orchestra/orchestra-spec (1).md

# [ORCHESTRA] — Multi-Harness Agent Orchestration

> Working name; yours to set. This is the binding spec — implementers (agents or you) bind to it, not to prose in a chat log.

**Status legend**
`[S]` settled — decided, do not re-litigate.
`[D]` default — a value/choice not explicitly ratified; tunable, veto freely. Never treat as fact.
`[O]` open — unresolved. Has a degrade-safe default so a gap never becomes a hallucinated decision.

---

## 0. Orientation

**What this is.** A control plane for an *orchestra of opaque harnesses* — Claude Code, Codex, opencode(-zen/go), and local models via llama-server. Subscription access is CLI-only: you orchestrate the **process**, not the model. Every harness is a black box with a terminal; herdr is the grip on it.

**What this is NOT.** `[S]` This is not Correx. Correx drives models you *call* (local inference, direct API). This drives harnesses you *cannot call*. They share **ontology** (task schema, vocab, the `*.md` conventions) so Maven speaks one language to both — they do **not** share execution code. The layers below have nothing in common with Correx's proposal-validator plane except discipline.

**The one metric.** `[S]` The objective is **maximized unattended runtime** — work completed per stretch you can walk away from — not cost-per-turn. Babysitting is a real cost that never appears in `ccusage`. Every trade-off resolves against this: Opus for correlation work cheaper models can't do, local/free for loud-failure mechanical work, rotation to extend the run before the context wall ends it.

**Deploy target.** `[S]` Runs on both machines (server, workpc). Single-user, homelab-internal.

---

## 1. Invariants — must hold everywhere

These are asserted at every boundary, not implemented as a component. If a change violates one, the change is wrong.

