# JIT Spawning Model for the Agent Container Daemon (ACN) in Magnitude: Exact-Once Process Management

> Discover Magnitude's JIT spawning model for the agent container daemon (ACN). Learn how AcnInstanceManager ensures exact-once creation and guarantees a single ready instance.

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

---

**Magnitude uses a Just-In-Time (JIT) ensurance model driven by AcnInstanceManager to guarantee exact-once creation of ACN daemons, ensuring clients receive a single ready instance matching a specific revision through a finite-state machine lifecycle.**

The **magnitudedev/magnitude** repository implements a sophisticated container orchestration mechanism that treats ACN lifecycle management as a stream-based coordination problem. The JIT spawning model for the agent container daemon (ACN) in Magnitude ensures that clients obtain precisely one healthy daemon instance per data root, eliminating race conditions through deterministic state transitions and SQLite-backed ownership records.

## How the JIT Ensurance Model Works

### The Ensurance Request Flow

When a client requires an ACN instance, it invokes `AcnInstanceManager.ensure({ target })` with an `AcnTarget` encoding the desired revision. This method returns a stream of **AcnEnsureEvent** objects that represent the progression from request to resolution. According to the source code in [`packages/sdk/src/acn-jit/acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-instance-manager.ts), the manager transforms the target specification into a supervised lifecycle that guarantees exactly one terminal outcome.

### Candidate Launch and State Machine

If no existing ACN satisfies the target, the **AcnCandidateLaunchSupervisor** initiates a new process candidate. This supervisor implements a strict finite-state machine defined in [`packages/sdk/src/acn-jit/acn-candidate-launch-supervisor.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-candidate-launch-supervisor.ts), transitioning through `NotLaunched → Spawned → Admitted → Ready` (with an alternative terminal state of `Failed`). Each state change is observable and irreversible, ensuring deterministic lifecycle progression.

### Ownership and Identity Management

Every candidate binds to an `ExactProcess` identity and an `AcnIdentity` revision marker. The **AcnOwnerStore** persists this ownership relationship in SQLite, located in [`packages/acn/src/acn-subscriptions.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/acn-subscriptions.ts). A candidate becomes the legitimate owner only after the store confirms a successful **compare-and-replace** operation, preventing split-brain scenarios where multiple processes claim the same ACN slot.

### Admission and Readiness Verification

Once admitted, the **AcnDaemonShutdownSupervisor** (defined in [`packages/sdk/src/acn-jit/acn-daemon-shutdown-supervisor.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-daemon-shutdown-supervisor.ts)) monitors the candidate for graceful termination signals, escalating from `TERM` to `KILL` if necessary. Simultaneously, the system awaits an HTTP 200 health response and revision verification. Only upon confirming both process health and identity match does the manager emit an `AcnInstance<AcnReady>` event.

## Exact-Once Guarantees and Lifecycle Boundaries

### Single-Result Stream Resolution

The `runAcnEnsure` pipeline in [`packages/sdk/src/acn-jit/acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-instance-manager.ts) enforces a critical invariant: the ensurance stream resolves exactly once. It yields either a ready ACN instance or a typed terminal failure, failing explicitly if multiple readiness events appear. This design eliminates intermediate states like "starting" or "stopping" from the public API surface, presenting clients with a binary outcome.

### Separation of Concerns Across Six Authorities

As documented in [`design/acn/lifecycle/jit-spawning.md`](https://github.com/magnitudedev/magnitude/blob/main/design/acn/lifecycle/jit-spawning.md), the Magnitude SDK decomposes lifecycle control into six narrow authorities:

- **AcnOwnerObserver**: Reads owner and health state without mutation.
- **AcnConvergenceDecider**: Pure function mapping observations to actions, implemented in [`packages/sdk/src/acn-jit/acn-convergence-decider.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-convergence-decider.ts).
- **AcnDaemonShutdownSupervisor**: Owns graceful shutdown of existing daemons.
- **AcnCandidateLaunchSupervisor**: Owns the entire candidate lifecycle.
- **AcnDaemonLaunchCommandResolver**: Resolves launch commands without side effects.
- **AcnEnsuranceCoordinator**: Orchestrates the above components.

This separation isolates OS-level process-group control from ACN-specific business logic, implemented through effect-typed coordination primitives.

## Practical Implementation: Requesting an ACN Instance

The public API exposes the JIT spawning mechanism through Effect-TS streaming primitives. The following TypeScript demonstrates how to request a specific ACN revision and consume the resulting instance:

```typescript
import { AcnInstanceManager, AcnEnsureRequestSchema } from "@magnitudedev/sdk/acn-jit";
import { Effect } from "effect";

// 1️⃣ Request an ACN matching a specific revision
const request = AcnEnsureRequestSchema.encode({
  target: { revision: 42 }   // Desired ACN revision
});

// 2️⃣ Run the ensure stream – obtains a ready ACN or fails
const acnReady = Effect.gen(function* ($) {
  const stream = yield* $(AcnInstanceManager).ensure(request);
  return yield* $(AcnInstanceManager.runAcnEnsure(stream));
});

// 3️⃣ Use the ready instance (e.g., call an RPC)
acnReady.pipe(
  Effect.flatMap(acn => acn.rpc.someMethod({ /* … */ }))
);

```

This code triggers the full JIT spawning pipeline, including candidate supervision, ownership negotiation, and health verification, ultimately yielding an `AcnReady` instance suitable for RPC communication.

## Summary

- The JIT spawning model for the agent container daemon (ACN) in Magnitude guarantees **exact-once** instantiation per data root through the `AcnInstanceManager` API.
- State transitions follow a rigorous finite-state machine from `NotLaunched` to `Ready`, supervised by the `AcnCandidateLaunchSupervisor`.
- **SQLite-backed ownership** via `AcnOwnerStore` prevents duplicate daemons through atomic compare-and-replace operations.
- The architecture separates concerns into six distinct authorities, isolating process control from policy decisions.
- Clients interact with a binary outcome stream that resolves exactly once, eliminating ambiguity around daemon readiness.

## Frequently Asked Questions

### What triggers the JIT spawning of an ACN in Magnitude?

A client request via `AcnInstanceManager.ensure({ target })` triggers the process when no existing daemon matches the requested revision. The system lazily creates the candidate process only upon explicit demand, hence the Just-In-Time designation.

### How does Magnitude prevent duplicate ACN instances?

The `AcnOwnerStore` maintains authoritative ownership records in SQLite. A candidate process must successfully complete a compare-and-replace operation to claim ownership. The `runAcnEnsure` pipeline additionally fails if it detects multiple readiness events, ensuring at-most-one semantics.

### What happens if an ACN candidate fails during startup?

The `AcnCandidateLaunchSupervisor` FSM includes a terminal `Failed` state. If a candidate exits before reaching `Ready` or fails health checks, the stream emits a typed terminal failure. The client receives this error as the single resolution of the ensurance operation, allowing for explicit error handling without polling intermediate states.

### How is ACN ownership persisted across process restarts?

Ownership binds to an `ExactProcess` identity and revision marker stored in SQLite via [`packages/acn/src/acn-subscriptions.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/acn-subscriptions.ts). When the SDK restarts, the `AcnOwnerObserver` reads this persistent state to determine whether an existing valid owner exists, enabling seamless recovery without orphaned processes.