How Magnitude Manages the ACN Lifecycle: Launch, Health Checks, and Shutdown Timings Explained

Magnitude orchestrates the Agent Compute Node (ACN) through four coordinated phases—launch, readiness verification, active running, and graceful shutdown—each governed by configurable timeouts and dedicated supervisor components.

The ACN lifecycle is central to Magnitude's architecture for just-in-time daemon management. Rather than running a persistent background service, Magnitude spawns short-lived ACN processes on demand, ensures they reach a healthy state before use, monitors their activity, and reclaims them when idle. This article examines the exact mechanisms, source file implementations, and timing parameters that control this orchestration.

The Four Phases of ACN Lifecycle Management

According to the magnitudedev/magnitude source code, the ACN lifecycle flows through distinct phases managed by specialized components in packages/daemon-management/src/acn-jit/.

Launch Phase: Deciding When to Spawn

The AcquisitionEnsuranceCoordinator (acn-ensurance-coordinator.ts) determines when a new ACN instance is required. It evaluates criteria such as:

• No existing ACN currently registered
• Previous instance has terminated or become unreachable
• A pending user request requires compute resources

When conditions are met, the coordinator delegates to the AcquisitionCandidateLaunchSupervisor to begin the actual process spawn.

Readiness Phase: Health Check and Registration

The AcquisitionCandidateLaunchSupervisor (acn-candidate-launch-supervisor.ts) executes the launch sequence:

1. Resolves the binary path and arguments via AcnDaemonLaunchCommandResolver
2. Spawns the process using Node's child_process
3. Polls the HTTP /health endpoint until it returns healthy
4. Registers the x-magnitude-acn-id in shared state for SDK routing

Timing Parameter	Default	Purpose
ACN_LAUNCH_TIMEOUT_MS	5000	Maximum wait for health endpoint response
ACN_MAX_RETRIES	3	Launch attempts before abandonment

If health checks fail within the timeout window, the supervisor retries up to the configured maximum. All retries exhausted results in a rejected promise propagated to the caller.

Running Phase: Activity Monitoring

Once healthy, the AcquisitionOwnerObserver (acn-owner-observer.ts) assumes responsibility:

• Maintains periodic heartbeat checks via /ping endpoint
• Tracks active session usage count
• Detects shutdown signals (OS SIGTERM, manual stop requests)
• Emits idle-timeout events when no sessions remain

Timing Parameter	Default	Purpose
ACN_IDLE_TIMEOUT_MS	30000	Duration of inactivity before shutdown trigger

The observer implements a reference-counting mechanism: each active RPC session increments the count, and when all sessions close, the idle timer begins.

Shutdown Phase: Graceful Termination

The AcquisitionDaemonShutdownSupervisor (acn-daemon-shutdown-supervisor.ts) handles termination:

1. Sends SIGTERM to the ACN process
2. Waits for graceful exit or timeout
3. Escalates to SIGKILL if necessary
4. Clears instance ID from shared state

Timing Parameter	Default	Purpose
ACN_SHUTDOWN_GRACE_MS	10000	Grace period after SIGTERM
ACN_SHUTDOWN_FORCE_MS	2000	Additional wait before SIGKILL

Central Orchestration: AcquisitionInstanceManager

The AcquisitionInstanceManager (acn-instance-manager.ts) binds these phases into a unified interface. Its public API exposes two primary methods:

• acquire(): Returns a promise that resolves when the ACN is healthy and ready for RPC calls
• release(): Signals that the ACN can be shut down, either immediately or after idle timeout

The manager internally coordinates:

• Launch requests to the AcquisitionEnsuranceCoordinator
• Readiness promise resolution from AcquisitionCandidateLaunchSupervisor
• Lifetime observation via AcquisitionOwnerObserver
• Shutdown delegation to AcquisitionDaemonShutdownSupervisor

Practical Usage Examples

Starting and Using an ACN Instance

