A critically loaded machine refuses new agents and stops none

spec:cc-agents.machine-guard

Use Case / Behavior · featureready floor ready

Packs: none

Design: 4 design entries · 4 pinned declarations · no decisions

specs/runner/machine-guard.sdp.md

No open questions and no blocking questions; implementation binding present, verifier binding present, and expected-outcome oracle none.

The machine guard is plugin/sidecar/machine.mjs. The sidecar asks it before it takes a slot. The caps keep one harness from taking every slot, and this guard keeps the machine itself from breaking.

Intent

actor: The sidecar that is about to start a turn.
problem: Many agents on one machine can drive it into swapping or a stall, and a plugin that merely counts turns cannot see that.
outcome: A new start waits, saying why, while the machine is critical, and every running turn goes on.
value: A fan-out cannot break the machine it runs on, at the price of a minimal sensor.

Behavior

rule.kernelSignalFirst line 22 · specs/runner/machine-guard.sdp.md:22: Memory is judged on the kernel's own pressure signal where there is one, macOS's pressure level or Linux's pressure stall information, and on available memory only as the fallback, because free memory alone misleads.
no example exercises it
rule.cpuNeedsMinutes line 23 · specs/runner/machine-guard.sdp.md:23: The CPU run queue makes the machine busy at 1.5 runnable threads per core over a minute and critical only at 4 per core over five minutes.
no example exercises it
rule.sharesNotNumbers line 24 · specs/runner/machine-guard.sdp.md:24: Every threshold is a share of this machine, of its memory or per core, never one machine's absolute numbers.
no example exercises it
rule.criticalOnly line 25 · specs/runner/machine-guard.sdp.md:25: A start is refused only while the machine is critical, with the reason, and a busy machine starts it.
no example exercises it
rule.waitingStart line 26 · specs/runner/machine-guard.sdp.md:26: A start the guard refuses waits, saying why, and runs once the machine is admitted.
no example exercises it
rule.neverRefuseBlind line 27 · specs/runner/machine-guard.sdp.md:27: Sensors that fail never refuse a start.
no example exercises it
rule.cached line 28 · specs/runner/machine-guard.sdp.md:28: The sample is measured at most once every two seconds.
no example exercises it
rule.worstReason line 29 · specs/runner/machine-guard.sdp.md:29: A reading with a memory and a CPU finding names the worse one, or both.
no example exercises it

0 unkeyed rules.

Design

levels line 33 · specs/runner/machine-guard.sdp.md:33: ok, busy, critical.
no citation recorded
sample line 34 · specs/runner/machine-guard.sdp.md:34: sample() returns { level, memory, cpu, reason }.
no citation recorded
admit line 35 · specs/runner/machine-guard.sdp.md:35: admit({ capKey }) returns { ok: true } or { ok: false, reason }.
no citation recorded
recordedReadings line 36 · specs/runner/machine-guard.sdp.md:36: CC_AGENTS_MACHINE_READINGS names a file of sensor readings, in the shape of the fixtures under tests/fixtures/machine, used instead of this machine's sensors.
no citation recorded

Verification

Verifier bindings

test:cc-agents.machine-suite · the machine guard against recorded sensor readings · anchored · test anchor binding present · tests/machine.test.mjs:4
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

Design view

Requirement drawing

Declared verifying examples: no declared verifying example.

Requirement drawing for spec:cc-agents.machine-guard

The diagram as text

spec:cc-agents.machine-guard: A critically loaded machine refuses new agents and stops none · declared Spec
spec:cc-agents.runner: Other model families run as real Claude Code agents · declared Spec
impl:cc-agents.machine: judges how loaded the machine is and admits a start unless it is critical · anchored code · plugin/sidecar/machine.mjs:20
impl:cc-agents.sidecar: the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · anchored code · plugin/sidecar/server.mjs:12
test:cc-agents.machine-suite: the machine guard against recorded sensor readings · anchored test binding · binding present · tests/machine.test.mjs:4
test:cc-agents.sidecar-suite: the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored test binding · binding present · tests/sidecar.test.mjs:4
spec:cc-agents.machine-guard refines spec:cc-agents.runner · declared
impl:cc-agents.machine satisfies spec:cc-agents.machine-guard · anchored
impl:cc-agents.sidecar references spec:cc-agents.machine-guard · anchored
test:cc-agents.machine-suite verifies spec:cc-agents.machine-guard · anchored
test:cc-agents.sidecar-suite verifies spec:cc-agents.machine-guard · anchored

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: requirementDiagram. Chosen syntax: flowchart TB because references require exact labels unavailable in requirement syntax.

Mermaid source for Requirement drawing for spec:cc-agents.machine-guard

flowchart TB
  n0["A critically loaded machine refuses new agents and stops none · declared Spec · spec:cc-agents.machine-guard"]
  n1["judges how loaded the machine is and admits a start unless it is critical · anchored code · impl:cc-agents.machine"]
  n2["the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · anchored code · impl:cc-agents.sidecar"]
  n3["the machine guard against recorded sensor readings · anchored test binding · binding present · test:cc-agents.machine-suite"]
  n4["the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored test binding · binding present · test:cc-agents.sidecar-suite"]
  n5["Other model families run as real Claude Code agents · declared Spec · spec:cc-agents.runner"]
  n0 -->|"refines · declared"| n5
  n1 -->|"satisfies · anchored"| n0
  n2 -->|"references · anchored"| n0
  n3 -->|"verifies · anchored"| n0
  n4 -->|"verifies · anchored"| n0

