# What Is JIT Ensurance in Magnitude's ACN Startup?

> Discover Magnitude's JIT ensurance, a just-in-time mechanism ensuring your ACN daemon is ready when the SDK needs it, eliminating pre-start infrastructure.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: internals
- Published: 2026-09-06

---

**JIT ensurance is Magnitude's just-in-time mechanism that guarantees the ACN (Agent Connection Node) daemon is running and ready exactly when the SDK needs it, eliminating the need for pre-started infrastructure.**

The Magnitude framework takes a composable, **effect-driven** approach to agent orchestration. Rather than requiring practitioners to manage daemon lifecycles manually, the SDK handles ACN startup automatically through its JIT ensurance system. This article explains how this architecture works, where the critical code lives, and how to leverage it in your applications.

## How JIT Ensurance Works

JIT ensurance operates as a three-layer coordination system that bridges the gap between "no daemon running" and "ready to serve RPC calls."

### AcnEnsuranceCoordinator: The Central Scheduler

The [`AcnEnsuranceCoordinator`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-ensurance-coordinator.ts) sits at the heart of the system. This service:

- **Serializes** multiple concurrent "ensure" requests for the same target
- Maintains an **ensure-stream** that emits lifecycle events: `starting`, `ready`, `failed`
- Prevents redundant daemon startups when multiple callers request the same ACN instance simultaneously

By centralizing coordination in `packages/daemon-management`, Magnitude decouples policy (when to start) from mechanics (how to start).

### LocalAcnInstanceManager: The Public API

SDK consumers interact with JIT ensurance through [`LocalAcnInstanceManager.ensure()`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/local-acn-instance-manager.ts). This method:

1. Acquires a **Scope** for resource cleanup
2. Invokes the coordinator to create or reuse an ensure-stream
3. Returns an **Effect** that resolves to a handle containing the RPC client

The signature follows Effect-TS conventions, enabling seamless composition with retries, timeouts, and error handling.

```typescript
// Example: Ensuring an ACN instance with retry policy
const acnManager = yield* Effect.service(AcnInstanceManager.Tag);

const acnHandle = yield* acnManager.ensure({
  target: "default",        // Identifies which daemon configuration to use
  dataDir: "/tmp/acn-data", // Optional: custom working directory
  version: "1.2.0"          // Optional: specific daemon version
}).pipe(
  Effect.retry({ schedule: Schedule.exponential("1 second", 2) }),
  Effect.timeout("30 seconds")
);

```

### RecoveringStreamProtocol: Fault Tolerance

The [`RecoveringStreamProtocol`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/jit-rpc/recovering-stream-protocol.ts) layer ensures that transient daemon failures don't break ongoing work. For each RPC call, this protocol:

- Injects an `x-magnitude-acn-id` header identifying the ensured instance
- Detects connection failures mid-request
- **Automatically re-invokes** `ensure()` to restart the daemon if needed
- Retries the original request with the new instance

This recovery happens transparently to application code.

## Key Design Principles

Magnitude's JIT ensurance embodies several architectural decisions:

| Principle | Implementation |
|-----------|---------------|
| **Lazy evaluation** | Daemons start only when first requested, not at SDK initialization |
| **Idempotency** | Multiple `ensure()` calls for the same target share one startup sequence |
| **Composability** | Returns standard Effect values, enabling custom retry/backoff policies |
| **Resource safety** | Scopes ensure proper cleanup on shutdown or cancellation |
| **Observability** | Event streams expose detailed lifecycle information |

## Complete Usage Example

Here's a production-ready pattern for consuming a JIT-ensured ACN:

```typescript
import { Effect, Schedule, Exit } from "effect";
import { AcnInstanceManager } from "@magnitude/sdk/acn-jit";

const program = Effect.gen(function* ($) {
  // 1. Acquire the manager from the Effect context
  const manager = yield* $(AcnInstanceManager.Tag);
  
  // 2. Ensure ACN with aggressive retry for CI environments
  const handle = yield* $(
    manager.ensure({ target: "production" }).pipe(
      Effect.retry({ times: 5, schedule: Schedule.spaced("2 seconds") })
    )
  );
  
  // 3. Use the typed RPC client
  const catalog = yield* $(handle.client.models.getCatalog({}));
  
  // 4. Perform work...
  const result = yield* $(processModels(catalog.models));
  
  // 5. Explicit cleanup (or let Scope handle it)
  yield* $(handle.close);
  
  return result;
});

// Execute with concrete logger and configuration
Effect.runPromise(program.pipe(
  Effect.provide(AcnInstanceManager.live),
  Effect.tapErrorCause(Effect.logError)
));

```

## Architecture Integration

JIT ensurance plugs into Magnitude's broader effect system at three integration points:

1. **CLI layer** — [[`packages/cli/src/server/acn-connection.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/cli/src/server/acn-connection.ts)](https://github.com/magnitudedev/magnitude/blob/main/packages/cli/src/server/acn-connection.ts) bootstraps the first ensure call when a user runs magnitude commands

2. **SDK client surface** — [[`packages/sdk/src/client.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/client.ts)](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/client.ts) exposes RPC methods that internally depend on ensured ACN instances

3. **Daemon lifecycle** — The coordinator communicates with platform-specific process managers to actually spawn the ACN binary

## Comparison: JIT vs. Pre-Started Daemons

| Approach | Resource Usage | Startup Latency | Operational Complexity |
|----------|-------------|-----------------|----------------------|
| **JIT ensurance** | Minimal (zero when idle) | First call pays startup cost | Low (self-managing) |
| Pre-started daemon | Constant baseline | Zero | High (health checks, restarts, versioning) |

JIT ensurance suits development workflows, serverless deployments, and resource-constrained environments. Pre-started daemons may be preferable for latency-sensitive production paths where warm pools are pre-provisioned.

## Summary

- **JIT ensurance** delays ACN daemon startup until the first RPC request, minimizing idle resource consumption
- The [`AcnEnsuranceCoordinator`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-ensurance-coordinator.ts) centralizes lifecycle management and prevents duplicate startups
- [`LocalAcnInstanceManager.ensure()`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/local-acn-instance-manager.ts) provides the composable Effect-based API
- [`RecoveringStreamProtocol`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/jit-rpc/recovering-stream-protocol.ts) adds transparent fault recovery without application code changes
- The entire system is built on Effect-TS, enabling custom retry policies, resource scoping, and type-safe error handling

## Frequently Asked Questions

### What happens if the ACN daemon crashes during a request?

The [`RecoveringStreamProtocol`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/jit-rpc/recovering-stream-protocol.ts) detects the disconnection, automatically invokes `ensure()` to restart the daemon, and retries the failed request with the new instance. This recovery is transparent to application code unless you specifically observe the event stream.

### Can I run multiple ACN instances with different configurations?

Yes. The `target` parameter in `ensure()` acts as a unique key. Each distinct target receives its own isolated daemon process and lifecycle management. Pass different `dataDir`, `version`, or environment variables per target to run side-by-side configurations.

### How do I customize the retry behavior for daemon startup?

Since `ensure()` returns a standard Effect, you can apply any Effect retry strategy. Use `Effect.retry()` with `Schedule.exponential()` for backoff, `Schedule.spaced()` for fixed intervals, or compose schedules for sophisticated patterns. The default implementation includes sensible defaults but imposes no policy.