How the Private Worker Transport Fence Sessions to a Supervisor Generation in Prime Agent

Private workers in Prime Agent use a three-stage transport fence—capability advertisement, fence token generation, and session fence registration—to securely hand off session ownership to the supervisor's current generation via direct peer-to-peer sockets.

The PrimeIntellect-ai/prime-agent repository implements a daemon architecture that separates session workers from the daemon supervisor that owns the socket generation. When a private worker starts, it must transfer its session information to the supervisor in a way that guarantees the supervisor's generation is aware of the session while preventing stale or rogue workers from claiming it. This hand-off is performed through the private worker transport fence.

How the Private Worker Transport Fence Works

The transport fence operates through three distinct stages that move session data from the worker to the supervisor generation.

Stage 1: Capability Advertisement

When a worker connects to the supervisor, it advertises its capabilities through the workerAuthAdvertisesPeerTransport function in daemon-supervisor.ts. The supervisor checks the capabilities array for the DAEMON_WORKER_PEER_TRANSPORT_CAPABILITY flag. If present, the supervisor records that this worker supports peer transport and can later receive a fenced transport ticket.

This capability check occurs at daemon-supervisor.ts:L75-L78, where the supervisor validates that the worker is authorized to request direct transport.

Stage 2: Fence Token Generation

Upon receiving a get_direct_worker_transport command, the supervisor creates a DaemonPeerTransportTicket. This ticket contains the supervisor generation ID, a signed nonce, and the worker's authentication token. Defined in daemon-protocol.ts, the ticket serves as a one-time use token that authorizes the worker to open a direct peer-to-peer socket.

The ticket generation bypasses the normal supervisor-mediated RPC path, allowing the worker to establish a raw socket connection for high-bandwidth session data transfer.

Stage 3: Session Fence Registration

The worker uses the ticket to open a direct socket and streams its session snapshot and heartbeat data straight to the supervisor. The supervisor validates the ticket through verifyPeerTransportTicket, checking that the generation ID, socket path, and token match.

Once validated at daemon-supervisor.ts:L398-L410, the supervisor calls registerSessionUnderGeneration to register the session under this.generation. From this point, the session is owned by that supervisor generation, and subsequent RPCs route through the fenced channel. If the supervisor restarts (creating a new generation), the fence automatically tears down, forcing the worker to request a new ticket.

Why the Transport Fence is Required

The private worker transport fence solves three critical problems in distributed session management.

Generation Safety: The supervisor's generation UUID (this.generation) is unique per process start. By binding the transport ticket to this UUID, workers cannot attach to stale supervisors after a restart, preventing session hijacking across process boundaries.

Direct Data Path: Session snapshots can contain large transcript files. Sending these over the normal JSON-RPC channel would introduce significant latency and encoding overhead. The fenced peer-transport uses raw sockets, avoiding JSON encodings and reducing latency for bulk data transfer.

Isolation: Only workers possessing the correct DAEMON_WORKER_AUTH_TOKEN and advertising the peer-transport capability receive tickets. This cryptographic validation prevents rogue processes from registering sessions they do not own.

Implementation Examples

Requesting a Fenced Transport from a Private Worker

Inside the private session worker, the client requests a direct transport ticket and opens the fenced connection:

// packages/coding-agent/src/session-worker/...
import { DaemonWorkerClient } from '../daemon/daemon-worker-client.js';

// 1. Request direct transport ticket from supervisor
const transportResp = await daemonClient.requestWorker(
  { type: 'get_direct_worker_transport' },
  WORKER_REQUEST_TIMEOUT_MS,
);

// 2. Validate supervisor response
if (!transportResp?.success) {
  throw new Error(`Failed to get transport ticket: ${transportResp?.error}`);
}
const ticket = transportResp.data as DaemonPeerTransportTicket;

// 3. Open direct socket using the fenced ticket
await daemonClient.openDirectPeerTransport(ticket);

// 4. Stream session snapshot over the direct socket
await daemonClient.sendSnapshot(sessionSnapshot);

Supervisor Ticket Handling and Validation

In the DaemonSupervisor class, the supervisor generates tickets and validates incoming fenced connections:

// packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
if (command.type === 'get_direct_worker_transport') {
  const ticket = this.createPeerTransportTicket(worker.descriptor);
  return { success: true, data: ticket };
}

// On incoming direct connection:
this.verifyPeerTransportTicket(incomingTicket); // Validates generation, socketPath, token
this.registerSessionUnderGeneration(sessionInfo, incomingTicket.supervisorGeneration);

Key Source Files

The transport fence implementation spans several files in the Prime Agent codebase:

• packages/coding-agent/src/modes/daemon/daemon-supervisor.ts: Core supervisor logic including capability validation, ticket generation, and session registration under the current generation.
• packages/coding-agent/src/modes/daemon/daemon-worker-protocol.ts: Protocol definitions for DAEMON_WORKER_PEER_TRANSPORT_CAPABILITY and the DaemonPeerTransportTicket interface.
• packages/coding-agent/src/session-worker/private-framing.ts: Worker-side implementation that constructs PrivateFrame objects to carry fence tickets and session snapshots over direct sockets.
• packages/coding-agent/src/modes/daemon/daemon-protocol.ts: General daemon protocol definitions including command types used during the fence handshake.
• packages/coding-agent/test/session-worker-private-framing.test.ts: Integration tests that verify private workers can successfully fence sessions to supervisor generations.

Summary

• The private worker transport fence uses a three-stage handshake: capability advertisement, ticket generation, and session registration.
• The DaemonPeerTransportTicket binds the worker to a specific supervisor generation UUID, preventing stale attachments after process restarts.
• Direct peer-to-peer sockets bypass JSON-RPC overhead, enabling efficient transfer of large session snapshots.
• File locations include daemon-supervisor.ts for validation logic and private-framing.ts for worker-side frame construction.

Frequently Asked Questions

What is a transport fence in Prime Agent?

A transport fence is a security boundary that allows private session workers to transfer ownership of their sessions to the current supervisor generation through cryptographically signed tickets and direct socket connections. It ensures that only authorized workers can register sessions and that these registrations are tied to a specific supervisor process instance.

How does the supervisor prevent stale workers from attaching after a restart?

The supervisor embeds its unique generation UUID (this.generation) into every DaemonPeerTransportTicket. When validating an incoming fence connection via verifyPeerTransportTicket, the supervisor rejects any ticket bearing a mismatched generation ID. After a restart, the generation UUID changes, invalidating all previously issued tickets and forcing workers to request new ones.

Why use direct sockets instead of JSON-RPC for session data?

Session snapshots can contain large transcript files that would cause significant serialization overhead and latency if encoded as JSON-RPC messages. The transport fence creates a raw binary socket channel that avoids JSON encoding, reducing memory pressure and transmission time for bulk session data while maintaining the RPC channel for control commands.

What happens if a transport ticket verification fails?

If verifyPeerTransportTicket detects a mismatch in the generation ID, socket path, or authentication token, the supervisor immediately closes the connection and refuses to register the session. The worker must then request a fresh ticket through the get_direct_worker_transport command, ensuring that only valid, current tokens can establish fenced sessions.

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