Decisions

No decision record named.

Runtime

impl:cc-agents.machine · judges how loaded the machine is and admits a start unless it is critical · plugin/sidecar/machine.mjs:20
Uses
None.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact

Relations of spec:cc-agents.machine-guard

The diagram as text

spec:cc-agents.machine-guard: A critically loaded machine refuses new agents and stops none
spec:cc-agents.runner: Other model families run as real Claude Code agents
spec:cc-agents.sidecar: One sidecar per Claude session owns the session's harness turns
spec:cc-agents.machine-guard refines spec:cc-agents.runner · declared
spec:cc-agents.sidecar dependsOn spec:cc-agents.machine-guard · declared — a start waits while the machine refuses it

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Mermaid source for Relations of spec:cc-agents.machine-guard

flowchart TB
  n0["Other model families run as real Claude Code agents · spec:cc-agents.runner"]
  n1["A critically loaded machine refuses new agents and stops none · spec:cc-agents.machine-guard"]
  n2["One sidecar per Claude session owns the session's harness turns · spec:cc-agents.sidecar"]
  n1 -->|"refines · declared"| n0
  n2 -->|"dependsOn · declared — a start waits while the machine refuses it"| n1

Rests on

refines · spec:cc-agents.runner · stated defined, floor ready

Rested on by

Distance 1

spec:cc-agents.sidecar
Implementing units
- impl:cc-agents.launch · plugin/sidecar/launch.mjs:7
- impl:cc-agents.sidecar · plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None

Distance 2

spec:cc-agents.mod-layer
Implementing units
- impl:cc-agents.mod · plugin/hooks/register.js:9
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite
Packs: None
spec:cc-agents.pane
Implementing units
- impl:cc-agents.harness-options · plugin/hooks/harnesses.js:5
- impl:cc-agents.pane · plugin/hooks/pane.js:13
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite, test:cc-agents.pane-suite
Packs: None
spec:cc-agents.relay-job-type
Implementing units
- impl:cc-agents.mod · plugin/hooks/register.js:9
- impl:cc-agents.relay-header · plugin/sidecar/relay-header.mjs:9
- impl:cc-agents.sidecar · plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite, test:cc-agents.sidecar-suite
Packs: None
spec:cc-agents.runner
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:cc-agents.steering-and-stop
Implementing units
- impl:cc-agents.mod · plugin/hooks/register.js:9
- impl:cc-agents.sidecar · plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite, test:cc-agents.sidecar-suite
Packs: None

Distance 3

spec:cc-agents.adapter-contract
Implementing units
- impl:cc-agents.codex · plugin/sidecar/adapters/codex.mjs:15
- impl:cc-agents.opencode · plugin/sidecar/adapters/opencode.mjs:26
- impl:cc-agents.sidecar · plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.opencode-suite, test:cc-agents.sidecar-suite
Packs: None
spec:cc-agents.codex-adapter
Implementing units
- impl:cc-agents.codex · plugin/sidecar/adapters/codex.mjs:15
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None
spec:cc-agents.cross-session-slots
Implementing units
- impl:cc-agents.sidecar · plugin/sidecar/server.mjs:12
- impl:cc-agents.slots · plugin/sidecar/slots.mjs:16
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None
spec:cc-agents.exact-answer
Implementing units
- impl:cc-agents.mod · plugin/hooks/register.js:9
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite
Packs: None
spec:cc-agents.hq-links
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:cc-agents.installation
Implementing units
None.
Referencing units
- impl:cc-agents.harness-options · plugin/hooks/harnesses.js:5
Enabled verifiers: None
Packs: None
spec:cc-agents.model-templates
Implementing units
- impl:cc-agents.harness-options · plugin/hooks/harnesses.js:5
- impl:cc-agents.mod · plugin/hooks/register.js:9
Referencing units
- impl:cc-agents.sync-templates · scripts/sync-templates.mjs:10
Enabled verifiers: test:cc-agents.mod-suite
Packs: None
spec:cc-agents.opencode-adapter
Implementing units
- impl:cc-agents.opencode · plugin/sidecar/adapters/opencode.mjs:26
Referencing units
None.
Enabled verifiers: test:cc-agents.opencode-suite
Packs: None
spec:cc-agents.work-containment
Implementing units
- impl:cc-agents.groups · plugin/sidecar/groups.mjs:13
- impl:cc-agents.guard · plugin/sidecar/guard.mjs:16
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None

Relations

Relation and direction	Other end	Claim	Reason	Exercised keys
refines · outgoing	Other model families run as real Claude Code agents `spec:cc-agents.runner` · resolves	declared	None	None
dependsOn · incoming	One sidecar per Claude session owns the session's harness turns `spec:cc-agents.sidecar` · resolves	declared	a start waits while the machine refuses it	None

Bindings

Implementation binding: present

impl:cc-agents.machine · judges how loaded the machine is and admits a start unless it is critical · plugin/sidecar/machine.mjs:20

Design reference: present

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

Verifier binding: present

test:cc-agents.machine-suite · the machine guard against recorded sensor readings · anchored · tests/machine.test.mjs:4 · test anchor
test:cc-agents.sidecar-suite · the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored · tests/sidecar.test.mjs:4 · test anchor

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.