1. **`[S]` The log is append-only, forever.** Corrections are *compensation events* appended on top. There is no rewrite/compaction path — you cannot replay a decision you deleted, and receipts are the point.
2. **`[S]` The plane emits events, not the agent.** The agent only writes code and artifacts. The router, the adapter, and the stop-hook/wrapper emit lifecycle events. The agent is not a participant in the task system — the harness is. (This is what keeps task tooling out of the agent's context.)
3. **`[S]` Events reference artifacts by hash; they never embed them.** Handoffs, reports, diffs → CAS. The event carries the hash. Event payloads are always small.
4. **`[S]` No free-form field is trusted as instruction.** Every event payload and artifact field is typed and schema-validated at write. Knowledge/handoff prose is framed and consumed as **data**. This is the injection boundary — saturated on purpose: assert it everywhere, never build it as one guarded component.
5. **`[S]` State lives in artifacts verifiable against ground truth — never in agent memory or prose.** Pickup-without-rediscovery works only because a fresh agent validates against repo + `TASK.md`, never against a predecessor's narrative.
6. **`[S]` The log is not the transcript.** Liveness and per-turn progress are answered by asking herdr / exit codes, not by replaying events.

---

## 2. Architecture

Four layers. Each reads from the one below. Conflating them is the trap.

```
┌─ Layer 4 · SURFACES ──────────────────────────────────────┐
│  tui/web (full) · telegram+ntfy (notify) · Maven (gated)   │
│  authorization enforced on the bus, not per-client         │
└───────────────▲───────────────────────────────────────────┘
                │ subscribe / emit (per authz)
┌─ Layer 3 · CONTINUITY ────────────────────────────────────┐
│  handoff schema · pickup contract · TASK.md · shared *.md  │
└───────────────▲───────────────────────────────────────────┘
                │ artifacts (by hash)
┌─ Layer 2 · HARNESS (execution) ───────────────────────────┐
│  herdr backbone · harness adapters · router · rotation     │
│  supervises opaque CLI processes; no API in the loop       │
└───────────────▲───────────────────────────────────────────┘
                │ consumes tasks / emits lifecycle
┌─ Layer 1 · SUBSTRATE (the sink) ──────────────────────────┐
│  canonical event log · provider port · task aggregate      │
│  event catalog = THE contract (§4)                         │
└────────────────────────────────────────────────────────────┘
```

**Build order is bottom-up (§8).** Layer 1 is build-ready now; higher layers carry marked open items.

### 2.1 Deployment topology  `[D]` (parse of a federated design — verify)

`[S]` **Federated, not single-host.** Agents run on **both** homesrv and workpc, on demand — but workpc is **not** always on, so this is a worker-federation, not a symmetric pair.

Two registries:
- **Machine registry** — hosts (`homesrv` always-on; `workpc` intermittent; +future), each with mesh address + reachability.
- **Herdr registry** — herdr instances, each **bound to a machine-registry entry**, carrying static per-instance config for what it may run.

`[S]` **homesrv is authoritative.** Event log + router + CAS live there and **only** there — a laptop that sleeps can't hold canonical truth. `[S]` **workpc is a worker + client**, never a source of task truth.

`[S]` **herdr on both; we drive it, we don't own it.** The router dispatches leases to **any registered + reachable** herdr per its static config. A herdr that's offline (workpc asleep) simply isn't a candidate that cycle — no special-casing.

`[S]` **Git is the cross-machine transport.** Server holds the remotes; a machine going offline has already pushed, a machine coming online pulls. **This makes the scratch-branch commit (§6.2) one mechanism for three handoffs — cross-rotation, cross-agent, and cross-machine.** State in git + a validated artifact, picked up by whoever/wherever.

| Component | Host | Notes |
|---|---|---|
| event log · router · CAS | **homesrv only** | canonical; always-on |
| herdr + leased harnesses | homesrv **and** workpc | worker federation; offline = not a candidate |
| git remotes | homesrv | cross-machine transport |
| tui / web control | workpc (and anywhere) | client |
| Maven | homesrv | fully server-side (§2.2) |

### 2.2 Projects & machine affinity  `[S]`(model) `[D]`(examples)

`[S]` **Tasks bind to a project at creation** — you pick which. `[S]` Projects are **first-class and extensible**: adding more later reshapes nothing (the binding is a field + a config entry, not a schema change). `[S]` A project declares **machine affinity** — which host(s) its harnesses run on — as **static manual config** ("work however it sees fit based on static configuration").

Resolution chain: **task → project → affinity → candidate machines → router filters by reachable+configured herdr there.**

`[D]` Illustrative affinities (yours, not the system's — shown to fix the model):

| Project | Affinity |
|---|---|
| correx | workpc-primary, git remote on homesrv |
| Maven | homesrv-full; workpc only for CPT / fine-tune / LoRA |
| Kdrive · Muzic · Nexus · Praxis · Hexis | homesrv-exclusive |

`[O]` **Fork — is affinity hard or soft?** Night queue on homesrv: a workpc-primary project (correx) has its remote on the server, so homesrv *could* run it against the remote — or you may want it to wait for workpc. **Default `[D]`: hard** (never run where not configured; overnight queue = server-runnable projects only) — safer, predictable, matches static config. Soft (prefer workpc, fall back to server overnight) is a one-flag change if you want it. See §9.

### 2.3 Workflow — end to end  `[S]`

Two walk-away modes, both reducing to the same lifecycle:

- **Mode A — mid-day handoff.** workpc is on; you queue/assign and walk away; workpc's herdr runs to completion; results commit + push to the homesrv remote; `TaskCompleted` per task. (You were just using workpc, so it's up — no sync-wait.)
- **Mode B — overnight batch.** You queue N tasks for the night on homesrv (server-runnable projects, per affinity above); homesrv's herdr works through them; each commits + pushes; **git-sync means workpc pulls in the morning**; a single **morning brief (§7.4)** rolls up the whole night. This is the payoff of the sync + brief machinery.

**The whole lifecycle, once:**

```
ingest → TaskCreated                                   (provider adapter; §3.2, §4)
  → router: project → affinity → machine → lease       (§2.2, §5.5)  ── offline herdr = skipped
    → herdr on that machine: bootstrap · work · gate · TDD   (§5, §6)
      → rotation as needed  (intra-task lease transfer; state via git)   (§5.3, §6.2)
        → TaskCompleted + report_ref   (proofs + receipts)   (§4)
           │  or → TaskFailed / TaskBlocked → you            (needs-human)
        → reflect status out · git push · (workpc pulls on wake)   (§2.1, §3.2)
  → brief rolls up the window → surfaces per authz              (§7.4, §7.1)
```

`[S]` Everything crossing a machine boundary is git + a validated artifact — never live state over the wire. The event log is the only always-on shared surface; nothing holds a second copy.

---

## 3. Layer 1 — Task Substrate  `[S]` (spine settled)

### 3.1 Canonical event log

`[S]` The event log is the single source of task truth. Append-only. Global monotonic sequence number = the subscriber cursor. Each task aggregate additionally carries a per-task version for optimistic concurrency (§4).

`[S]` **Corrections = compensation.** A wrong event is never edited; a compensating event is appended and replay sees both.

`[S]` **Snapshots** cache "state as of sequence N" so projections don't replay from zero. Raw events are retained regardless — snapshots are an optimization, never a substitute.

`[D]` **Storage backend.** Append-only log store TBD; CAS blobs can sit on existing MinIO. Choose in §8 spike.

### 3.2 Provider port — bidirectional adapter

`[S]` The provider is an **interface, not a default implementation**, and it is **not** the source of task truth. It has two directions:

- **Ingest:** external task → `TaskCreated` event.
- **Reflect:** task state transitions → external status (e.g. close the Gitea issue on completion).

`[S]` **Stable external key `(source, external_id)`** per adapter, serving double duty:
- **Idempotency on ingest** — a webhook firing twice, or a poll re-seeing an issue, must not create two `TaskCreated`. First sight creates; repeats no-op or update.
- **Reflection address** — tells the adapter which external record to update outbound.

Adapters (all implement the same port):
- Gitea issues / CI failures (webhook + poll)
- Pure-local JSONL (trivial baseline — build first)
- (later) anything Maven feeds in

### 3.3 Task aggregate

`[S]` **Task is the only aggregate.** Epic / roadmap / sprint are **projections** over parent links, not their own streams (sprint's open/close lifecycle is the one possible exception — deferred to the agile layer).

Fields:

| Field | Type | Notes |
|---|---|---|
| `id` | ulid | internal |
| `source`, `external_id` | str | the stable external key |
| `project` | project-id | **bound at creation** (§2.2); resolves to machine affinity. Sink and brief group on this. |
| `capability` | tag set | **static**, set at creation. What the task *needs*. Router matches on this. |
| `lease` | Lease? | **dynamic**. Who holds it *now*. See §3.4. |
| `parent` | task-id? | task→epic→roadmap link |
| `inherent_priority` | enum | raw priority, editable |
| `due` | instant? | no hard deadlines; feeds derived importance |
| `estimate` | `{value, who, confidence}` | provenance-carrying (§3.6) |
| `state` | enum | derived from lifecycle events |
| `version` | int | optimistic-concurrency guard |

### 3.4 Two axes: capability vs. lease  `[S]`

These are **independent** and must not be merged:

- **Capability** — a property of the *task*. Static tag set (`{correlation}`, `{mechanical}`, …). Set at creation, matched at pickup.
- **Lease** — a property of a *harness instance*. Dynamic: who holds it, and until when (TTL, §5.4). Router sets it, agent releases it, rotation transfers it.

Merging them is wrong because it would force recomputing task metadata every time quota shifts — the task didn't change, the harness did.

`[S]` **Availability ≠ capability.** Whether a given harness *can accept right now* (alive? quota headroom? under concurrency cap?) is a **runtime filter the router applies at lease time**, not a task field. Router **matches** on capability, **filters** by availability.

`[S]` **Pickup-without-rediscovery** = lease release keeps capability intact; the next matching+available harness picks up from task state. Rotation-handoff and agent-to-agent-handoff are **the same lease transfer over the same task state** — one mechanism.

### 3.5 Derived importance  `[S]`

Importance is **not stored**. It is a sort key over the sink: `f(inherent_priority, proximity_to_due)`, recomputed as due approaches. `[S]` **Pickup-only** — importance orders the sink when a lease frees; it **never preempts running work**. No preemption event, no interrupt path in the harness.

### 3.6 Agile structure  `[S]`

- Hierarchy = parent links (§3.3), rendered as projections.
- Sprint = a time-boxed *selection* over the sink.
- Estimates carry `{who, confidence}` — agents give weighted judgment; you keep the last word. (This is the "standup" mechanic reduced to a field; see §7 for the advisory-event form.)

---

## 4. Event Catalog — THE contract

`[S]` An event earns a **distinct type only when a subscriber reacts in a way a generic "something changed" could not dispatch.** Everything else is one generic amend.

### Behavioral events (distinct subscriber reactions)

| Event | Emitted by | Key payload | Reacted to by | Concurrency |
|---|---|---|---|---|
| `TaskCreated` | provider adapter (ingest) | `project`, `capability`, `source`, `external_id`, `parent?`, `inherent_priority`, `due?` | router → evaluate for assignment | dedup on `(source,external_id)` |
| `TaskLeased` | router | `harness_id`, `expected_version`, `ttl` | the matched harness → start work | **CAS on task `version`** — second writer fails, no lock |
| `TaskReleased` | agent/harness (via plane) | `handoff_ref` (hash), `anchor_sha` | router → find next picker | version-guarded |
| `TaskCompleted` | stop-hook/wrapper (via plane) | `report_ref` (hash), `receipt` | fan-out: telegram/Gitea/Maven; reflect status out | terminal |
| `TaskFailed` | router | `reason`, `attempts` | needs-human path; stop retrying | terminal |
| `TaskBlocked` | agent/harness (via plane) | `blocker`, `handoff_ref?` | needs-human path | — |
| `ApprovalRequested` | harness (gate/arbiter) | `subject_ref`, `options` | full+gated surfaces present it; harness blocks | — |
| `ApprovalGranted` / `ApprovalDenied` | full-control surface | `subject_ref`, `by` | harness unblocks; other surfaces learn via this event | resolve-by-event, no timeout |

### Generic event

| Event | Emitted by | Payload | Reacted to by |
|---|---|---|---|
| `TaskAmended` | human or agent | `{fields}`: title, due, description, `inherent_priority` | sink re-projects |

`[S]` `TaskAmended` **never** carries lease or lifecycle. That boundary is the whole thing keeping it from rotting into a CRUD blob.

### Explicitly NOT in the log

- **Per-turn progress, liveness** → herdr socket (`pane.agent_status_changed`, `pane.exited`) + exit codes.
- **Token spend** → a **separate projection** keyed by `harness+window`, not by task. Per-task cost lands as a `receipt` field on `TaskCompleted`, **summed across the task's lease intervals** (a rotated task spans several sessions → a sum, not a single delta).

### The "no not-mine excuses" mechanism  `[S]`

Don't trust the agent to self-report a lint/format/test issue. The **quality gate** (detekt/ktlint, mypy/ruff, shellcheck, schema-validate) catches it mechanically and emits `TaskCreated` for anything it won't block on — deterministic and automatic. The only residue is a logic bug the agent *notices* but no gate catches → one narrow "file-a-task" affordance, kept small.

---

## 5. Layer 2 — Harness (execution)

### 5.1 herdr backbone  `[S]`

herdr (rust agent multiplexer; v0.7.x, AGPL-3.0/commercial — matters only if linked, not if shelled out to) gives real turn state where tmux gave none:

- `agent.prompt` with inline `wait{until,timeout_ms}` — bootstrap injection + turn-completion wait in **one request**, no gap.
- `agent.wait` **pins the pane occupant** — a replacement can't satisfy the old wait.
- `events.subscribe` on `pane.agent_status_changed` — no polling.
- `pane.report_metadata` (`tokens` map, TTL) — live occupancy gauge in the sidebar once you have the number.
- `pane.exited` — crash fast-path. `notification.show` — HALT pages you through herdr itself.
- `worktree.create` — one worktree per rotation chain → anchor validation collapses to one `rev-parse`.

`[S]` Install native integrations (`herdr integration install {claude,codex,opencode}`) so "done" is reported, not inferred. `[S]` Socket at `~/.config/herdr/herdr.sock` is unauthenticated → bind harness fleet to the WireGuard mesh, never `0.0.0.0`; on VPS, reconsider entirely. `[S]` Generate the client off `herdr api schema --json`; check protocol version via `ping` before depending on new behavior.

`[D]` **Driving herdr — imperative is fine, except two ops.** Poke panes over the socket (send-text / capture-pane-equivalents) for ordinary control and for feeding the TUI/brief — it's a multiplexer you don't own, this is expected. But keep the **two rotation-critical ops** on the semantic primitives: **turn-end** via Face B / `agent_status` (§5.2.1), and **bootstrap injection** via `agent.prompt` with inline `wait` (`agent.wait` pins the occupant so a replacement can't satisfy it). capture-pane polling + send-keys for *those two* reintroduces the exact tmux race — a bootstrap or `/clear` fired into a half-rendered prompt, silently, unattended. Veto only if you've solved that race another way.

### 5.2 Harness adapter — the second load-bearing contract  `[S]`

A harness adapter has **two faces**, and it is the *same seam* as the Layer-1 provider concept applied to execution:

```
interface HarnessAdapter {
  // Face A — lifecycle / IO
  fun lease(task, worktree): Session        // start the opaque CLI in a herdr pane
  fun bootstrap(session, handoffRef)        // ~200-token prompt: "read handoff, run validate, proceed"
  fun release(session): TaskReleased        // checkpoint + emit
  fun kill(session)

  // Face B — turn-boundary + occupancy detection  (per-harness impl; §5.2.1)
  fun onTurnBoundary(cb)                     // cc: Stop hook (exit 2 refuses turn); codex: rollout tail; opencode: SSE session.status
  fun occupancy(session): Fraction          // all three read native session state — NO proxy required
}
```

`[S]` **cc's Face B** = the Stop hook. Exit **2** blocks stop and feeds stderr back → over-threshold-with-no-valid-handoff refuses the turn until the handoff is written and validates, then exit 0. `[S]` **codex/opencode's Face B** read their own native session state (§5.2.1) — no proxy. The trigger is harness-agnostic **above** the adapter; per-harness **below** it. `[S]` The router and rotation logic never know which harness they're driving.

### 5.2.1 Occupancy sources — verified  `[S]`/`[D]`

`[S]` herdr has no token accounting, but the earlier "proxy for codex/opencode" assumption was wrong: **all three harnesses write usage into local session state; none require an interception proxy.** They differ only in the cleanest access path. Build this measurement and verify it against a live session **before** wiring any trigger — the whole rotation system rests on this number.

| Harness | Source `[S]` | Path / endpoint | Per-turn shape `[S]` | Occupancy numerator (what's in the window *now*) |
|---|---|---|---|---|
| **Claude Code** | session JSONL, `message.usage` per assistant entry | `~/.claude/projects/<enc-path>/<session-id>.jsonl` (hook gives `transcript_path` on stdin) | **absolute per entry**: `input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `output_tokens` | last assistant entry: `input + cache_read + cache_creation` (the context sent). Dedupe by message `uuid`. |
| **Codex** | rollout JSONL `event_msg`, `payload.type=="token_count"` | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` (or `CODEX_HOME`). Active file authoritative via `state_*.sqlite → threads.rollout_path` — discover, don't hardcode | `info.total_token_usage` is **cumulative** (diff successive); `info.last_token_usage` is the last step | `last_token_usage.last_input (+ last_cached)`. Only present since codex ≥ 2025-09-06; older logs have none. |
| **opencode** | server API (it's already a Hono server on `:4096`) | SSE `GET /event` → `session.status` (idle/busy) + `message.updated`; or `GET /session/{id}/messages`; files at `~/.local/share/opencode/storage/message/` (`OPENCODE_DATA_DIR`) | per-message `tokens = {input, output, reasoning, cache:{read,write}}` (`cost:0` in files) | last message: `tokens.input + tokens.cache.read`. |

`[S]` **The trap that would silently break rotation: never use the cumulative session total as occupancy.** All three accumulate `cache_read` per turn without bound — one real opencode session reported ~56M "total tokens" against a 200k window; codex burns from 21k→560k cumulative in a startup loop. Cumulative total answers "what did this session cost," not "how full is the context." **Occupancy = *this turn's* input+cache against the model's context window**, i.e. the numerator column above ÷ window (200k Sonnet/Opus-class; the gpt-5.x window for codex — model-dependent constants, keep them in config).

`[D]` **Proxy is the fallback, not the primary.** A localhost shim on `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` reading `usage` off responses still works and is the one *uniform* implementation across all three — worth it only if per-harness parsing gets annoying or you want request-time-synchronous truth. Native sources are simpler and are the default.

`[D]` **opencode SSE is not rock-solid** — the `/event` stream has known bugs (closes right after `server.connected`; stochastic REST behavior under `opencode serve`). Treat the event stream as the fast path and keep the message-file / `opencode stats --json` read as the backstop, same fast-path-plus-backstop shape as `pane.exited`+TTL.

### 5.3 Rotation  `[S]`

`[S]` **The Stop-hook/Face-B decides rotation, not the router.** It has the transcript and fires at turn boundaries. The router decides whether rotation is *permitted* (caps, budget) and executes it.

Triggers:
- `[D]` **soft ~55%** → "prepare handoff at next natural stop"
- `[D]` **hard ~75%** → rotate now; reserve `[D]` ~10–15k tokens to actually write the handoff (do not wait for 90% — compaction beats you)
- `[S]` **milestone** → phase boundary rotates regardless of occupancy (a fresh agent at a boundary beats a 60%-full one; cheap context is a feature)
- `[S]` **thrash** → N failed test runs / same file edited M times with no pass / identical tool calls repeating → rotate with `reason=thrash` + populated `dead_ends` = circuit breaker
- `[S]` **agent-initiated `ROTATE`** → emitted when a coherent unit finishes and the next is independent

`[S]` **Rotation = intra-task lease transfer** (§3.4). `[S]` **Split-then-close** (cheap): new pane validates the anchor before the old pane closes — atomic, with a real rollback path, and it drops the `/clear`-slash-command dependency that codex/opencode don't share.

### 5.4 Failure & lease semantics  `[S]`

- `[S]` **Lease carries a TTL.** Reclamation = **lease-expiry**, not crash-detection. A harness that dies without releasing lets its lease go stale → task returns to the sink. You don't need to reliably observe death; you need leases to not be eternal.
- `[S]` `pane.exited` = fast-path to relet sooner; TTL = backstop for the hang `pane.exited` misses.
- `[S]` Policy: **retry N, then `TaskFailed`**; agent continues if nothing more important is queued. `[D]` `N`, `ttl`, retry backoff = config.

### 5.5 Router  `[S]`

Makes assignment decisions at **exactly two moments**: on `TaskCreated` (ingest) and on lease-free (`TaskReleased`/expiry). **Never against running work** (pickup-only, §3.5). Algorithm: resolve **project → machine affinity** (§2.2) to candidate hosts → **restrict** to registered + **reachable** herdr on those hosts (offline = not a candidate) → **match** by `capability` → **filter** by availability (alive, quota headroom, under concurrency cap) → **order** by derived importance → lease the top via version-guarded `TaskLeased`. `[S]` Machine resolution is first because it's the hard constraint; capability and availability narrow within it.

### 5.6 Build note  `[S]`

Orchestrator in **bash first** (~150 lines: subscribe, read request, validate, split, prompt, ack, close) — run it on one real task, find where the state machine is wrong (it will be, around thrash + timeout). **Then** port to Kotlin/Spring as a proper long-lived supervised service and slot it into the fleet. Hooks stay bash forever (they run in the agent's process every turn — no runtime, no deps).

---

## 6. Layer 3 — Continuity

### 6.1 Handoff schema  `[S]`

Every field **verifiable against the repo** — prose is where hallucination lives and it compounds across rotations. `[D]` **Size cap ~4–6k tokens**; if it doesn't fit, task decomposition is wrong, not the schema. Stored in CAS; events carry the hash (Invariant 3).

```toml
[meta]      id, parent, reason = "threshold|milestone|thrash|manual", rotation_index
[anchor]    git_sha, branch, dirty = [{path, sha256}]        # verifiable state
[objective] goal (one sentence), done_when = [checkable, criteria]
[progress]  completed = [{what, evidence = "file:line"}], remaining = [...]
[next]      action (single step), command (literal first cmd), files = [...]
[knowledge] invariants = [...], dead_ends = [{tried, why_failed}], open_questions = [...]
[verify]    build, test, last_result = {command, exit_code, at_sha}
```

`[S]` **`dead_ends` is the highest-value block and the one everyone omits** — negative knowledge is exactly what's lost on rotation; without it the fresh agent re-derives the same failure. `[S]` **`[knowledge]` is framed as data, not instructions** (Invariant 4) — this is the injection-persistence surface; strict schema, no free-form.

### 6.2 Pickup contract — the make-or-break  `[S]`

`[S]` Agents validate; the orchestra validates. `[S]` The validation is a **concrete, testable procedure** run before the fresh agent continues — not a principle:

```
validate-handoff <id>:
  1. schema-check the handoff (types, required fields, no free-form in [knowledge])
  2. git rev-parse HEAD  == anchor.git_sha
  3. for each anchor.dirty: sha256(path) == recorded          # or: WIP committed to scratch branch, one sha compare
  4. re-read immutable TASK.md (original spec)
  → all pass → proceed
  → any fail → do NOT rotate/continue; agent fixes, re-validate
```

`[S]` **`TASK.md` is immutable**, holds the original spec, is **re-injected every rotation**, and is **never rewritten**. The fresh agent validates against repo + `TASK.md` — **never against the predecessor's handoff prose.** This is the defense against the telephone game across long autonomous runs. `[S]` **Commit WIP to a scratch branch first** so step 3 is one sha compare, atomic and free.

### 6.3 Shared memory & vocab  `[S]`

- `[S]` Shared `*.md` (AGENTS.md, CLAUDE.md, vocab) — **all agents contribute.**
- `[S]` On update, the **orchestra injects a notice** to agents whose current task is **adjacent** (staleness handled at the orchestra layer, not by trusting cached agent views — same shape as herdr's metadata TTL, one layer up).
- `[S]` Docs are self-containing, human-readable **and** digestible-at-a-glance, with references where available and mockups at specing stage. The policy SHOULDs ("no not-mine excuses", TDD-by-default, spec-first, cheap-harness-before-manual, QA-mandatory) live **here as convention text + gates**, not as code.

---

## 7. Layer 4 — Surfaces

### 7.1 Authorization model — enforced on the bus  `[S]`

Not a UX detail — a capability per surface on the event bus. "Who can do what from where" is enforced **once, at the bus**, not per-client.

| Surface | Capability | Can emit | Notes |
|---|---|---|---|
| **telegram + ntfy** | notify-only | *nothing* | read-side subscriber; pure notification |
| **tui / web-ui** | full control | any event, incl. approvals | the control seats |
| **MCP** `[D]` | read + **gated** write | queries freely; task create/amend via `ApprovalRequested` | programmatic surface for external agents/tools; `[D]` promote to full if it's your own trusted client. (MCP-as-*ingest* — Maven feeding tasks — is the §3.2 provider port, separate from this.) |
| **Maven** | observation + **gated** control | **only** via `ApprovalRequested` → your grant; never direct | north-star assistant, fenced |

`[S]` **Clients poll; they do not store.** `[S]` An approval granted on **any** full/gated surface resolves by `ApprovalGranted`/`Denied`; others **learn via the event** later. **No approval timeout** (you may be asleep). `[S]` Artifacts crossing into a **control-capable** surface are **re-validated against schema at that boundary** (Invariant 4), never passed through.

### 7.2 Quota transparency  `[O]`

`[S]` **Quota ≠ occupancy — different numbers, do not conflate.** Occupancy (§5.2.1) is *context-window fill of one session* and drives rotation. Quota here is *subscription-pool consumption across sessions* (the 5-hour rolling + weekly caps) and drives the router's availability filter + 3am safety. Same source files, different accounting: `ccusage blocks --json` gives the 5h-window view; codex even surfaces its own 5h/weekly % in the rollout logs.

`[S]` Transparent quota is a **projection** (§4, keyed `harness+window`), fed by the same per-harness session state as §5.2.1 (`ccusage`-style) — no separate proxy needed. `[O]` **Accuracy is unresolved** — each pool is reconstructed, none authoritative, and a 3am autonomous run trusting a wrong "you have headroom" hits a wall mid-task. **Degrade-safe default `[D]`:** treat `[D]` 80% reported as full; the router's availability filter (§5.5) uses the conservative number. Name the failure mode in-system; refine after measuring a real run.

### 7.3 Standups  `[S]`

Scheduled read over the log that emits an **advisory** event (agents provide opinion + weighted judgment). `[S]` **Last word is yours** — the advisory routes through the same approval gate; nothing self-applies.

### 7.4 The brief  `[S]`

`[S]` A **projection over the event log for a window** (nightly, or on demand) — **not** a new event source, not something an agent authors. It aggregates, for that window: `TaskCompleted` / `TaskFailed` / `TaskBlocked` with their `report_ref` proofs+receipts, what **needs you** (pending `ApprovalRequested`, failures, blocks), quota consumed per harness (§7.2), and the **git sync state** (what pushed, what's on which branch, what workpc still needs to pull). Read-only, **digestible at a glance** (the SHOULD).

`[S]` **The morning brief is just the overnight window's brief** — the payoff of Mode B (§2.3). Delivered per surface authz (§7.1): telegram gets the headline + ntfy ping, tui/web the full rollup. `[S]` It **surfaces** judgment and attention items; nothing in it self-applies — your call, same gate as everywhere.

The per-task report (`report_ref`, §4) is one task's receipts; the brief is the window's rollup **over** those reports. Two levels, one is not the other.

---

## 8. Build Sequence  `[S]`

Bottom-up. Each step is a consumer of the one below; do not start a step before its dependency is proven.

1. **Task schema + provider port** — one interface, one **JSONL adapter**. (§3)
2. **Event log + state projection** — prove the read model; pick the log store + CAS backend here. (§3.1, §4)
3. **`*.md` conventions** — near-zero code; encodes most policy SHOULDs. (§6.3)
4. **herdr harness + rotation** — as a **consumer** of 1–2. Build the **occupancy measurement first** and verify against a live session (§5.2). Orchestrator in **bash**, then port. (§5)
5. **Surfaces, one at a time** — each a subscriber with its bus capability (§7). Telegram/ntfy first (read-only, lowest risk) → tui/web → Maven-gated.

**Cross-cutting from day one:** Invariants (§1) are asserted as each layer lands — especially append-only (1), plane-emits (2), hash-refs (3), typed-no-freeform (4). TDD by default; QA suites mandatory; cheap harness before any manual debug/test.

---

## 9. Open Questions — with degrade-safe defaults

Named so the spec is written against a known frontier. Each has a default so a gap never becomes a hallucinated decision.

| # | Question | Status | Degrade-safe default |
|---|---|---|---|
| 1 | **Quota projection accuracy** across cc/codex/opencode (reconstructed, non-authoritative) | `[O]` | Treat `[D]` 80% reported as full; router uses conservative number. Refine post-measurement. |
| 2 | **Schema-evolution mechanic** — upcast-on-read vs. tolerant-reader | `[O]` (versioned = decided) | Tolerant-reader + versioned envelope until a real migration forces upcasting. |
| 3 | **Log retention / cold-storage aging** as the log grows | `[O]` (deferred) | Snapshot + keep all raw events online; revisit only when size bites. |
| 4 | **Storage backend** for append-only log (+ CAS on MinIO?) | `[O]` | Decide in Step 2 spike; JSONL baseline works meanwhile. |
| 5 | **Cross-surface approval propagation** detail (poll cadence, dedup) | `[O]` (deferrable) | Resolve-by-event, no timeout; clients poll `[D]` on a short interval. |
| 6 | **Capability tag vocabulary** — the actual tag set beyond `{correlation, mechanical}` | `[O]` | Start with those two; grow from real task triage, not up front. |
| 7 | **Machine affinity: hard or soft?** (§2.2) — can a workpc-primary project run on homesrv against the remote overnight, or wait for workpc? | `[O]` | **Hard** — never run where not configured; overnight queue = server-runnable projects only. Soft is a one-flag change. |
| 8 | **Cross-machine lease correctness** (§2.1) — worktree/anchor validation and quota accounting when a lease's git checkout lives on a different host than the router | `[O]` | Git is the only cross-machine transport; validate against the local checkout wherever the harness runs; quota accounted per-host. Prove on the first federated run. |

**Decided elsewhere (do not reopen):** compensation over compaction; versioned schema; snapshot+replay; per-harness trigger = adapter Face B; retry-then-relet with TTL reclamation; capability-static vs. availability-dynamic; pickup-only importance (no preemption); surface authorization split; injection as an everywhere-invariant; **federated worker topology (homesrv authoritative, workpc intermittent worker); herdr on both, driven-not-owned; git as cross-machine transport; task→project→machine-affinity; the brief as a windowed projection.**

**Explicitly out of scope — deferred by decision, not omission:** cheap-model / free-inference **delegation** (offloading mechanical sub-work to local llama-server or free providers). Concluded orthogonal to this system — **rotation is the quota lever, delegation is at most a trim**, and the real objective is unattended runtime, not per-turn price (§0). Revisit later as a per-task routing hint carried in task metadata, once the substrate runs and a profiled session shows where tokens actually go. Named here so it stays a choice.

---

*This spec is the contract. Where it says `[O]`, the default holds until you decide — an implementing agent must surface the open item, never silently pick.*