One sidecar per Claude session owns the session's harness turns

actor

The mod of one Claude session.

problem

A harness turn outlives any single step or hook call, and its capacity, events and cleanup must not depend on a Claude Code process that can reload its mods or die.

outcome

A process per session keeps each agent's turn and its events until the mod reads them, runs the turn through the adapter, and ends everything it started when its owner is gone.

value

A mod reload or crash does not lose a running turn, and no turn outlives the session that started it.

Open questions

• non-blocking · question.idleExit line 29 · specs/runner/sidecar.sdp.md:29 · The sidecar also exits two minutes after its last turn and its last waiting spawn, refuses a second concurrent turn for the same agent, and fails a turn whose preparation fails without running it; no test pins any of the three.Decider: delegatedProvisional: Both are as built.
• non-blocking · question.insideTheProcess line 32 · specs/runner/sidecar.sdp.md:32 · The README says the agents run inside the Claude Code process, while the code runs them in a detached sidecar and separate harness processes whose lifetime is tied to the host.Decider: ownerProvisional: The code is the truth; the README sentence needs a correction in the documents.

rule.privateSocket line 38 · specs/runner/sidecar.sdp.md:38

The sidecar listens only on a Unix socket mode 0600 in a directory mode 0700 that belongs to the user, and refuses to start in a directory that others can enter.

no example exercises it

rule.exitsWithOwner line 39 · specs/runner/sidecar.sdp.md:39

The sidecar exits when its owner, the Claude Code process that started it, is gone, and a sidecar that stops mid-turn takes the harness and its commands with it.

no example exercises it

rule.knowsNoHarness line 40 · specs/runner/sidecar.sdp.md:40

The sidecar loads an adapter by the harness's name from its adapters folder, accepts only names of lowercase letters, digits and hyphens, and refuses a harness with no adapter.

no example exercises it

rule.checkBeforeStart line 41 · specs/runner/sidecar.sdp.md:41

A check resolves the model and effort the turn will run with, refuses what the harness cannot do with the values that would work, and answers with the turn's cap key and cap.

no example exercises it

rule.eventsKept line 42 · specs/runner/sidecar.sdp.md:42

The sidecar keeps an agent's events and serves them by a cursor, as a long poll that answers at once when events are past the cursor.

no example exercises it

rule.oneAttempt line 43 · specs/runner/sidecar.sdp.md:43

A turn runs once: a failure the harness reports ends the turn as it comes and is never replayed, because the harness retries on its own.

no example exercises it

rule.preparedBeforeRun line 44 · specs/runner/sidecar.sdp.md:44

The adapter prepares the turn and its work is recorded in the turn's slot before anything is submitted.

no example exercises it

rule.leaseInterrupts line 45 · specs/runner/sidecar.sdp.md:45

A turn whose events nobody has read within the lease is interrupted.

no example exercises it

rule.waitsVisibly line 46 · specs/runner/sidecar.sdp.md:46

A turn over its cap, or refused by the machine guard, waits and says why once as a status line, and starts when a slot frees or the machine eases.

no example exercises it

rule.statusForViews line 47 · specs/runner/sidecar.sdp.md:47

A status answer gives the session's agents, every cap key's use counted machine-wide, the spawns waiting for a slot, and the machine's sample.

no example exercises it

rule.remembersAgents line 48 · specs/runner/sidecar.sdp.md:48

The sidecar writes each agent's settings to a file in its run directory, so a reloaded mod can ask for them, and remembers Workflow roles by run id and position across sessions.

no example exercises it

0 unkeyed rules.

startCommand line 52 · specs/runner/sidecar.sdp.md:52

node launch.mjs --dir <run dir> --sock <socket> --state <state dir>; the sidecar's owner is the launcher's parent.

no citation recorded

endpoints line 53 · specs/runner/sidecar.sdp.md:53

GET /health, POST /check, POST /reserve, POST /release, POST /register, POST /start, GET /events, POST /steer, POST /interrupt, GET /status, GET /agent, POST /resume-lookup.

no citation recorded

turnStates line 54 · specs/runner/sidecar.sdp.md:54

waiting, preparing, submitted, running, stopping, confirmed-ended.

no citation recorded

environment line 55 · specs/runner/sidecar.sdp.md:55

CC_AGENTS_STATE names the state directory, CC_AGENTS_LEASE_MS the lease, CC_AGENTS_MACHINE another machine-guard module, for tests.

no citation recorded

runDirectory line 56 · specs/runner/sidecar.sdp.md:56

<state>/run/<first 12 characters of the session id>, holding the socket, the log and the agents file.

no citation recorded

Verifier bindings

• test:cc-agents.sidecar-suite · the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored · test anchor binding present · tests/sidecar.test.mjs:4

Requirement drawing

• Declared verifying examples: no declared verifying example.

Decisions

No decision record named.

• impl:cc-agents.launch · starts the sidecar detached and returns once it answers on its socket · plugin/sidecar/launch.mjs:7

  Uses

  None.

• impl:cc-agents.sidecar · the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · plugin/sidecar/server.mjs:12

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.