supervisor.md

Supervisor surface

This document describes the JSON shapes the bernstein supervisor command emits. Two surfaces are documented:

1. Aggregated supervisor snapshot - the body returned by bernstein supervisor status --json and embedded as the supervisor field in bernstein status --json.
2. Signed escalation receipt - the envelope persisted under .sdd/runtime/supervisor/receipts/ whenever the supervisor or the operator escalates a stalled worker.

Both shapes are versioned via an explicit schema_version field.

Supervisor snapshot

{
  "schema_version": "1.0.0",
  "generated_ts": 1700000000.0,
  "stuck_count": 2,
  "oldest_stall_age_s": 95.0,
  "workers": [
    {
      "worker_id": "abc123def456",
      "session_id": "sess-abc123",
      "role": "backend",
      "task_id": "t-12",
      "worktree_id": "wt-007",
      "last_heartbeat_age_s": 42.0,
      "is_stuck": false,
      "stall_reason": "unknown",
      "recommended_action": "inspect",
      "respawn_budget_remaining": 3,
      "stuck_since_ts": null,
      "details": {"status": "working"}
    }
  ]
}

Fields

Field	Type	Description
schema_version	string	Aggregator schema version. Currently 1.0.0.
generated_ts	float	Unix timestamp the snapshot was captured.
stuck_count	integer	Number of workers with is_stuck=true.
oldest_stall_age_s	float | null	Age, in seconds, of the oldest currently-stuck worker; null when no worker is stuck or no stall timestamp is available.
workers[].worker_id	string	Operator-decodable worker handle.
workers[].session_id	string	Adapter session id.
workers[].role	string	Worker role (manager, backend, qa, ...).
workers[].task_id	string	Current task id, or empty string.
workers[].worktree_id	string	Worktree the worker is running in.
workers[].last_heartbeat_age_s	float | null	Seconds since the last heartbeat; null when none recorded.
workers[].is_stuck	bool	True iff at least one detector classifies the row as stuck.
workers[].stall_reason	string	One of manager_no_children, watchdog_model_question, respawn_budget_exhausted, heartbeat_stale, no_progress, or unknown.
workers[].recommended_action	string	One of respawn, escalate, park, inspect. Deterministic over the chain slice (see below).
workers[].respawn_budget_remaining	integer	Respawns remaining under the session's budget.
workers[].stuck_since_ts	float | null	Unix timestamp the stall first fired; null when not known.
workers[].details	object	Free-form detector context. The aggregator currently includes status (raw agent status).

Escalation receipt envelope

{
  "schema_version": "1.0.0",
  "worker_id": "abc123def456",
  "worktree_id": "wt-007",
  "session_id": "sess-abc123",
  "stall_reason": "manager_no_children",
  "recommended_action": "escalate",
  "audit_entries": [
    {
      "event_type": "stalled_manager",
      "session_id": "sess-abc123",
      "details": {"runtime_s": 120.0, "hook_event_count": 12}
    }
  ],
  "identity": {
    "install_rev": "abc123def4567890",
    "keyid": "...64 hex chars...",
    "run_id": "run-2026-05-21-001"
  },
  "prev_chain_digest": "...64 hex chars...",
  "payload_digest": "...64 hex chars...",
  "signature_b64": "...base64 Ed25519 signature...",
  "details": {
    "operator_reason": "wedged on credential rotation",
    "respawn_budget_remaining": 0
  }
}

Receipt fields

Field	Type	Description
schema_version	string	Receipt schema version. Currently 1.0.0.
worker_id	string	Stable worker identifier.
worktree_id	string	Worktree the worker was running in.
session_id	string	Adapter session id.
stall_reason	string	Structured stall reason - same vocabulary as the aggregator.
recommended_action	string	Deterministic action - same vocabulary as the aggregator.
audit_entries	array of object	Captured chain slice (default 16 trailing entries) leading up to the stall.
identity.install_rev	string	Operator-decodable install fingerprint.
identity.keyid	string	sha256 of the Ed25519 public key (hex).
identity.run_id	string	Orchestrator run id, when known.
prev_chain_digest	string	HMAC of the previous audit-chain entry. Links the receipt into the tamper-evident audit log.
payload_digest	string	sha256 of the canonical signing payload. Lets verifiers detect a swapped signature blob.
signature_b64	string	base64-encoded Ed25519 signature over the canonical payload.
details	object	Free-form context. The CLI populates operator_reason and respawn_budget_remaining.

Determinism contract

recommended_action is a pure function of the receipt's (stall_reason, audit_entries, respawn_budget_remaining). The function

• never reads files or environment,
• never opens a socket,
• never reads a wall clock.

Two operators handed the same receipt bytes (or independently reassembled receipts from the same chain prefix) compute the byte-identical recommended_action. The contract is enforced by the unit test tests/unit/test_supervisor_receipt.py::test_recommended_action_determinism, which drives the same chain slice through the function from two different temp dirs and asserts equality.

Cross-worktree fence

Every receipt asserts that the stuck session never crossed worktree boundaries during the stall window. An audit entry whose event_type ends in .resolved or starts with cross_worktree. and references the stuck session_id from a sibling worktree_id is a fence violation and aborts receipt assembly. Verifiers re-run the same check from the receipt bytes alone, so a tampered audit slice that smuggled a leak past assembly fails verification.

Verification

The standalone verifier loads only the public side of the install Ed25519 keypair (<workdir>/.sdd/runtime/supervisor/install.key.pub, PEM-encoded). It

1. recomputes payload_digest over the canonical signing bytes and asserts byte-equality with the receipt's payload_digest,
2. re-asserts the cross-worktree fence,
3. re-derives recommended_action from the embedded slice and asserts equality with the receipt's recommended_action,
4. verifies the Ed25519 signature over the canonical bytes.

A receipt that survives all four checks is byte-portable: any auditor holding the install's public key validates it offline without contacting the orchestrator.