# How the Backpressure Mechanism Works at the Daemon Attachment Level

> Discover how Prime-Agent’s backpressure mechanism at the daemon attachment level prevents event loss by queuing critical snapshots until socket drain events occur.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: internals
- Published: 2026-09-05

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

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

```

This logic appears at lines 1495-1497 of [`daemon-supervisor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```typescript
// 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"]),
  };
}

```

```typescript
// 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);
}

```

```typescript
// 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts).