How the RLM Child Registry Survives Kernel Restarts in Prime Agent

The RLM child registry persists across kernel restarts by writing child session metadata to an on-disk ledger and reconstructing the in-memory registry from that ledger during kernel initialization.

The Recursive Language Model (RLM) architecture in PrimeIntellect-ai/prime-agent enables parent sessions to spawn isolated child sessions for delegated tasks. Ensuring the RLM child registry survives unexpected Python kernel crashes requires a durable persistence layer that maintains the relationship between parent and child sessions across process lifecycles.

On-Disk Ledger Architecture

The foundation of registry durability lies in incremental disk persistence implemented in packages/coding-agent/src/modes/daemon/rlm-ledger.ts.

Incremental Metadata Logging

When an RLM child spawns, the daemon immediately records its metadata to a ledger file within the session's artifact directory. This entry includes the session ID, child ID, timestamps, and cumulative token usage. The ledger writes append-only increments during child execution, ensuring that even if the kernel crashes mid-operation, the disk already contains a durable record of the child's existence and state.

// Conceptual flow during child spawn
const child = await parentSession.spawnRlmChild({
  model: "gpt-4",
  prompt: "Refactor this function",
});
// Ledger entry written here before execution begins
await child.run(); // Incremental usage updates written during execution

Runtime Registry Exposure

While the kernel is active, the registry maintains in-memory references through a dedicated runtime bridge.

RlmRuntime Integration

The RlmRuntime class in packages/coding-agent/src/core/rlm-runtime.ts exposes the direct RLM child registry to the executing kernel. As noted in the source comment "Expose the current parent session's direct RLM child registry to its kernel," this object holds live references to active AgentSessionRuntime instances while the kernel process remains alive.

// Kernel access to live registry
const rlmRuntime = new RlmRuntime(parentSession);
const childRegistry = rlmRuntime.getChildRegistry(); // Live references

Kernel Recovery and Rehydration

When the kernel restarts, a reconstruction protocol executes before message processing resumes.

Ledger Scanning and Runtime Reconstruction

The ReplKernelManager executes bootstrap logic defined in packages/coding-agent/src/modes/daemon/daemon-protocol.ts. This process reads the "Live RLM child sessions (including grandchildren) hosted by the daemon under this session" section from the ledger. For each persisted entry, the kernel instantiates new AgentSessionRuntime objects, attaching the recorded usage and status to recreate the exact registry state present before the crash.

// Kernel startup sequence
await kernelManager.start(); // Reads ledger from artifact directory
// Registry restored here without losing child relationships
const restoredRegistry = parentSession.getRlmChildRegistry();

Heartbeat and Quiescence Restoration

The daemon maintains separate heartbeat tracking for RLM children independent of user session heartbeats. Upon kernel restart, the system restores pending heartbeat states from the ledger, ensuring that quiescence barriers and scheduling constraints remain enforced. This prevents orphaned children or premature termination during recovery scenarios.

Usage Aggregation and Session Management

The SessionManager in packages/coding-agent/src/core/session-manager.ts handles the final persistence layer for billing and metrics. When an RLM child run completes, the manager records usage statistics folded into the parent assistant message and immediately writes these aggregates to the ledger. This ensures token counts and execution metadata survive restarts without duplication or data loss.

Key Source Files

• packages/coding-agent/src/core/rlm-runtime.ts – Exposes the direct RLM child registry to the kernel runtime.
• packages/coding-agent/src/modes/daemon/rlm-ledger.ts – Handles incremental persistence of child session metadata.
• packages/coding-agent/src/modes/daemon/daemon-protocol.ts – Implements kernel bootstrap logic for live RLM child sessions.
• packages/coding-agent/src/core/session-manager.ts – Aggregates usage data into parent messages and ledger entries.
• packages/coding-agent/test/daemon-mode.test.ts – Validates persistence behavior across kernel restarts.

Summary

• The RLM child registry survives kernel restarts through a three-layer persistence strategy: on-disk ledgers, runtime exposure, and reconstruction logic.
• The ledger in rlm-ledger.ts writes child metadata incrementally to ensure crash safety.
• RlmRuntime provides the in-memory registry interface during active kernel sessions.
• Kernel restart triggers a reconstruction protocol in daemon-protocol.ts that rehydrates AgentSessionRuntime objects from the ledger before processing resumes.
• Usage aggregation and heartbeat states persist through the SessionManager, maintaining accurate billing and scheduling across restarts.

Frequently Asked Questions

Where is the RLM child registry state stored between restarts?

The registry persists state in an on-disk ledger file located within the session's artifact directory, as implemented in packages/coding-agent/src/modes/daemon/rlm-ledger.ts. This ledger records session IDs, child IDs, timestamps, and usage incrementally to ensure durability even if the kernel crashes mid-write.

How does the kernel reconstruct the child registry after a restart?

During initialization, the ReplKernelManager reads the persisted ledger entries and reconstructs AgentSessionRuntime objects for each recorded child. This process, defined in packages/coding-agent/src/modes/daemon/daemon-protocol.ts, executes before any new message processing begins, ensuring the kernel sees an identical registry state to pre-restart.

What prevents usage data loss when an RLM child session restarts?

The SessionManager component immediately writes usage statistics to the ledger when an RLM child run completes, folding this data into the parent assistant message. Because this write occurs before acknowledging completion, the usage aggregates survive restarts without duplication.

Are quiescence barriers maintained across kernel restarts?

Yes. The daemon's heartbeat system restores pending heartbeat states from the ledger during kernel re-initialization, ensuring that quiescence barriers and scheduling constraints for RLM children remain enforced even after unexpected crashes.

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