// packages/sdk-common/src/connection/acn-bootstrap.ts
import { makeAcnInstanceManager } from "@magnitudedev/daemon-management";

const acnManager = makeAcnInstanceManager({
  launchTimeoutMs: 5_000,
  idleTimeoutMs: 30_000,
});

async function initializeWork() {
  // Triggers launch if needed, waits for health check
  const acnId = await acnManager.acquire();
  console.log(`ACN ready with ID: ${acnId}`);
  
  // SDK automatically routes RPC calls to this instance
  const projects = await rpc.projectManager.list({});
  return projects;
}

Configuring Environment Variables

# .env or process environment

ACN_LAUNCH_TIMEOUT_MS=10000      # Slower machines need more time

ACN_IDLE_TIMEOUT_MS=60000        # Keep alive longer for burst workloads

ACN_SHUTDOWN_GRACE_MS=15000      # Allow more cleanup time

ACN_SHUTDOWN_FORCE_MS=5000       # Delay before forced kill

Manual Shutdown Trigger

// Explicit release, bypassing idle timeout
await acnManager.release({ immediate: true });

// Or let idle timeout handle it naturally
await acnManager.release();  // Returns immediately, shutdown follows idle period

Key Source Files and Responsibilities

File Path	Component	Lifecycle Responsibility
packages/daemon-management/src/acn-jit/acn-instance-manager.ts	AcquisitionInstanceManager	Central API coordinating all phases
packages/daemon-management/src/acn-jit/acn-ensurance-coordinator.ts	AcquisitionEnsuranceCoordinator	Launch decision logic
packages/daemon-management/src/acn-jit/acn-candidate-launch-supervisor.ts	AcquisitionCandidateLaunchSupervisor	Process spawn and health verification
packages/daemon-management/src/acn-jit/acn-owner-observer.ts	AcquisitionOwnerObserver	Runtime monitoring and idle detection
packages/daemon-management/src/acn-jit/acn-daemon-shutdown-supervisor.ts	AcquisitionDaemonShutdownSupervisor	Graceful and forced termination
packages/daemon-management/src/acn-jit/acn-daemon-launch-command-resolver.ts	AcnDaemonLaunchCommandResolver	Binary path and argument resolution
packages/acn-protocol/src/boundary/acn.ts	RPC boundary definitions	Contract between SDK and running ACN

Summary

• Four phases govern the ACN lifecycle: launch decision, readiness verification, active operation, and shutdown reclamation
• Five configurable timings control behavior: ACN_LAUNCH_TIMEOUT_MS, ACN_MAX_RETRIES, ACN_IDLE_TIMEOUT_MS, ACN_SHUTDOWN_GRACE_MS, and ACN_SHUTDOWN_FORCE_MS
• AcquisitionInstanceManager in acn-instance-manager.ts serves as the primary interface for SDK consumers
• Graceful degradation is built in: retries on launch failure, escalating signals on shutdown, and automatic cleanup of orphaned state

Frequently Asked Questions

What triggers the ACN to launch?

The AcquisitionEnsuranceCoordinator evaluates need based on request demand and existing instance state. No persistent daemon runs; each compute session begins with an explicit acquire() call that may trigger fresh process spawn.

How does Magnitude ensure an ACN is ready before use?

The AcquisitionCandidateLaunchSupervisor polls the /health endpoint until success or timeout. Only after this verification does acquire() resolve, guaranteeing that subsequent RPC calls reach a functional service.

Can I adjust how long the ACN stays running?

Yes. Set ACN_IDLE_TIMEOUT_MS to control inactivity duration before automatic shutdown. For persistent workloads, increase this value; for resource-constrained environments, decrease it to reclaim memory faster.

What happens if the ACN process hangs during shutdown?

The AcquisitionDaemonShutdownSupervisor implements a two-stage termination: SIGTERM followed by ACN_SHUTDOWN_GRACE_MS wait, then SIGKILL if still running. This prevents zombie processes while allowing cleanup routines to execute.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}