How the Backpressure Mechanism Works at the Daemon Attachment Level

Prime-Agent’s daemon-supervisor prevents event loss by marking clients as backpressured when socket.write() returns false, queuing critical snapshots until the underlying TCP socket emits a drain event.

Prime-Agent’s daemon-supervisor coordinates high-throughput session events across numerous concurrent socket connections. When a client’s TCP socket cannot accept more data, the backpressure mechanism at the daemon attachment level activates to pause event streaming without dropping state changes. This design guarantees at-least-once delivery of roster updates and session snapshots while preventing memory exhaustion on the server.

Architecture Overview

The backpressure implementation spans three coordinated components within the daemon codebase:

• DaemonSocketClient – A per-client state object defined in src/modes/daemon/active-session-state.ts that maintains a backpressured boolean flag.
• writeSnapshotBuffer – A low-level helper in src/modes/daemon/daemon-supervisor.ts that detects write failures and triggers queuing logic.
• Drain event listener – A socket lifecycle handler in the same supervisor file that clears backpressure and flushes queued data.

Each component ensures that flow control respects the kernel’s socket buffer limits while maintaining session consistency.

The Backpressure Detection Flow

When a client attaches to the daemon, the supervisor executes a precise sequence to handle slow consumers:

1. Client attachment – The supervisor instantiates a DaemonSocketClient and begins broadcasting DaemonOutbound frames via writeSnapshotBuffer.
2. Write failure detection – If client.socket.write(buffer) returns false, the kernel buffer is full. The supervisor immediately sets client.backpressured = true and suspends incremental event streaming.
3. Roster resync queuing – The code at src/modes/daemon/daemon-supervisor.ts:1495-1497 queues a full-roster resync, leveraging the comment logic: // socket.write queues even when it reports backpressure: one resync per loss gap.
4. Snapshot catch-up – While backpressured, the daemon populates client.catchupActiveSessionIds and waits, ensuring the client receives a consistent state snapshot rather than a partial event stream.
5. Drain and flush – When the OS buffer empties, the socket emits a drain event. The supervisor clears client.backpressured at src/modes/daemon/daemon-supervisor.ts:4223-4225 and streams the queued snapshot or roster resync.

If a client remains backpressured beyond a threshold, the supervisor aborts the connection to prevent resource leaks, as validated in the regression test suite.

Implementation Deep Dive

DaemonSocketClient State Tracking

The DaemonSocketClient interface stores the backpressure flag alongside attachment metadata. According to src/modes/daemon/active-session-state.ts:20-23, this boolean gates roster resyncs and snapshot catch-up logic, ensuring no new data streams until the flag clears.

writeSnapshotBuffer and Write Failures

The writeSnapshotBuffer method implements the critical check:

const ok = client.socket.write(buffer);
if (!ok) client.backpressured = true;

This logic appears at lines 1495-1497 of daemon-supervisor.ts. When ok is false, the method does not drop the frame; instead, it signals the supervisor to queue a full state resync that will replace the lost incremental events.

Drain Event Handling

The recovery mechanism listens for the drain event on the net.Socket instance. The handler at lines 4223-4225 resets the backpressure state and immediately invokes the catch-up streaming function. This ensures clients receive a consistent snapshot of attachedActiveSessionIds before processing new real-time events.

Practical Code Examples

The following patterns demonstrate how the daemon manages backpressure programmatically:

// Creating a test client that mimics a real socket
function socketClient(id: string): DaemonSocketClient {
  const socket = new PassThrough();
  return {
    id,
    socket: socket as unknown as Socket,
    attachedActiveSessionIds: new Set([activeSessionId]),
    catchupActiveSessionIds: new Set(),
    detachInput: () => {},
    supportsExtensionUi: false,
    capabilities: new Set(["chunked_snapshot"]),
  };
}

// Low-level write with backpressure detection
function writeSnapshotBuffer(client: DaemonSocketClient, buffer: Uint8Array) {
  const ok = client.socket.write(buffer);
  if (!ok) {
    client.backpressured = true;  // Flag set when kernel buffer is full
    // Queue resync logic here...
  }
  return Promise.resolve(ok);
}

// Drain listener installation per client
client.socket.on("drain", () => {
  client.backpressured = false;  // Clear flag
  
  // Flush queued snapshot if exists
  if (client.catchupPromise) {
    client.catchupPromise = streamQueuedSnapshot(client);
  }
});

These examples mirror the implementation found in packages/coding-agent/test/suite/regressions/4677-snapshot-catchup-replacement.test.ts, which validates the behavior under simulated load.

Summary

• Detection: The daemon detects backpressure when socket.write() returns false, setting client.backpressured = true in active-session-state.ts.
• Queuing: Instead of dropping events, the supervisor queues a full-roster resync and pending snapshots via writeSnapshotBuffer in daemon-supervisor.ts.
• Recovery: The drain event handler clears the backpressure flag and flushes queued state, ensuring clients receive catch-up snapshots at lines 4223-4225.
• Safety: Persistent backpressure triggers connection termination to prevent resource exhaustion, as tested in the regression suite.

Frequently Asked Questions

What triggers the backpressure mechanism in Prime-Agent’s daemon?

When the supervisor calls socket.write() to broadcast session events, a return value of false indicates the kernel’s TCP send buffer is full. This triggers the mechanism, setting the backpressured flag on the DaemonSocketClient instance and pausing incremental event streaming until the buffer drains.

How does the daemon ensure no data loss during backpressure events?

Rather than dropping frames, the daemon queues a full-roster resync and any pending snapshots. The comment at daemon-supervisor.ts:1495-1497 explicitly notes that the system queues "one resync per loss gap," ensuring the client receives a complete state snapshot once the socket becomes writable again.

What happens if a client remains backpressured for an extended period?

The supervisor monitors the duration of backpressure states. If a client cannot accept data within the configured timeout window, the daemon forcibly terminates the connection to prevent memory leaks and zombie sockets, as validated in regression test 4677-snapshot-catchup-replacement.test.ts.

Where is the backpressure state stored for each connected client?

The state resides in the DaemonSocketClient interface defined at src/modes/daemon/active-session-state.ts:20-23. This object tracks the backpressured boolean alongside attachment IDs and capability flags, making it accessible to both the write buffer logic and the drain event handlers in daemon-supervisor.ts.

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