omp-conductor 0.15.10 → 0.15.12

package/REFERENCE.md

@@ -0,0 +1,2680 @@
+# omp-conductor — Reference
+
+The complete reference for `omp-conductor`, every surface and every internal. For
+the 10-minute operator guide — what it is, install, quick start, operating the
+fleet, and multi-project operation — read [`README.md`](README.md).
+
+The sections below are the reference half of the documentation. Each guide
+section links back here for the full detail it trims.
+
+## Install prerequisites
+
+The guide's [Install](README.md#install) section links here. What the host needs
+before anything runs:
+
+`@oh-my-pi/pi-coding-agent` (`>=17.1.4`) is a **peer dependency** and must already
+be present. If you run omp, it is.
+
+Also required on the host:
+
+- `bun`: the CLI and the daemon run on it (`Bun.serve` backs `/healthz`).
+- **A model credential the *daemon's own account* can reach.** Sessions are child
+  processes of the daemon and inherit its environment and `$HOME` unmodified, so a
+  session authenticates with exactly what the daemon authenticates with — nothing
+  is injected and nothing is scrubbed. Any shape the harness itself understands
+  works, including the ordinary one:
+  - an **OAuth login** already recorded for that account (`omp` login state under
+    its `~/.omp/agent`). This is the common case and needs no configuration.
+  - a model **API key** in the daemon's environment (`ANTHROPIC_API_KEY`,
+    `OPENAI_API_KEY`, …). Note systemd starts the service with a clean
+    environment, so it has to be an `Environment=` line on the unit, not something
+    exported in your shell.
+  - the harness's **auth broker**, configured in that account's
+    `~/.omp/agent/config.yml`.
+
+  The account matters more than the shape: a login recorded under a *different*
+  account is invisible to the service. A unit running `User=fleet` cannot see
+  `root`'s login, and workers then die at turn 0 with `No model selected`. Such a
+  run is classified `env-start-failure` and charges **neither** the failure budget
+  nor a continuation — an environment fault is not a failed implementation, and a
+  run that recorded no turn, no commit and no error did not attempt anything — but
+  nothing dispatches successfully until the credential is reachable.
+- `gh`, already authenticated: every tracker operation shells out to it, so the
+  daemon never handles a GitHub token itself.
+- `git`: mirrors and worktrees.
+- **[omp-telegram](https://www.npmjs.com/package/omp-telegram)**, for the
+  escalation channel. It is a separate package and is not vendored here.
+
+  Two different things depend on it, and they need different amounts of it:
+
+  - **Tier-2 paging** needs only its bot token. This package reads
+    `TELEGRAM_BOT_TOKEN` out of `$OMP_TELEGRAM_STATE_DIR/.env` (default
+    `~/.omp/agent/telegram/.env`) and posts to the chat id you configure. No
+    pairing required, and no token ever passes through this package's own config.
+  - **The interactive channel** — replying to an escalation, approving a brief
+    amendment from your phone — needs omp-telegram actually paired, which is what
+    writes `access.json`. The fleet heartbeat also reads that file and refuses to
+    tick unless exactly one owner is paired, on the grounds that unattended
+    dispatch is only defensible while a tier-2 page can reach a person.
+  - **Approving a Learning-loop amendment from a heartbeat tick** needs one more
+    setting than pairing: a notify destination. `/telegram notify` writes
+    `notifyMode` and `notifyChat` into the same `access.json`. omp-telegram
+    mounts its `telegram_ask` tool only for a turn that resolves a notify target,
+    and a locally injected tick resolves one only through that setting — so
+    without it the orchestrator can page you but cannot put a yes/no question in
+    front of you, which is the one thing the Learning loop's approval step
+    requires. `omp-conductor status` reports this on the `telegram` row, and a
+    tick that cannot ask says so in its own prompt and falls back to
+    `telegram_send`.
+
+    Set `notifyChat` even on a forum fleet. `/telegram topics` routes to a topic
+    this session claims at runtime, and that claim is not visible in
+    `access.json` — so a file carrying only `topicsChat` is reported as
+    unconfigured rather than guessed at, on the grounds that a health row which
+    reads green over a broken contract is worse than one that overstates a fault.
+
+  - **A fleet that answers instead of narrating** needs one key, set once:
+    `/telegram set profile daemon` (omp-telegram 0.11.0 or newer). Without it the
+    bridge behaves as it does on a laptop: it finalizes a real Telegram message
+    per assistant turn for as long as a conversation is active — so one answer
+    arrives as several messages, and a message that lands mid-tick keeps relaying
+    that tick's internal turns — and it posts every local run's closing text to
+    `notifyChat`, which on a host whose runs are heartbeat ticks means each tick's
+    working prose. The profile switches all of it off at the transport: text
+    reaches Telegram only through `telegram_send` / `telegram_ask`, the idle post
+    is suppressed, and `telegram_ask` stays mounted and aimed at the paired owner
+    on every turn — including a locally injected tick, so it also removes the need
+    for `notifyMode` above. Approval and blocked-input pings still fire; those
+    mean a human is needed, which is the point of the channel.
+
+    `omp-conductor status` reports an interactive profile on the `telegram` row,
+    and every tick composed on one carries a prompt line saying so. Note the two
+    settings pull against each other before the profile exists: setting
+    `notifyMode` to make `telegram_ask` mountable is exactly what arms the idle
+    post, so the correctly askable fleet was also the loud one.
+
+  With neither, tier 2 degrades to a comment on the issue. Nothing is broken in
+  that configuration: it is supported, just slower to reach you.
+
+
+## Updating
+
+Run one command from a shell outside the target `herdr-fleet.service`:
+
+```bash
+omp-conductor upgrade
+```
+
+The fleet can also install its own fixes: with the `install` release shape
+granted to the orchestrator (`omp-conductor setup authority`, gate **install**),
+an orchestrator requests `conductor_install --arg version=X.Y.Z`. The daemon
+refuses a version npm does not expose, then starts a transient systemd unit
+(`omp-conductor-upgrade-install-<version>`) that runs the same transaction
+outside the pane and the daemon, journaling every surface it touches to the
+state-dir upgrade journal. The first tick after the restart reads that journal
+and verifies independently — installed version, `/healthz`, ticks, pane,
+`doctor` — then restores dispatch and reports through the durable outbox; any
+gap triggers the detached rollback and a tier-2 page. The unit never declares
+its own success, so a fleet is never left half-upgraded and quiet.
+
+It resolves the latest published npm release, pauses new claims, drains active
+workers, and pins that exact release across the Bun-global CLI, omp plugin, and
+Herdr plugin. It also recomposes the conductor-owned brief floor, restarts Herdr
+and the daemon, waits for pane recovery, verifies the installed identities and
+layered fleet status twice, then restores the original dispatch state.
+
+Use `omp-conductor upgrade --to X.Y.Z` for an explicit published version. The
+command exits without changing anything when all three surfaces already use that
+release, the Herdr plugin is pinned to its exact `gitHead`, and the brief is
+current.
+
+The upgrade is host-wide, because everything it replaces is: one daemon serves
+every configured project, so its restart lands on all of them at once. A bare
+`omp-conductor upgrade` therefore drains **every** project's workers and
+refreshes **every** project's brief, and pauses them with the fleet-wide
+sentinel — which leaves any per-project `hold` you set standing when it
+restores dispatch.
+
+`--project` narrows that only when it is truthful to do so. When a live daemon
+recorded a single project, the command drains and restarts that project, and an
+explicit `--project` naming a different one is rejected before pause or
+installation. When the daemon serves every configured project and there is more
+than one, `--project` is rejected too: draining one queue and then restarting
+the shared daemon would kill another queue's workers without ever counting
+them. Re-run without the flag.
+
+Ticks remain in their existing armed or disarmed state, so an ordinary update
+does not halt the exact pane or require another Telegram arm challenge. Progress
+names the Bun-global CLI, omp plugin, Herdr plugin, brief, reloads, and both
+verification passes separately.
+
+An installation, brief, reload, or verification failure pauses dispatch and
+attempts to restore the exact CLI/plugin identities that were present before the
+command. If rollback also fails, the error names every failed restoration and
+keeps dispatch paused; it never brings a known mixed fleet back into service.
+The command never publishes npm, edits an install root, or delegates lifecycle
+steps to an AI session. It refuses to run inside a Herdr-managed session because
+an updater that restarts itself cannot verify the result.
+
+After every upgrade — and after the initial install — run the mechanical host
+verification:
+
+```bash
+omp-conductor doctor
+```
+
+It is read-only and exits 0 only when nothing failed. Each finding is one
+deployment fault that has already cost a debugging session: expired `gh` auth
+or scope gaps, case-mismatched routing/state labels (silent by design), the
+installed systemd units drifting from the staged render, runtime-dir ownership,
+config.json validation and backup freshness, sqlite `PRAGMA integrity_check`,
+spend telemetry reading $0.00 on every completed run, invalid reporting
+timezones, and Telegram delivery health. `--probe-telegram` is the one opt-in
+side effect: one self-identified test message through the report transport.
+
+The unit-drift check compares the installed units against the staged render,
+excluding the herdr pane-shell `SHELL=` pin: that value is host state resolved
+at staging time, and `doctor`'s own process resolves it differently (or not at
+all) in a non-login/tick context, so it is reported as not-comparable rather
+than as drift (#511). It still flags genuine drift in `User=`, `ExecStart=`,
+other `Environment=` lines, `Restart=` and `SuccessExitStatus=`, and the unit
+itself keeps pinning `SHELL=` so panes do not fall back to dash (#463).
+
+## Onboarding
+
+`omp-conductor setup` is the whole of it. One command, in a plain terminal, doing
+the two jobs onboarding has always had:
+
+| Half | What it does |
+| --- | --- |
+| **The interview** | Asks the judgment no amount of repo reading produces, then writes it into `POLICY.md` as prose you own and can edit. |
+| **The probes** | Reads your repos and *proposes* the rest — real CI gates, the project context, the release procedure — each a default you edit or a draft you confirm. |
+
+The split matters because the two halves fail differently. A wrong config value is
+a run that errors on the next tick; a wrong release boundary is a fleet that
+publishes something at 03:00. The first is worth a validated prompt. The second is
+worth being asked properly, which is why it is asked and never guessed.
+
+### What only you can answer
+
+Always asked: **where the roadmap lives and what the current priority is.** A
+tracker shows what is *open*, never what *matters*, and an orchestrator that cannot
+rank work grooms by recency — which is how a stale issue outranks the thing you are
+shipping this month.
+
+Asked only when you grant the orchestrator a release shape, because a
+humans-release fleet has no boundary to draw:
+
+- **Where the orchestrator's leg ENDS**, in one sentence. If it cannot be said in
+  one sentence it is not a boundary, and a vague release mandate is what eventually
+  publishes something at 03:00.
+- **What** may be released and from which branch; **when** — batched how, after
+  which *named* checks; **what proof** must be held first, results actually read
+  rather than an impression; **what must still be asked** every time; and **what
+  stays permanently forbidden**.
+- **What makes a release worth cutting** — a sprint, an epic's children all closed,
+  N merged issues. Without it the orchestrator either releases per merge, a stream
+  of meaningless versions burning shared runners, or never releases at all.
+- **Who owns the rollback.** Name a person and setup says so plainly: that person
+  already owns the release, so the honest configuration ends the agent's leg
+  *before* the irreversible step. It offers to move the boundary there; declining
+  is a choice, not a mistake.
+
+Grant every release shape and setup pushes back once — credentials sitting in the
+environment of a session that runs unattended for weeks, and a 03:00 rollback being
+a judgement call under time pressure with partial information — then records what
+you decide. It is your fleet.
+
+### What setup reads for you
+
+Setup discovers factual defaults before it asks for them. `git remote get-url
+origin` supplies the tracker repo and single-repo routing key; bounded `gh` calls
+supply the default branch, existing queue/state labels, branch-protection checks,
+environments, an unambiguous npm package name, and GitHub Projects/open milestones.
+Each discovered value is shown with its evidence and remains editable at the same
+prompt. Discovery only seeds a fresh interview: a re-run starts from the saved
+project, so an operator-edited value is never guessed again.
+
+Judgment and prose still belong to the existing confined model probes, and **every
+answer is a proposal**:
+
+- **Gates.** Reads each routing repo's CI workflows, `package.json` scripts and
+  `Makefile`/`justfile`, then pre-fills the [gates](#configuration) prompt with the
+  exact commands and the `cwd` each runs from, so your gates match what CI runs. It
+  reports the evidence it used, and an honest "this repo has no cheap local check"
+  is a real answer rather than an invented `npm test`.
+- **Project context** and **the release procedure.** Drafted across *every* routing
+  repo — which repo owns which concern, which ship together, where the release
+  machinery actually lives — then shown to you in full and kept **only if you
+  confirm**. `POLICY.md` is re-read on every tick, so a paragraph you never read
+  would become an instruction the orchestrator follows all week.
+
+A model probe has **no shell, no editor and no verbs**: it reads files and answers,
+and a tool it was not given is refused rather than allowed. It is not a sandbox —
+it runs as your own user and reads what you can read — which is why it is pointed
+only at repos you configured yourself.
+
+**Setup never fails because discovery or a probe did.** No `gh`, no auth or
+network, a private repo, no omp peer, a clone failure, a timeout, or a malformed
+reply each produces a warning and leaves the typed default in place. Every question
+is still asked.
+
+Skip the reading half entirely with `--no-ai`:
+
+```bash
+omp-conductor setup --no-ai
+```
+
+To fill in or revise just the brief later — the two `POLICY.md` sections above — run
+the `brief` area, which re-asks the judgment questions and re-runs the probes:
+
+```bash
+omp-conductor setup brief
+```
+
+### Changing one setting
+
+`config.json` is wizard-written, so changing a value means running the wizard —
+and a wizard that re-asks twenty questions to add one key is a wizard people edit
+the file behind instead. So a re-run against a project that is already configured
+opens with one question:
+
+```text
+"platform" is already configured — what would you like to do?
+> Change one area
+    asks one area's questions; every other answer is carried through from the saved config
+  Walk every question again
+    the full interview, every prompt pre-filled with what is configured now
+  Add another project
+    full interview for a new project; existing projects stay as they are
+```
+
+Amending is the default. Pick it and the eight areas are listed with what each one
+says right now, so the row you want is the row you can see:
+
+```text
+Which area? Each row shows what it says now
+  tracker & repos — acme/platform, queue "ready-for-agent", "repo:" → platform, api, web, worker
+  gates — platform: bun run check; api: ruff check . @ backend; web: pnpm lint…
+  caps & worker model — 2 workers, 120 turns, 90m, $25/day, 2 attempts (all defaults) — harness default model
+  code graph — not configured — workers grep
+  authority — merge=orchestrator, release=orchestrator
+  escalation & triage — tier 2 pages Telegram 123456789, comments too, triage external
+  reporting scope — material — escalations, plus green PRs, second failures, and anything that stops the fleet
+  orchestrator brief — none at ~/.omp/conductor/worktrees/ORCHESTRATOR.md
+```
+
+Only that area's questions are asked. Every other answer is read back out of
+`config.json` and written again unchanged — the same answers, the same builder,
+the same single confirm, so there is still exactly one thing in this package that
+writes a config, and it still writes nothing before you agree. The consent screen
+leads with the delta and then shows the whole project as it would be written:
+
+```text
+amending       code graph  —  project platform
+  was            not configured — workers grep
+  now            ~/.cache/conductor-graph/acme — 4 clone(s): platform, api, web, worker
+  carried over   tracker & repos, gates, caps & worker model, authority, escalation & triage, reporting scope, orchestrator brief
+                 read back from ~/.omp/conductor/config.json and rewritten unchanged
+```
+
+A first run, or a project name this config has never seen, never sees either
+question: there is nothing to amend, so it is the full interview exactly as
+before. Choosing *Walk every question again* asks once to confirm the replace
+(so a silent overwrite cannot happen from muscle-memory Enter) — every prompt
+pre-filled with what is configured, Enter to keep it — with one wrinkle worth
+knowing: the two authority confirms and the orchestrator-session confirm cannot
+start on "yes", so Entering through the full interview **revokes** a delegation
+rather than renewing it. Amending the `authority` area names the current grant in
+the question, which is the safer way to leave one alone.
+
+### Adding another project
+
+One daemon serves every configured project. To put a second (or third) fleet on
+the same host without touching the first:
+
+```bash
+omp-conductor setup --project second
+# or pick "Add another project" from the re-run chooser
+```
+
+That is a full interview for the new name only. Defaults land under
+`~/.omp/conductor/projects/<name>/{worktrees,mirrors}` so two fleets never share
+a cwd; the first project's existing flat `worktrees`/`mirrors` paths are never
+migrated. A `workspaceRoot` that collides with another project is refused with
+both names in the error. Re-using an existing name asks amend-or-replace before
+anything is written.
+
+After apply, setup provisions labels, brief, tick config (with `project` +
+`agentName`), topic binding, smoke, and arm for the new project only, then prints:
+
+- `omp-conductor restart --now` — the running daemon picks up the new project
+  only after reload (printed, not auto-run when workers are live)
+- a copy-pasteable **herdr handoff**: `herdr --session conductor workspace create
+  --cwd <workspaceRoot> --label <project> --no-focus`, then `herdr --session
+  conductor agent start <project> --kind omp --pane <pane-id>` into that empty
+  pane (never into a live orchestrator), plus the `FLEET_CWDS` list for
+  multi-fleet recovery
+
+`omp-conductor setup gates --project second` (and every other area) still amends
+only that project.
+
+### Keeping a brief current
+
+The standing prompt is three layers:
+
+| Layer | File | Updates how? |
+| --- | --- | --- |
+| Package floor | `src/briefs/orchestrator.md` | Every tick recomposes it into `ORCHESTRATOR.md` from the installed package. Upgrade the package in this host's existing install root + restart is enough. |
+| Shared policy | `$OMP_CONDUCTOR_HOME/SHARED_POLICY.md` (default `~/.omp/conductor/SHARED_POLICY.md`) | Optional, host-wide: one file applying to **every** project. Create it by hand beside `config.json`; it is re-read each tick like `POLICY.md`, so an edit binds the next heartbeat. The per-project `POLICY.md` overrides it where the two conflict. |
+| Fleet policy | `POLICY.md` | Yours. Setup writes the scaffold once; the Learning loop edits only this file. |
+| Composed view | `ORCHESTRATOR.md` | Regenerated from floor + `SHARED_POLICY.md` (when present) + `POLICY.md` on each tick (and at setup). Do not hand-amend it for durable policy. |
+| Worker brief | `src/briefs/worker.md` | Read per run from the package. |
+
+```bash
+omp-conductor brief-upgrade                 # report overlay / legacy state
+omp-conductor brief-upgrade --migrate       # dry-run: bannered ORCHESTRATOR.md → POLICY.md
+omp-conductor brief-upgrade --migrate --apply
+omp-conductor brief-upgrade --retrofit      # #20: propose YOURS TO EDIT cut on a hand-written brief
+omp-conductor brief-upgrade --retrofit --apply
+```
+
+- **Overlay already active** (`POLICY.md` present): protocol updates need no brief-upgrade.
+  `brief-upgrade` reports which layers compose — floor, optional shared policy,
+  and `POLICY.md` — and the composed banner names all three when the shared one
+  exists, so a reader can tell which layer a paragraph came from.
+- **Legacy bannered brief**: `--migrate` lifts the owned half into `POLICY.md`
+  and recomposes. Previous brief and policy versions go to
+  `$OMP_CONDUCTOR_HOME/backups/briefs/` (default
+  `~/.omp/conductor/backups/briefs/`), named with their source filename and
+  timestamp.
+- **Hand-written brief** (no banner): `--retrofit` inserts the banner before the first Releases / Project context / Reporting / Amendments heading; then `--migrate`.
+- **The legacy single-file merge is gone** (0.4.3). A bare `--apply` exits `2`
+  naming the two paths that remain, rather than rewriting a brief nobody asked
+  it to. `--migrate` is the cross-version ABI: an upgrade keeps calling it, and
+  an overlay fleet tolerates its absence because the floor recomposes each tick.
+- **`status` names the layout**, so a fleet still on a legacy brief is visible
+  where an operator already looks: `brief     overlay (package floor + POLICY.md)`,
+  or `brief     legacy-bannered — run omp-conductor brief-upgrade`.
+- **Existing sidecars**: a composed refresh relocates conductor-generated
+  `ORCHESTRATOR.md.bak-<timestamp>` and `POLICY.md.bak-<timestamp>` files into
+  that backup directory. Other `.bak` files stay untouched.
+
+`--file PATH` checks a brief that is not where the wizard would have put it.
+
+The **Learning loop** proposes diffs against `POLICY.md` for you to approve over
+Telegram. It also learns from repeated operational friction. The daemon
+automatically rolls up repairable admission holds; the orchestrator records
+judgments code cannot make with:
+
+```bash
+omp-conductor friction escalation-digest --detail "routine retry belonged in the digest" [--issue N]
+omp-conductor friction report-noise --detail "green status repeated with no operator action"
+omp-conductor friction report-surprise --detail "a material failure was missing from the report"
+```
+
+Three observations within seven days make a bounded signal eligible for one
+tick. After it is surfaced, that signal cools down for seven days. A signal is
+evidence to investigate, never an automatic policy edit: the existing one-at-a-
+time Telegram approval, `POLICY.md`-only edit, Hard-boundary prohibition, and
+**Amendments** log still apply.
+
+## How one tick works
+
+Per tick, for the daemon's project:
+
+1. **Verify and settle pushed PRs.** For every run in `pushed-pending`, repeat
+   the independent head/check verification; green → `pushed-green`, red →
+   `failed`, and still pending stays occupied. For every verified
+   `pushed-green` run, ask what became of its PR. Merged → `merged`; closed
+   without merging → `failed`. Unknown answers leave the row unchanged. Every row
+   that settles also loses its `agent:in-progress` label. This
+   maintenance runs even while dispatch is paused or workers are active, so
+   status converges on the five-minute tick cadence. It also runs above admission
+   so a row settled here frees its issue in the same tick. See
+   [what settles a green PR](#what-settles-a-green-pr).
+2. **Paused?** If the pause sentinel exists, the tick claims nothing and returns.
+   Settlement has already run, but no queue or admission work occurs. This makes
+   `omp-conductor hold` take effect without signalling the process.
+3. **List the queue.** Open issues in `tracker.repo` labelled `queueLabel`.
+4. **Filter and route.** An issue is eligible only if it carries the queue label
+   and none of the three state labels (`inProgress`, `blocked`, `failed`). Eligible
+   issues are partitioned into routable and unroutable.
+5. **Escalate the unroutable** at Tier 1, quoting the repo labels actually seen and
+   the configured repo names. These are never dispatched.
+6. **Check spend.** If spend since local midnight has reached `dailySpendUsd`, the
+   daemon **pauses itself**, pages at Tier 2, and returns.
+7. **Check capacity.** `maxConcurrentWorkers` minus *live* workers (runs in
+   `claimed` or `running`) gives the free slots. A pending or green PR occupies
+   its issue but not a slot: its worker is finished, and counting pushed PRs
+   would let two completed workers stop the fleet.
+   If no slot is free, the tick logs and returns.
+8. **Check the plan allowance.** If `caps.planUsage` names a window, the daemon
+   reads it (cached, see [Caps](#caps)) and holds *every* candidate under
+   `plan-usage-cap` when the window is at or over its threshold. Unlike the
+   spend cap this does **not** pause the daemon: the window resets on the
+   provider's clock, so dispatch resumes by itself.
+9. **Admit issues** up to the free slots, skipping any issue that already has
+   an active run — including a pending or green PR, so a second attempt cannot
+   land on a live PR. Repeated implementation failures consume
+   `maxAttemptsPerIssue`; cap kills, daemon orphans and answered blocks consume
+   the independent `maxContinuationsPerIssue`. Exhausting either escalates.
+10. **Ask the tracker whether the work already exists.** For each candidate that
+    survived step 9 — so at most one API call per free slot, never one per queued
+    issue — the daemon asks whether an **open** PR already closes it. An open PR
+    normally holds the issue. One narrow exception permits a routed continuation:
+    the latest run must be terminal, and the open PR must be that run's retained
+    work — either the PR URL it recorded or a PR opened on the branch it retained.
+    The branch half matters because a run can be cap-killed before its worker ever
+    opens a PR, leaving a retained branch and no recorded URL; a PR pushed to that
+    branch afterwards is still the continuation target. Drafts count because their
+    branch can hold the only copy of the work.
+    The tracker also finds work missing from a new, moved, restored, or cleared
+    store. If the check fails, the candidate is **held**, not admitted, and
+    retried next tick: the cost of holding is five minutes, the cost of admitting
+    on an unknown is a burned attempt and a duplicate PR. Only that candidate is
+    held, so a flaky API cannot stall the rest of the queue.
+11. **Record the pass.** Persist ready/routed/admitted counts and group every hold
+    under a stable reason code with at most five sample issue numbers. Tracker
+    failures mark the summary `DEGRADED`; capacity, sibling, open-PR and budget
+    holds remain normal policy state.
+12. **Dispatch** the admitted issues concurrently.
+
+Then, per admitted issue:
+
+1. **Create the run row (`claimed`) — before any worktree or session exists.**
+   This ordering is the whole crash-safety story: the *row*, not a label, is the
+   guard against dispatching the same issue twice. It is local and written before
+   anything that can fail; if the process dies at any later point, the startup
+   orphan sweep marks the left-behind row `orphaned` and the orchestrator's drain
+   duty triages it (see below). The `agent:in-progress` label is a write-behind
+   projection of that row — enqueued in the same breath and applied to the tracker
+   by the projector with retry — so even a tracker that refuses the write cannot
+   recreate a duplicate PR while the guard is unavailable.
+2. Run the tick's post-admission projection pass, which applies freshly enqueued
+   label ops on the healthy path.
+3. Clear any stale tree for this issue, then add a fresh worktree at
+   `<workspaceRoot>/<issue>` cut from the bare mirror at `<mirrorRoot>/<repo>.git`,
+   on the run's branch off the repo's default branch.
+4. Allocate a session transcript under `<state dir>/sessions/`, one per attempt,
+   and move the run to `running`. The run record keeps the exact path and a
+   failure escalation quotes it, so you can read what the worker actually did.
+5. Run one omp session with the rendered brief, under the turn and wall-clock caps.
+6. Record the outcome:
+
+   | Outcome | Labels | Worktree | Escalation |
+   | --- | --- | --- | --- |
+   | `pushed-pending` | `agent:in-progress` stays while the daemon rechecks GitHub | removed | none |
+   | `pushed-green` | `agent:in-progress` stays while the PR is open | removed | none |
+   | `blocked` | swapped to `agent:blocked` | dirty tree committed to the branch, then removed | Tier 1 |
+   | `failed` / `killed` | swapped to `agent:failed` | dirty tree committed to the branch, then retained until the PR or issue is terminal | Tier 1 |
+   | unexpected error | swapped to `agent:failed` | same | Tier 1 |
+
+   `pushed-pending` and `pushed-green` are not the end of the row: later ticks
+   verify outstanding checks and settle the PR once it resolves, and a row that
+   settles gives up its `agent:in-progress` label. See
+   [what settles a green PR](#what-settles-a-green-pr).
+
+   Every label write the dispatcher makes goes through the label projection
+   outbox and is applied to the tracker by the projector with retry, strictly in
+   the order it was enqueued per issue — a later op for one issue never lands
+   before an earlier one that is still owed. A state-label swap on a dispatch
+   outcome enqueues the new label ahead of the old one's removal, so the issue
+   is never briefly bare (the shape eligibility reads as fresh work), while a
+   requeue (`swapToQueue`, `unblock`) enqueues its removals ahead of the queue
+   add for the same reason in reverse: the issue must not look claimable before
+   its stale state label is gone. A refused write is deferred with backoff
+   instead of dropped, and `status` shows any un-applied lag on a
+   `labels projection` row.
+
+   **Every continuable end salvages the tree first.** A turns-cap kill, a
+   wall-clock kill, a crash and a graceful block all leave a tree the next
+   attempt removes `--force` — only the run's *branch* is preserved across
+   attempts. So before the escalation is written, a dirty tree is committed to
+   the run's own branch as `wip(#<issue>): attempt <n> <ending> — auto-salvaged`
+   (everything, including files git has never seen) and pushed, and the
+   escalation says where it went: `WIP committed to <branch> @ <sha>`. A push
+   that is refused leaves the commit in this host's mirror and says so.
+
+   Blocking was excluded from this until #118, on the argument that a worker
+   which stops on purpose has turns left to commit for itself. It cost a
+   34-file refactor: the worker blocked to ask whether a failing test was
+   obsolete — which is precisely a worker declining to commit a half-migrated
+   tree — and the daemon removed the tree seconds later, leaving the run branch
+   and `origin/main` on the same commit. A `pushed-green` or `pushed-pending`
+   run is now the only end that does not salvage: its deliverable is already on
+   a remote branch, and appending a WIP commit would turn the PR the daemon
+   just verified red.
+
+   **A salvage that fails keeps the tree and stops the issue.** If git refuses
+   the commit, the worktree is the only copy in existence, so it is retained
+   whatever the run's outcome was, the row records the failure, and the issue
+   is held out of dispatch with the `unsalvaged-wip` reason — because claiming
+   it is what would finally destroy the tree. `status` shows it under `wip` as
+   `UNSALVAGED`, and `omp-conductor unblock <n>` refuses. Recover the tree by
+   hand, then `unblock <n> --force` records that you accepted it and releases
+   the hold.
+
+   **A preserved tip is named to the next worker.** The sha is written to the
+   run row, shown by `status` and the board, and the continuation brief tells
+   the resuming worker the exact commit it is building on and that it is the
+   only copy.
+
+   Later ticks reap retained failure trees in bounded batches after the tracker
+   proves their PR merged/closed or their issue closed, provided no live run or
+   queued continuation owns the issue. Cleanup fetches remote refs first and
+   keeps any dirty tree or branch with uniquely local commits. Only then does it
+   remove the physical tree, prune registrations, and delete the obsolete local
+   mirror branch. Unknown tracker, network, repo, or git state is a no-op.
+
+### What a restart does to runs that were in flight
+
+A `claimed` or `running` row is a promise that a worker process exists, and a
+daemon that just started knows that promise is broken: its workers died with the
+previous process. At startup — unless another daemon is alive, so a foreground
+`daemon --once` cannot orphan a running daemon's real workers — every such row is
+**salvaged first** (dirty tree → `wip(#N): attempt N killed by a daemon restart —
+auto-salvaged` on the run's branch, same path as a turns-cap kill), then moved to
+`orphaned`, with a log line naming the issue, the attempt and the worktree. That
+frees the slots immediately; a fleet must never resume as deadlocked as it
+crashed, and uncommitted edits must not wait for a human with `bun -e`.
+
+Only the rows change after salvage. The issue keeps `agent:in-progress` — the
+label is the crash guard against double-dispatch — and deciding what the dead
+worker's remains are worth is the orchestrator's drain-duty judgement, spelled
+out in its brief: an open green PR goes to the merge path, a salvaged sha is a
+continuation hand-off, and a clean orphan has its label released so the next
+tick re-claims it. Orphans consume `maxContinuationsPerIssue`, not failed
+implementation attempts, so crashes cannot starve the retry needed for a real
+code or CI failure — and a crash loop still escalates.
+
+### Deploying a new package onto a busy fleet
+
+`systemctl restart` / `omp-conductor restart` is safe for **work product** once
+this version is installed: startup salvage commits dirty trees before orphaning
+rows, and salvage rewrites the mirror's managed `info/exclude` to the package's
+current list before `git add` so a narrowed ignore cannot hide deliverables.
+
+It is still disruptive for **in-flight sessions** because the worker process dies
+and the attempt is spent. Update through the lifecycle command rather than
+hand-installing or restarting individual surfaces:
+
+```bash
+omp-conductor upgrade
+```
+
+It pauses new claims, drains workers, installs one pinned release across all
+surfaces, restarts, verifies twice, and resumes only if dispatch was initially
+running. If an install, restart, or verification step fails, dispatch remains
+paused and the command exits nonzero.
+
+Do **not** edit files under the running install and expect the daemon to keep
+dispatching — the integrity tripwire pauses and pages. Upgrade by whole release
+so the new process records a fresh baseline.
+
+### What settles a green PR
+
+The worker watches CI, then reports the PR URL and the exact remote head SHA it
+observed. The daemon independently reads the PR again and requires it to be open,
+non-draft, still at that head, and backed by a non-empty check rollup in which
+every check succeeded or was skipped. Missing or nonterminal checks become
+`pushed-pending` and are rechecked on later ticks; red or cancelled checks become
+`failed` with a bounded job/log digest. Only verified evidence becomes
+`pushed-green`.
+If a failed report mentions PRs only in prose, the daemon retains the last URL
+whose `owner/repo` matches the run's repository; links to other repositories are
+ignored. This preserves the continuation target without trusting an unrelated
+PR mentioned in the same report.
+
+What happens after verification is a human's decision, taken minutes to days
+later and never announced to the daemon — so every tick asks the tracker about
+every pushed PR it is still holding:
+
+| PR | Row becomes | Why |
+| --- | --- | --- |
+| merged | `merged` | The work landed. This is the state `merged` was reserved for. |
+| closed without merging | `failed`, class `returned-for-revision`, with the PR in `lastError` | A human read the work and asked for another pass. Leaving it `pushed-green` strands the issue forever behind a PR nobody will merge, and calling it `merged` is a lie about code that is not on the base branch. `failed` is the honest row state; the class preserves the review decision and releases the issue so a re-queue can be attempted again. |
+| still open | unchanged | The normal steady state. Its issue must stay occupied, or a second attempt lands on the live PR. |
+| could not be determined | unchanged | A flaky network, a revoked token, a deleted PR. An unknown answer never settles a row; the next tick asks again for free. |
+
+Run history is untouched. A PR closed without merging consumes one continuation,
+not a failed implementation attempt; a merge spends neither budget. A settled
+row also loses `agent:in-progress` from its issue: the row transition and label
+removal are one fact, and a terminal answer about the PR proves no worker
+process owns the issue,
+so the duplicate-dispatch guard it exists for is spent. The removal is *enqueued
+on the label projection outbox in the same breath as the terminal write* — a
+durable local write that cannot fail on the tracker — so the row settles at once
+and the projector applies the label with retry. A tracker that refuses the
+removal can no longer strand it: the op stays owed, eligibility overlays the
+pending removal so the issue is not held back by a label that is already decided
+gone, and `status` shows the lag. Anything beyond that one release — a re-queue,
+a `blocked` marker — is still the orchestrator's drain-duty judgement. One
+unreachable PR costs its own row and nothing else; the rest of the sweep still
+settles.
+
+Until this existed, nothing ever revisited a `pushed-green` row: the startup
+reconciler only settles rows that held a process, and `merged` went unwritten. On
+2026-08-07 the reference fleet reported three active runs whose PRs were all
+merged and whose issues were all closed, through two daemon restarts — and because
+the active set *is* the busy set, those three issues were permanently unclaimable.
+A status page that has stopped being evidence is worse than no status page.
+
+The label half of that outlived the row half by two days. On 2026-08-09 a merged
+PR and a closed-unmerged one both settled their rows correctly and both left their
+issues carrying `agent:in-progress`, which eligibility reads as "a worker owns
+this" — with the brief forbidding the orchestrator from editing a state label and
+`unblock` declining to clear that one, neither issue could ever be claimed again.
+
+### Base-branch health after merge
+
+The daemon records two different facts after a merge:
+
+- The **post-merge audit** attributes a regression to one merge. For up to 24
+  hours, it checks only push-triggered workflow runs for the exact merge SHA and
+  base branch. A new red result adds `base-branch-red` evidence and escalates.
+- **Current health** drives `status` and release policy. On every sweep, the
+  daemon resolves the live head of each branch it merged into during the last
+  seven days, then reads only push-triggered runs for that head and branch. The
+  status row includes the head SHA and run count.
+
+Current health is `green` only when every observed run completed successfully,
+neutrally, or skipped. A failing conclusion is `red`; an in-progress or
+unrecognised conclusion is `pending`; and a head with no push-triggered run is
+`unknown`, never green. Pending and unknown heads are rechecked. Green and red
+heads are read again when the branch moves, so an old verdict cannot describe a
+new commit. If GitHub cannot return the head or its runs, the daemon keeps the
+last honest row instead of replacing evidence with a network failure.
+
+The `base-branch-green` release requirement reads this current live-head row for
+the repository being released. Red, pending, unknown, and absent evidence all
+refuse the release.
+
+### The settlement audit
+
+Two lines of the worker report template were once taken on faith. `state:
+pushed-green` stopped being believed in #85: a claim is now verified against
+GitHub before a run settles. The `changed:` line stopped being *asked for* in
+#488: the file list is derived at settlement from the pull request's own diff,
+so a worker that writes no file list still settles with a correct one, and a
+report whose list contradicts the diff is rewritten to say what the diff says.
+The worker's narrative — what changed and why — is untouched; only the file list
+stops being hand-authored.
+
+So at settlement the daemon fetches the pull request's diff, derives the report's
+`changed:` line from it, and checks the diff itself for weakened tests. What it
+finds is a **settlement audit flag** — advisory, never a gate. A flagged run
+settles exactly as an unflagged one does; nothing here can change a run's state,
+hold a merge, or spend an attempt.
+
+| Flag | Raised when |
+| --- | --- |
+| `changed-line-missing` | The settlement could not read the PR's diff, so no `changed:` file list was derived. The one disclosure fault left, and it is a tree-read failure, not a worker's. |
+| `test-file-deleted` | A test file left the tree with no rename to account for it. |
+| `test-disabled` | A `.skip` / `.only` / `xit` / `@pytest.mark.skip` / `t.Skip` marker appears on a line the PR added. |
+| `assertions-removed` | An assertion was commented out, or a test file lost more assertions than it gained. |
+| `test-timeout-raised` | A named timeout in a test file went up — compared against its own previous value, so a brand-new timeout is not a finding. |
+
+A flag on a test file the dispatching issue never names is marked
+`[unattributed]`: that is the "don't weaken tests you didn't write" case, and it
+is the one worth reading first.
+
+Flags reach you three ways: appended to the settlement report, stored on the run
+row and shown under the run in `omp-conductor status` for as long as its PR is
+open, and — once per flagged settlement — as a tier-1 escalation to the
+orchestrator, whose brief says what judgement each flag invites.
+
+**A clean, accurately reported PR produces nothing.** That is a design
+constraint, not an aspiration: an audit that fires on honest work gets muted, and
+a muted audit is worse than none because the fleet still believes it is being
+checked. Every rule resolves ambiguity towards silence, and each accepts a named
+blind spot to stay quiet — a renamed test file is not a deleted one (even when
+git did not detect the rename, matched by basename), a `.skip` inside a string
+literal or a recorded fixture is not a skip, and a rewritten test that keeps its
+coverage is not a weakening.
+
+The analyser is pure: it takes a parsed diff, the report and the issue text, and
+returns flags. Only `Tracker.prDiff` touches the network, and a diff it cannot
+read produces no flags *and says so* — silence about a diff nobody read is not a
+clean bill.
+
+### Continuation runs
+
+When a worktree is provisioned onto a branch that already exists in the mirror
+(reattach after a prior attempt, orphan, or turns-cap auto-requeue), the worker
+brief includes a **Continuation** section: read `git log` / `git diff` against
+the default branch first, and do not recreate work already on the branch.
+
+A **turns-cap kill with attempts remaining** salvages the tree, puts the queue
+label back on, and skips the failed label so the next tick reclaims as a
+continuation automatically.
+
+### Branch names
+
+`<type>/<slug>`, where the type is `fix` when any label's last segment (after `:`
+or `/`) is `bug`, and `feat` otherwise. The slug is the issue title folded to
+`[a-z0-9-]`, and the whole ref is capped at 60 characters. It is computed from the
+issue alone, so a retried run recomputes the same branch and finds its own work
+instead of forking a second one.
+
+## Routing
+
+An issue must carry **exactly one** `repo:<name>` label naming a repo in
+`routing.repos`. The prefix is `routing.labelPrefix` and defaults to `repo:`.
+
+Routing never guesses. An issue it cannot resolve to a single configured checkout
+is handed back as unroutable:
+
+| Reason | Condition |
+| --- | --- |
+| `no-repo-label` | The issue carries no label starting with the prefix. |
+| `multiple-repo-labels` | It carries two or more distinct prefixed labels. A repeated identical label is deduplicated, not treated as an ambiguity. |
+| `unknown-repo` | Its single prefixed label names a repo that is not in `routing.repos`. |
+
+In all three cases the issue is **escalated at Tier 1 and never dispatched**. The
+fix is always the same, and the escalation says so: put exactly one
+`repo:<name>` label on the issue.
+
+This is deliberate. A request that spans two repos, taken whole by one worker, is
+the precise failure this guard exists to prevent: the worker cannot open a PR
+against two checkouts, so it improvises — it vendors a copy, edits the wrong repo,
+or produces a PR that cannot be merged without the other half. Splitting a
+multi-repo request is a human decision about contracts; it is not something to
+infer from a label. Sending the issue back costs a label edit; guessing costs a
+bad merge.
+
+## Host sizing and memory
+
+Workers are **child processes** of the daemon (plus one long-lived orchestrator
+session), each its own pid, talking back over a unix socket. They are still
+inside the service's cgroup, so systemd's Memory peak for
+`omp-conductor.service` is daemon + every live worker + the orchestrator + any
+MCP stdio children those sessions mount. `MemoryMax=` governs that whole total,
+not one process.
+
+The generated unit starts `omp-conductor daemon --port 8787` without a
+`--project` filter, so one daemon serves every configured project. Its automatic
+`MemoryMax=` tier uses the sum of resolved `maxConcurrentWorkers` values across
+all projects: `3G` for a total of one worker, otherwise `5G`.
+
+On the reference deploy that produced [issue #51](https://github.com/TerrifiedBug/conductor/issues/51):
+
+| Shape | Observed |
+| --- | --- |
+| Idle / workers restarting | ~430 MB RSS for the daemon alone |
+| Two workers + orchestrator, busy | **3.2–4.2 GB** Memory peak for the unit; up to ~800 MB swap |
+
+That peak is **expected for concurrent SDK sessions**, not evidence of a
+conductor-side leak: the SQLite store is disk-backed, admission state is
+per-tick, and worker sessions are disposed when a run ends. What grows is the
+session heap (conversation + tool output); a single graph-assisted run has been
+measured in the hundreds of thousands of characters of tool output.
+
+**Practical guidance**
+
+- Prefer **≥16 GiB RAM** for the default `maxConcurrentWorkers: 2`, and do **not**
+  co-locate ClickHouse / other multi-GB services beside that fleet on an ≤8 GiB
+  box.
+- On hosts under ~16 GiB, keep the **sum** of every project's
+  `maxConcurrentWorkers` at **1**. `omp-conductor setup` chooses that default
+  for a new project when it can read host RAM and warns before applying a
+  configuration whose combined capacity exceeds the host recommendation.
+- Supervise the daemon with a unit that sets `SuccessExitStatus=0 143`; setup
+  renders `MemoryMax=3G` for one configured worker and `MemoryMax=5G` for two
+  or more.
+- `omp-conductor status` prints daemon `rss` from `/healthz` when the process is
+  up, so you can see pressure without scraping journald.
+
+## Caps
+
+Caps resolve per project: the global `defaults` block, then the project's own
+`caps` layered on field by field, so a project that pins one cap still inherits the
+rest. `0` is a real value (a hard stop), not "unset".
+
+| Cap | Default | What it protects |
+| --- | --- | --- |
+| `maxConcurrentWorkers` | `2` (setup may write `1` on &lt;16 GiB hosts) | Parallel omp sessions, each a child process of the daemon and all inside its cgroup. Two, because **CI runner slots, not model tokens, are the usual throughput ceiling** — a third worker would starve its own PR checks on a small self-hosted runner pool. On hosts under ~16 GiB RAM, prefer `1` so the unit stays out of swap ([host sizing](#host-sizing-and-memory)). Raise it only if you actually have the runners *and* the RAM. |
+| `maxConcurrentWorkersPerRepo` | `1` | Max live workers in the **same repo**. The mirror, branch-protection staleness and shared CI egress are all per-repo collision domains, so extra slots should land on other repos. Raise it only when a repo genuinely needs two workers at once. |
+| `dailySpendUsd` | `25` | Rolling-day spend ceiling in USD, or `null` for no spend gate. `0` is a hard stop. Metered from assistant `usage.cost.total`. |
+| `planUsage` | `null` (unmetered) | Subscription/plan allowance guard: `{ "windowId": "anthropic:7d", "maxUsedFraction": 0.85 }`, or `null` for no plan gate. Independent of `dailySpendUsd` — see [Plan allowance](#plan-allowance-planusage) below. |
+| `workerMaxTurns` | `120` | Base ceiling for each new worker. Catches a session looping without converging; use `omp-conductor extend` to raise one live run or one issue's next attempt without changing this default. |
+| `workerMaxTurnsCeiling` | `240` (twice the effective `workerMaxTurns` when omitted) | Upper bound for per-issue turn extensions. Prevents the loopback control from granting an unbounded worker budget. |
+| `workerWallClockMs` | `5400000` (90 minutes) | Wall-clock ceiling for one worker. A session that is merely stuck spends no turns, so turns alone cannot detect it. |
+| `maxAttemptsPerIssue` | `2` | Failed implementation or CI attempts before escalation. Operational stops do not consume this budget, so salvage can continue without stealing the retry needed for a real failure. |
+| `maxContinuationsPerIssue` | `2` | Cap-kill, daemon-orphan and answered-block resumes before escalation. This independently bounds crash/resume loops. |
+
+Days are counted from **local midnight**, matching how a human reads "today".
+
+Set `dailySpendUsd` to `null` (wizard: blank) for no money gate — turns and wall-clock still apply. Hitting a numeric `dailySpendUsd` is not the same as hitting the other caps. A concurrency
+limit simply defers work to a later tick. The spend cap **pauses the daemon and
+pages at Tier 2**: a loop that is burning money has to halt itself, because
+waiting for someone to notice tomorrow is how a runaway becomes expensive.
+Work resumes only after `omp-conductor resume`.
+
+`workerMaxTurns` and `workerWallClockMs` are enforced inside the session driver.
+The daemon reads a live run's effective turn ceiling at every turn boundary. Use
+`omp-conductor extend <issue> --turns N [--project NAME]` to raise it without
+restarting or reconstructing the session. For a live worker, extension is
+monotonic: equal or lower values are refused. If the latest run is failed,
+killed, orphaned, or blocked, the command instead stores a one-shot ceiling for
+that issue's next attempt. A next-attempt ceiling must exceed the effective
+project base, and every extension must stay at or below
+`workerMaxTurnsCeiling`. `status` shows both active ceilings and pending
+next-attempt overrides. The store consumes an override atomically when it claims
+the next run, so later attempts return to the project base. Config edits change
+that base on the next tick but do not change workers already in flight. A cap
+that fires aborts the run, records it as `killed`, and names the ceiling in the
+escalation.
+
+Pause one live worker cooperatively with
+`omp-conductor worker pause <issue> [--project NAME]`. The daemon aborts the
+active turn to an idle harness state, freezes the remaining wall-clock budget,
+and keeps the run in the Running lane. `status` overlays `paused`/`pausing` from `/healthz` on that active-run line while the SQLite row stays `running`. `omp-conductor worker resume <issue>`
+continues the same session with a prompt to re-check its last action before
+proceeding. To end that run instead, use
+`omp-conductor worker stop <issue> --reason TEXT [--project NAME]`. Stop works
+from running or paused, salvages dirty work before removing the worktree, records
+the distinct terminal `stopped` state, and removes `agent:in-progress` through
+the label outbox. A salvage failure keeps the only copy in place and reports its
+path. Stopped runs consume neither implementation-failure nor continuation
+budget. Repeating stop reports the already-terminal state. These worker controls
+are separate from fleet-level `pause`, which stops new claims.
+
+### Plan allowance (`planUsage`)
+
+`dailySpendUsd` meters money, which is the only thing an API-billed account can
+run out of. A fixed-price subscription cannot be expressed that way: the real
+ceiling is a **provider allowance** — a weekly token window whose marginal
+dollar cost is zero and whose exhaustion stops every session on the host.
+Pricing that into the dollar meter would mean inventing a number.
+
+`planUsage` is the second, independent guard. It reads `omp usage --json` — the
+structured form of the harness `/usage` view — and holds new claims while the
+named window is at or over its threshold. Running workers finish normally, and
+**the daemon is not paused**: the window resets on the provider's clock, so
+dispatch resumes by itself once a fresh reading is below the threshold. Nothing
+estimates a plan quota from conductor's own transcript token counts.
+
+```json
+"caps": {
+  "planUsage": { "windowId": "anthropic:7d", "maxUsedFraction": 0.85 }
+}
+```
+
+**Naming the window.** `limits` in the payload is a *list*, not a single
+number: one Anthropic account reports `anthropic:5h`, `anthropic:7d` and the
+tier-scoped `anthropic:7d:fable` at the same time, and other providers add
+their own. So the cap names its window rather than taking whichever entry came
+first. Run this on the fleet host and copy an `id`:
+
+```bash
+omp usage --json | jq -r '.reports[].limits[] | "\(.id)  \(.amount.usedFraction)  \(.amount.unit)"'
+```
+
+A bare window key (`"7d"`) also works, but **only** when exactly one reported
+allowance carries it. On an Anthropic account `7d` matches two, and the guard
+refuses to guess.
+
+**`maxUsedFraction` is a fraction, not a percentage.** `0.85` holds at 85%.
+A value outside `0`–`1` is rejected at config load, because `85` would mean
+"hold at 8500% consumed" — a guard that reads as configured and can never fire.
+Comparison always goes through the provider's `usedFraction`, never a raw
+count: `unit` is `percent` for Anthropic and `unknown` with raw counts for
+`xai-oauth`, so a threshold compared against `used` misreads any non-percent
+provider by orders of magnitude.
+
+**Availability policy.** The guard never displays a number it did not read, and
+never shows a fabricated `0% used`. What each situation does:
+
+| Situation | `status` / `board` | New claims |
+| --- | --- | --- |
+| `planUsage: null` | `unmetered` | admitted |
+| Window below threshold | `5% / 85% of anthropic:7d used · resets in 6d 2h` | admitted |
+| Window at or over threshold | same, plus `holding new claims` | **held** (`plan-usage-cap`, Tier 1) |
+| No provider reports a readable allowance, or `omp usage --json` fails | `unavailable — <reason>` | admitted for up to 30 minutes, then **held** and paged at Tier 2 |
+| `windowId` names a window the reading does not contain | `window "<id>" is not in this reading — Reported: …` | **held**, Tier 2 |
+| `windowId` matches more than one allowance | `window "<id>" matches …` | **held**, Tier 2 |
+| The window reports nothing a fraction can be derived from | `window "<id>" reports no comparable fraction …` | **held**, Tier 2 |
+
+The split is deliberate. A *read error* is transient — a token refresh, a
+provider 502, `omp` briefly absent mid-upgrade — and stalling a fleet on one
+would cost more than admitting through it, since spend, turns, wall clock and
+concurrency are all still enforced. Half an hour of continuous failure is not
+an outage, it is a broken meter, and a plan-capped fleet running on a broken
+meter is how the allowance gets spent to zero unnoticed. A *successful* read
+that does not contain the configured window is not a read error at all: the
+source answered, and it says the config names something that is not there. That
+fails closed immediately, like every other config fault in this package, and
+recovers by itself as soon as a reading contains the window again.
+
+Readings are cached for 60 seconds (15 for a failure) so one tick costs one
+provider call rather than one per candidate, and a cached reading is dropped
+the moment its own `resetsAt` passes — that is what makes admission resume at
+the rollover instead of a TTL later. `omp usage invalidate` clears omp's own
+cache; conductor picks the change up at its next read.
+
+Both controls are shown separately, never folded together — `status` prints a
+`spend today` row and a `plan usage` row, and the board's admission line ends
+with `spend $2.40/$25.00  |  plan 5%/85%`.
+
+## Worker model
+
+`workerModel` on a project pins the model its workers run on, as a pattern in
+omp's own model/role syntax (whatever `/model` accepts). It sits beside `caps`
+rather than inside them, because it is not a ceiling:
+
+```json
+"workerModel": "smol"
+```
+
+Omit it and the harness picks, which is the right answer until you have a reason.
+The pattern is passed through unresolved: omp resolves it after its extensions
+load, so a name this package has never heard of still works. If the harness cannot
+honour the pattern it says so, and the daemon logs that per run:
+
+```text
+#412 model fallback: <what the harness substituted>
+```
+
+Worth reading the log for. A run that quietly used a weaker model than you chose
+otherwise looks like a run that was merely unlucky.
+
+## Code-graph discovery
+
+Optional, off unless you answer yes in the wizard, and worth answering yes to for
+one measured reason: **workers spend most of a run finding code, not changing it.**
+On the dogfood fleet a single run typically spends 30–62 `read` calls and 32–69
+`bash` calls against 9–24 edits — 215–390k characters of tool output, roughly four
+fifths of a 120-turn budget — and the runs that died at the turns cap died with
+the work unfinished. A code graph answers "who calls this" and "where is this
+defined" in one call instead of twenty greps.
+
+### Two things this package does not do for you
+
+`omp-conductor` never installs, starts, imports, or depends on the indexer for
+dispatch. With `graphProject` unset, nothing about dispatch, caps, escalation, or
+status changes. A fresh host needs both of these before an index is worth
+anything, and `setup graph` reports them as step 0:
+
+1. **`codebase-memory-mcp` on PATH** — a separate project,
+   [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp).
+2. **Mounted as an MCP server** in `~/.omp/agent/mcp.json`, on the account the
+   daemon runs as. Miss this and the failure is silent: every index builds
+   correctly, no worker session can read any of them, so workers fall back to
+   grepping and the feature looks like a no-op. `setup graph` prints the entry.
+
+Say yes and the wizard asks for one root, then derives one clone per routed repo
+underneath it (default `~/.cache/conductor-graph/<org>/<repo>`) and writes it to
+each repo's [`graphProject`](#configuration). The only automatic interaction is
+a bounded, read-only health query; this package never clones, fetches, builds an
+index, or changes systemd. Dispatch, caps and escalation do not depend on graph
+health. On a fleet configured before this key existed, `omp-conductor setup` and
+the `code graph` area add it in two prompts — see
+[Changing one setting](#changing-one-setting).
+
+### Why the clone, and not your checkout or the worktree
+
+This is the part that decides whether the feature helps or hurts, so it is worth
+being blunt about all three candidates.
+
+| Directory | Why not |
+| --- | --- |
+| **The worker's worktree** | An index is keyed by the realpath of the directory it was built from, and has no git-worktree awareness. A run's `worktrees/<issue>` path is therefore *always* an empty project — a worker that queried its own cwd would get silence, conclude there is no graph, and spend the run grepping. This is why `graphProject` is an absolute path in the config and not something derived at run time. |
+| **Your own checkout** | Refreshing an index means resetting the clone to its default branch. In a directory you work in, that either destroys uncommitted work or — if it is made safe instead — indexes whatever feature branch you left checked out, so the fleet orients against your WIP. |
+| **A conductor mirror** | The daemon's mirrors are bare. There is no working tree to index. |
+
+So `graphProject` names a fourth thing: a clone that exists only to be indexed,
+that nothing human ever edits, and that is therefore safe to `git reset --hard`
+every night. The worker brief names that path, tells the session to match it
+against `list_projects`' `root_path` and query by the `name` beside it, and says
+plainly that the graph is a snapshot which does **not** contain the worker's own
+edits — orient with it, then read the real file before changing it.
+
+### Creating and refreshing them
+
+```bash
+omp-conductor setup graph --print     # print the plan: clones, index commands, units
+omp-conductor setup graph             # run it: clone, install, enable, seed, verify
+```
+
+`setup graph --print` prints a `git clone` for every clone that does not exist yet, the
+one-shot index command per repo, and a `cbm-reindex.service` + `cbm-reindex.timer`
+pair built from the project's own repos and branches. `--write` stages all three
+in the state directory and prints the two `sudo` lines that install and enable
+them; it never runs `systemctl`.
+
+**Run it as the account the fleet runs as, never under `sudo`** — it refuses if
+you try. Everything it derives resolves per-account: the config it loads, the
+state directory it stages into, and the `HOME`/`User=` it bakes into the unit.
+Under root you get a timer that goes green while writing indexes into
+`/root/.cache`, where no worker session looks — silent, and indistinguishable
+from the feature simply not helping. Only installing the units needs root, which
+is why that is two separate printed commands.
+
+Two properties of the generated unit are deliberate:
+
+- **It is a timer, not the server's own watcher.** That watcher lives inside a
+  connected MCP session and dies with it, so an ephemeral worker session keeps
+  nothing fresh. The refresh has to come from outside the fleet.
+- **It fails loudly.** The refresh is `set -euo pipefail`, then per repo
+  `git fetch --prune origin` and `git reset --hard origin/<its own defaultBranch>`
+  before indexing. Nothing is `|| true`-ed, so a fetch that has been broken for a
+  week turns the unit red instead of quietly re-indexing a stale tree and exiting
+  `0` — a green timer serving a month-old graph is worse than no graph at all.
+
+The unit spells out `HOME` and an explicit `PATH`, because systemd supplies
+neither usefully: the indexer resolves its store from `HOME`, systemd's default
+`PATH` has no `~/.local/bin`, and the indexer shells out to `git`. Both are the
+user that ran `setup graph`; the unit sets no `User=`, so check them if that is
+not the account the timer runs as.
+
+### Seeing whether the graph is usable
+
+When at least one routed repo has `graphProject`, `omp-conductor status` adds a
+`code graph` block. It proves the indexer is on `PATH`, the worker MCP config
+mounts it, every configured clone exists and exactly matches an indexed
+`root_path`, the refresh timer is enabled and active, and the last service run
+succeeded within 45 minutes. A running daemon refreshes this evidence every
+minute and publishes the cached result through `/healthz`; status probes the host
+directly when that cache is unavailable. Every command is read-only, runs with a
+one-second timeout, and graph degradation never changes `/healthz.ok` or blocks
+dispatch. Unconfigured projects omit the block entirely.
+
+## Escalation tiers
+
+| Tier | Meaning | Raised by | Delivered to |
+| --- | --- | --- | --- |
+| 1 | "Not a human's problem yet" — the run is parked and safe. | Unroutable issue, blocked run, failed or killed run, dispatch error, attempts exhausted. | The orchestrator session, as an injected prompt. Falls back to an issue comment when no orchestrator is running, or when it will not accept the injection. |
+| 2 | "The fleet is stopped until you look." | Daily spend cap reached; the installed package changed under the running daemon. Either way the project is already paused. | Telegram, when `escalation.telegramChatId` is set and a bot token is readable; otherwise it falls back to the issue comment. |
+
+**The orchestrator** is one persistent, file-backed session per daemon run, resumed
+across restarts so it remembers what it has already handled. Its `cwd` is the state
+directory, deliberately not a checkout. Delivery resolves when the harness *accepts*
+the prompt, not when the model answers it, so a tick never parks behind a model; an
+injection arriving mid-thought queues as a follow-up instead of interrupting the
+turn in flight. Its standing orders are explicit: re-brief the worker, file or
+comment on issues, or promote to tier 2, and never edit product code or push a
+branch. Merging is the one line worded from config — see [`authority`](#configuration).
+If it fails to start, the daemon logs a warning and runs on, with tier-1
+escalations degraded to issue comments.
+
+**Or no orchestrator at all.** Set `escalation.orchestrator` to `"external"` when
+you already run your own supervising session — a visible TUI session in a pane,
+typically. The daemon then starts none of its own and every tier-1 escalation
+posts as an issue comment, which is what that session drains. One brain, and it
+is the one you can watch.
+
+**Answering a tier 1 is only half of it.** A blocked or failed run leaves its state
+label on the issue, and eligibility reads any state label as disqualifying, so an
+answered issue that keeps one is never re-claimed and the answer is inert — nothing
+fails, the issue just stops existing as far as dispatch is concerned.
+[`omp-conductor unblock <issue>`](#cli-reference) is the way back: it clears the
+label through the same tracker the dispatcher writes with, including
+`agent:in-progress` when the newest recorded run is terminal, since a terminal row
+is proof the worker process is gone. The brief tells the
+orchestrator to run that verb rather than edit the label itself, and that is not a
+formality — orphan detection works by comparing `agent:in-progress` labels against
+live runs, and it is only trustworthy while every state label on the tracker was
+written by this package.
+
+Tier 2 borrows the bot token that `omp-telegram` already owns, at
+`~/.omp/agent/telegram/.env` (or `$OMP_TELEGRAM_STATE_DIR/.env`). If you run that
+bot, Tier 2 needs no extra configuration beyond the chat id. If the token is
+absent, Tier 2 degrades to the issue comment instead of failing. The token is
+never logged, and it is redacted out of any error text that could reach a public
+issue comment.
+
+**Escalations are deduplicated.** The dispatcher re-notices the same unroutable
+issue on every poll, so a ledger in the store — keyed by project, issue, tier and
+summary — makes a recurring condition page **once** and suppresses the five-minute
+repeats. The marker is recorded only on successful delivery, so a page that could
+not be delivered is retried on the next tick instead of being written off as sent.
+The spend-cap and integrity-tripwire summaries carry the date, so the same
+condition pages again tomorrow but only once per day.
+
+If `fallbackToIssueComment` is off and no Telegram transport is configured,
+delivery throws instead of dropping silently. The failure is logged and retried,
+because a swallowed escalation looks exactly like a healthy fleet.
+
+## Report delivery (the outbox)
+
+Escalations are the daemon's. **Reports** — the material events and the daily
+digest your [`reporting.scope`](README.md#your-workflow-vs-the-package) asks for — are
+written by the orchestrator, and until v0.3.26 they were also *delivered* by it:
+a report reached you only if the model remembered to call `telegram_send`. On
+2026-08-06 a suite release and two tier-2 escalations were written that way and
+none of the three arrived, and nothing anywhere recorded that fact — an undelivered
+report and a quiet tick look identical.
+
+### Material events survive the session
+
+A deferred digest does not use the session transcript as its source of truth.
+Record each ordinary outcome when it happens:
+
+```bash
+omp-conductor event record \
+  --category merge \
+  --summary "#42 merged" \
+  --evidence "https://github.com/acme/api/pull/42"
+```
+
+`--category` is a short lowercase slug. `--summary` states the outcome, and
+`--evidence` names the issue, PR, release, run, commit, or URL that proves it.
+Use `--occurred-at <ISO timestamp>` when the event happened earlier; otherwise,
+the command uses the current time. The command writes one row to SQLite and
+sends nothing. The row survives later ticks, session compaction, session
+replacement, and daemon restarts.
+
+When a digest is due, its tick prompt lists a bounded, oldest-first set of
+owed material events and deferred escalations. Each line includes its ledger id.
+The prompt gives the exact handoff shape:
+
+```bash
+omp-conductor report \
+  --kind digest \
+  --events EVENT_ID_1,EVENT_ID_2 \
+  --notices NOTICE_ID_1,NOTICE_ID_2 \
+  --text "<the whole digest>"
+```
+
+Remove the id of any row you did not use. Omitted rows stay owed. The report row
+and the named ledger rows are associated in one SQLite transaction. If the
+handoff fails, no row is consumed. If a daily report deduplicates against a
+daily report already queued that day, newly named rows also stay owed. If
+delivery exhausts its retry budget and the report becomes `failed`, its rows
+return to the owed backlog, where a replacement digest can claim them.
+`omp-conductor status` always shows the
+material-event and held-escalation backlog counts, including the age of the
+oldest row when one exists.
+
+This accumulator does not poll GitHub and does not infer outcomes from tracker
+state. The orchestrator still decides what is material and records the evidence.
+The mechanism only makes that decision durable until a non-failed digest owns it.
+
+Authorship still needs judgement the daemon does not have, so it stays with the
+model. Delivery does not, so it moved:
+
+```bash
+omp-conductor report --text "<the whole report>"  # immediate report, when policy permits
+omp-conductor report \
+  --text "<the whole digest>" --kind digest \
+  --events EVENT_IDS --notices NOTICE_IDS          # use row ids from its tick
+```
+
+The command persists the text before anything is sent and prints a durable
+handoff id. An immediate report admitted during quiet hours is stored as a held
+notice and prints that id; the daemon includes it in the next digest or in a
+catch-up report when the configured window opens. Otherwise it writes a
+`reports` row and prints its report id. Both survive the session being
+compacted, interrupted or restarted,
+and the daemon being restarted under it. The daemon delivers over the same bot
+token tier 2 uses, with bounded retries, and `omp-conductor status` lists
+anything it still owes. If availability closes after a material report was
+queued but before its first attempt, the outbox atomically converts that row to
+the same held-notice path instead of leaking the update through quiet hours.
+
+### Answering a person, in the thread they wrote in
+
+A report is an update; an answer is a conversation, and it goes back where the
+question came from. `telegram_send` keeps the active forum topic **only while it
+names no chat** — `thread_id` defaults to the active topic when `chat_id` is
+omitted — so an orchestrator that helpfully supplied `chat_id` (and nothing
+else) answered three topic messages in the main chat instead (#366). The
+orchestrator floor now says to name **neither** target or **both**, and the
+dispatcher refuses `chat_id` without `thread_id` for a project that configured
+`escalation.telegramTopicId`. A flat-chat project is unaffected. When a pinned
+topic id has gone stale — the bridge re-claims pane topics across restarts — the
+live claim for the project's herdr space is used instead, falling back to a
+claim titled for the project, so a restart does not quietly move every page into
+the main chat (#407, #412).
+
+A locally injected tick has no inbound message to inherit a topic from, so a
+bare `telegram_send` there has nothing to preserve. That turn addresses the
+operator from config instead:
+
+```bash
+omp-conductor message --text "<the message>"                             # this project's chat and topic
+omp-conductor message --category tier2 --text "cut 0.16.0 tonight?"      # blocking question: declared category + open decision row
+omp-conductor message --text "QUESTION: do we release?"                  # marker form still maps to decision-needed
+```
+
+A question — a declared `--category` that is not `material`, or text beginning
+`QUESTION:` — is an ask, not a send: before delivery the command records an
+open decision row for the question (parked on silence: "nobody answered" keeps
+the row open and pending, re-surfaced in every tick until answered or the
+seven-day expiry, never an approval) and prints the id to resolve it later
+with `omp-conductor decision resolve <id> --answer "…"`, so the orchestrator
+never has to remember a separate `decision open` (#520).
+
+It is not a bypass of the interrupt policy: the same availability decision an
+autonomous Telegram tool call gets is applied, so a message whose category the
+policy defers is durably held for the digest or the working-hours catch-up and
+the command prints that held-notice id instead of claiming delivery — a
+*blocking* question must therefore declare a category the fleet interrupts on,
+not default to the marker. It is also not a report — it
+leaves no `reports` row, and nothing retries it.
+
+### Delivery is at-least-once, and the docs will not pretend otherwise
+
+The Telegram Bot API accepts no client-supplied idempotency key and offers the
+bot no readable record of what it has already sent. There is nothing to replay a
+request against and nothing to reconcile with, so **exactly-once delivery cannot
+be built on this transport** and this package does not claim it. `delivered` is
+proof that Telegram accepted *an* attempt, never proof that exactly one message
+exists.
+
+What it does instead is make the ambiguity explicit and always resolve it in the
+direction of the duplicate:
+
+| State | Meaning | What you do |
+| --- | --- | --- |
+| `pending` | Nothing is in flight. Never attempted, or the last attempt failed **definitively** — see below. Nobody has this report. | Nothing. It retries on a bounded backoff (30s doubling to a 15-minute floor) and `status` shows the error. |
+| `sending` | A request left this host and its outcome was never learned: the daemon died, or the request was cut off after the bytes went out. Telegram may be holding the message. | Nothing, but expect a possible duplicate. Check the chat if you want to know now. |
+| `delivered` | Telegram answered `ok: true`. The row records the message id from the response **body**, not the HTTP status. | Nothing. |
+| `failed` | The retry budget ran out — six attempts, roughly half an hour. | Fix the transport. This state pages tier 2 in its own right — see below. |
+
+The row is written `sending`, with the id of the attempt about to run, **before**
+the request is made. A crash in that window therefore leaves an explicitly
+ambiguous row rather than a silently lost one. The next daemon start sweeps every
+`sending` row, retries it, and the retried message carries the report id and a
+plain-English line saying it may already be in the chat. A duplicate you can spot
+by its report id is much the cheaper of the two mistakes; a silently dropped
+report is the entire reason this exists.
+
+#### Two kinds of failure, and only one of them is quiet
+
+A failed send is classified where the socket is watched, not by the caller, and
+the two classes are treated differently on purpose:
+
+| Outcome | What happened | Row | Retry says |
+| --- | --- | --- | --- |
+| **Definitive** — nobody has it | Telegram answered and refused it (`{"ok":false}` under any status, or a non-2xx status), or the connection never opened at all (refused, DNS failure) so the request provably never left. | back to `pending`, backoff, attempt counted | nothing special — it *is* a first attempt |
+| **Outcome unknown** — Telegram might have it | The request was cut off after it left: timeout, abort, socket reset, `EPIPE`. Or the POST came back `200` and the **response body could not be read** — Telegram had already decided and the answer was lost coming back. | stays `sending`, flagged as a possible repeat | `POSSIBLE REPEAT`, with the report id to compare against |
+
+Anything that cannot be classified confidently is treated as **outcome unknown**.
+That default is deliberate and is the safe direction: the worst case is a
+duplicate you were warned about, against a delivered report re-posted as though
+it were new, with nothing anywhere saying it might be a second copy.
+
+The half of "never double-post" that *is* achievable is enforced: a report cannot
+be **concurrently** in flight twice. Claiming a report is a conditional update,
+so only one attempt can move a `pending` row, and every terminal transition names
+the attempt it is settling — a request that answers after its row was reclaimed
+is discarded rather than allowed to overwrite a newer attempt's outcome. That is
+what stops a retry storm.
+
+### A report nobody can deliver is itself news
+
+A report that exhausts its retries is marked `failed` **and escalates as tier 2**.
+This rides the transport that just failed, which is deliberate and accepted: the
+common failure is a wrong chat id or a bot kicked from the chat, not a global
+Telegram outage, and in both of those the page reaches an operator who is
+otherwise being told nothing at all. If the whole channel is down the page
+degrades to a line in `daemon.log` and the `reports` block in `status`, which is
+then the only surface — a report has no tracker issue, so there is no issue
+comment to fall back to. The page goes through the ordinary escalation ledger and
+carries the report id, so one undeliverable report pages exactly once.
+
+### Daily digests are deduplicated from the ledger
+
+With `digest.cadence: "daily"`, `--kind digest` is accepted at most once per
+**local** day, per project. The second hand-over on the same day is refused and
+told which report already holds the slot, including when that report has already
+been delivered. This is decided from the `reports` table, not from the model's
+memory of the last tick — a restarted or compacted session cannot send a second
+daily digest by forgetting the first. A `per-tick` digest carries no daily key,
+so later ticks can hand off newly accumulated rows. Material reports carry no
+dedupe key either: two events in a day are two events.
+
+### What `status` shows
+
+```text
+reports   1 pending · 1 sending · 0 failed (delivery is at-least-once — a retry may duplicate)
+  9f2c1ab0d3e4  pending    material  12m old  attempt 2/6, retry in 1m  (telegram sendMessage rejected: {"ok":false,…)
+  4b7c1ad9e001  SENDING    digest    3m old   attempt 1, outcome unknown — the process that sent it never said; a daemon start retries it and the message will say it may be a repeat
+```
+
+`pending` and `sending` are printed differently because they ask different things
+of you, and every row carries its age — "1 report pending since 08:15Z" is the
+signal that was missing when the reports went nowhere. Delivered reports leave
+the block: it is a list of what you are still owed, not a log.
+
+Delivery keeps running while the fleet is **paused**. Pause stops claiming, not
+your right to hear about work that already happened. It runs on its own
+thirty-second timer rather than the five-minute dispatch tick, so a report does
+not sit in the outbox for the length of a poll interval.
+
+The tier-2 escalation ledger (`notifications`) is untouched by all of this. It is
+a bare dedupe key by design — its primary key *is* the key — which is exactly why
+reports needed a separate table rather than an extension of that one.
+
+## The decision ledger (#136)
+
+The outbox above fixed reports the orchestrator sends. This fixes the ones it is
+**waiting on**. A question put to you — an amendment, a tier-2 decision, "do I
+ship this tonight?" — lived in exactly one place: the model's context. A
+compaction, a restart, or a tick that ran long lost the question *and* the fact
+that one was owed, after which the session either asked again (you answer twice)
+or dropped it silently (the decision never lands, and nothing anywhere says one
+is outstanding).
+
+So questions are written down, and every tick's prompt carries what is still
+open — read from the store, never from what the session remembers asking:
+
+```bash
+omp-conductor decision open --question "ship 0.4.3 tonight?" \
+  --blocks "the release" --resolves-when issue-closed:132
+omp-conductor decision list
+omp-conductor decision resolve <id> --answer "yes, after #132 lands"
+omp-conductor decision withdraw <id> --reason "the release slipped a week"
+```
+
+**`--resolves-when` is the part that makes a parked question wake up.** Six
+conditions, each one something this package can check without asking you:
+
+| Condition | Met when |
+| --- | --- |
+| `pr-merged:<https url>` | `gh` reports that pull request merged. |
+| `pr-checks-green:<https url>` | Every check on that pull request has a green verdict (a non-empty list, all `success`/`neutral`); a failing or still-pending check is not met. |
+| `pr-mergeable:<https url>` | The pull request is mergeable (`clean`, not `unknown` or conflicting). |
+| `issue-closed:<number>` | That issue is closed on the tracker. |
+| `npm-version:<pkg>@<version>` | `npm view <pkg>@<version> version` succeeds — the version is published. |
+| `rate-limit-reset:github` | GraphQL quota on `github` has any remaining capacity again. |
+
+The daemon evaluates them beside each tick, fire-and-forget: a hanging registry
+costs one unevaluated condition, never the tick. A row that transitions
+false→true also writes the same `.conductor-tick-requested` poke recover uses,
+so the orchestrator heartbeat fires promptly (mid-interval poll, still gated by
+arm/channel/pending single-flight) instead of waiting a full interval. The poke
+reason and the digest flag `[CONDITION MET — act on this now]` both surface the
+wake so the session acts when the answer becomes actionable. Repeated sweeps
+while the condition stays true do nothing further — the store marks the
+transition once. After a green-but-behind PR is updated through
+`conductor_pr_update_branch`, open a fresh `pr-checks-green` watch on the new
+head so the next green transition can wake merge review the same way; nothing
+here merges on its own.
+
+Anything else exits `2` and lists the six forms. An unparseable condition on an
+existing row is *listed and never treated as met*: a grammar a future release
+adds must not make an old row unloadable, and a question must never be hidden by
+a condition nobody can check.
+
+**Expiry is enforced, not remembered.** An unanswered question closes itself
+after seven days — the deadline the floor's parked-amendment protocol already
+promised — so the digest stays a list of live questions instead of a graveyard.
+Answering or withdrawing is explicit, and a second resolution of the same id is
+refused rather than overwriting the first answer.
+
+`omp-conductor status` carries one row, `decisions`, reported whether or not
+anything is open: `decisions 2 open (oldest 26h)`, or `decisions none open`. A
+row that appeared only when something was outstanding would leave "it forgot to
+record the question" and "there genuinely is none" looking identical, which is
+the ambiguity this table exists to remove.
+
+## Failure classes and recovery by class (#132)
+
+Every run that did not reach a merged PR used to end at a human. The
+orchestrator re-derived the same triage on each tick — read the row, read the
+PR's checks, decide whether to requeue, re-run, settle or escalate — and then
+threw the conclusion away. Measured on this fleet's own history: **half the
+spend produced no merged PR**, and a large share of it was not implementation
+failure at all but daemon restarts, cancelled runners and a base branch moving
+under a green PR.
+
+So the daemon classifies each terminal non-success before the next dispatch,
+persists the class on the row, and performs the one recovery that class names.
+
+| Class | Signals | Recovery | Budget |
+| --- | --- | --- | --- |
+| `env-start-failure` | turn 0 plus an explicit harness start error (`No model selected`, a rejected key) | escalate — the session never read the issue | none |
+| `settlement-stuck` | a row carrying a PR that has since merged | settle: release the label, mark the row merged | none |
+| `returned-for-revision` | a `pushed-green` or `pushed-pending` PR was closed without merging | none — preserve the review decision for a human re-queue | continuation |
+| `merge-conflict` | `pushed-green`, PR open, GitHub reports conflicting | requeue for a rebase continuation | continuation |
+| `question` | the worker stopped to ask something (`blocked`) | escalate, carrying the worker's own report as evidence | none |
+| `orphan-dirty` | orphaned with a failed salvage and no operator ack | hold — recorded only; the tree is the only copy | none |
+| `orphan-clean` | orphaned with nothing uncommitted | requeue | continuation |
+| `turn-cap-progress` | at the turn ceiling **with** a PR, head or salvage commit | continue from the branch | continuation |
+| `turn-cap-spinning` | at the ceiling with no PR and no commits | escalate with the last tool calls the transcript recorded — and the completion path deliberately does **not** requeue it | none |
+| `admin-kill` | killed *below* its own ceiling — a restart or a drain | requeue | none |
+| `ci-infra` | PR open, every unresolved check cancelled / timed out / stale | re-run the failed jobs | none |
+| `ci-deterministic` | PR open, a check genuinely reports `FAILURE` | escalate with the failing check names and links | failed attempt |
+| `dispatch-infra` | the conductor's own Git path failed before the worker's first turn | requeue, bounded by per-class strikes | none |
+| `provider-credit` | the provider refused the run for credit (HTTP 402, or its own out-of-credit text read off the transcript) | pause the fleet and require `omp-conductor resume` once the provider has credit | none |
+| `provider-transient` | the provider aborted a request stream before the run produced a verdict | requeue, bounded by per-class strikes | none |
+| `unknown` | anything unrecognised | escalate | as recorded |
+
+**Unknown escalates; it never silently retries.** A shape this table does not
+recognise is a gap in the table, and a quiet requeue would spend a budget on a
+cause nobody has named — the behaviour this exists to end.
+
+### The budgets follow the cause
+
+`failuresFor` (implementation attempts) excludes `ci-infra`, `settlement-stuck`,
+`env-start-failure`, `dispatch-infra`, `provider-credit`, `provider-transient`
+and `returned-for-revision`. `continuationsFor` excludes `admin-kill`,
+`settlement-stuck`, `env-start-failure`, `dispatch-infra`, `provider-credit`
+and `provider-transient`, but explicitly counts a failed
+`returned-for-revision` row. Environment, dispatch and provider faults charge
+neither budget because the issue did not receive a valid implementation
+attempt. A merge conflict and a returned review both charge a continuation:
+each asks for more work, but neither is a failed implementation attempt.
+
+An **unclassified** row (every row written before 0.4.3) counts exactly as it
+did before classification existed. Upgrading therefore changes no existing
+budget: the columns are additive and nullable, and a pre-0.4.3 `conductor.db`
+opens unchanged.
+
+### Stale labels are reconciled
+
+On 2026-08-09 four issues carried `agent:failed` while every one of them was
+already complete — residue of a turns-cap kill two days earlier that nothing in
+the loop ever revisited. The board counted four phantom failures while the
+genuinely stuck issues were invisible.
+
+Each tick now reconciles the three state labels against the tracker:
+
+- A **closed** issue never keeps an `agent:*` label.
+- An **open** issue carrying `failed` whose sub-issues have *all* closed loses
+  the label and gets one comment naming them, deduplicated through the same
+  notifications ledger escalations use.
+
+Positive evidence only: a tracker that cannot list answers empty, and an empty
+answer removes nothing — the label is the interlock that keeps two workers off
+one issue.
+
+### Where you see it
+
+- `omp-conductor status` grows a `failure classes (unrecovered)` block, counting
+  only rows whose recovery has *not* run. Classes rather than row states,
+  because a row state is not an issue state.
+- The board appends `[<class>]` to a card whose newest run carries one.
+- The tick prompt carries one line — `Auto-recovered since last tick: 3
+  (merge-conflict #365, admin-kill #82, …) — already handled, do not re-triage
+  these.` — so the orchestrator stops writing that paragraph by re-deriving it.
+
+## Configuration
+
+The config lives at `$OMP_CONDUCTOR_HOME/config.json`, or
+`~/.omp/conductor/config.json` when that variable is unset. It is written with mode
+`0600` in a directory created `0700`, because it carries chat ids and clone URLs.
+That same directory holds the SQLite store (`conductor.db`), the `paused` sentinel,
+the `sessions/` worker transcripts, the `orchestrator/` session directory,
+`backups/briefs/` for timestamped brief and policy safety copies, and
+`release-policy-blocks.jsonl`, the append-only audit of mechanically rejected
+release/deploy calls.
+
+Runtime state lives elsewhere, under `$OMP_CONDUCTOR_RUNTIME_DIR` (default
+`~/.omp/run/daemons/omp-conductor`): `daemon.json`, a mode-`0600` pidfile written
+atomically, and `daemon.log`, appended across every boot so the previous failure is
+still there when you go looking. It is kept apart from the config directory because
+it is meaningless after a reboot, and the pidfile's liveness is probed on every
+read — a stale one never blocks a `start`. Both `start` and a bare `daemon` write
+the pidfile, so a daemon run in the foreground under systemd is as visible to
+`status` as a backgrounded one; `daemon --once` writes nothing, because that drill
+is exactly what the orphan-reconciliation guard reads the pidfile to protect.
+
+The file is validated on every read. A malformed config produces one readable error
+listing every fault, and the daemon refuses to start rather than running with half
+a project.
+
+The same vocabulary the loader enforces ships as a JSON Schema at
+`schema/config.schema.json` in the installed package (draft 2020-12). Anything
+`saveConfig` writes carries a top-level `"$schema"` reference to that installed
+copy (resolved from the package's own location, so it points at a real file),
+which lets an editor that understands JSON Schema validate a hand-edited config
+as you type; a config without the key is just as valid. Regenerate the shipped
+schema from `ConfigSchema` (`src/config-schema.ts`) with:
+
+```sh
+bun run schema
+```
+
+and commit the resulting `schema/config.schema.json`. CI's `bun test` fails if the
+checked-in schema drifts from what the code renders, so you cannot forget the step.
+
+`omp-conductor setup` is the only thing here that writes this file, and on a project
+it already knows it can rewrite one area of it without re-asking the rest — see
+[Changing one setting](#changing-one-setting).
+
+`version` is `2`. A `version: 1` file still loads: caps it names that this build no
+longer enforces are dropped rather than treated as typos, and the next save writes
+it back as `2`. In a `version: 2` file an unrecognised cap key **is** an error,
+because there is nothing left to retire — a mistyped `dailySpendUSD` would
+otherwise read as configured while the real ceiling stayed the default.
+
+A complete, valid config for one project with two target repos:
+
+```json
+{
+  "version": 2,
+  "defaults": {
+    "maxConcurrentWorkers": 2,
+    "dailySpendUsd": 25,
+    "planUsage": { "windowId": "anthropic:7d", "maxUsedFraction": 0.85 },
+    "workerMaxTurns": 120,
+    "workerWallClockMs": 5400000,
+    "maxAttemptsPerIssue": 2,
+    "maxContinuationsPerIssue": 2
+  },
+  "projects": [
+    {
+      "name": "demo",
+      "tracker": { "kind": "github", "repo": "acme/planning" },
+      "queueLabel": "ready-for-agent",
+      "stateLabels": {
+        "inProgress": "agent:in-progress",
+        "blocked": "agent:blocked",
+        "failed": "agent:failed"
+      },
+      "routing": {
+        "labelPrefix": "repo:",
+        "repos": {
+          "api": {
+            "name": "api",
+            "cloneUrl": "git@github.com:acme/api.git",
+            "defaultBranch": "main",
+            "gates": [
+              { "cmd": "bun run lint", "cwd": "." },
+              { "cmd": "bun test", "cwd": "." }
+            ],
+            "graphProject": "~/.cache/conductor-graph/acme/api",
+            "migrations": { "dir": "backend/alembic/versions" },
+            "release": { "versionFile": "omp/package.json" }
+          },
+          "worker": {
+            "name": "worker",
+            "cloneUrl": "git@github.com:acme/worker.git",
+            "defaultBranch": "main",
+            "gates": [
+              { "cmd": "ruff check .", "cwd": "." },
+              { "cmd": "pytest -q", "cwd": "backend" }
+            ]
+          }
+        }
+      },
+      "caps": {
+        "maxConcurrentWorkers": 1,
+        "dailySpendUsd": 15
+      },
+      "workerModel": "smol",
+      "escalation": {
+        "telegramChatId": "123456789",
+        "telegramTopicId": 8713,
+        "fallbackToIssueComment": true,
+        "orchestrator": "embedded"
+      },
+      "authority": {
+        "merge": "human",
+        "release": "human"
+      },
+      "releasePolicy": {
+        "version-bump-pr": "human",
+        "git-tag": "human",
+        "git-push-tags": "human",
+        "package-publish": "human",
+        "github-release": "human",
+        "deploy": "human"
+      },
+      "policy": {
+        "merge": {
+          "requiredChecks": ["build", "lint"],
+          "baseFreshness": "up-to-date",
+          "drafts": "block",
+          "whenBehindBase": "update-branch"
+        },
+        "release": {
+          "requires": ["runs-settled", "no-open-prs"],
+          "requiredChecks": ["release"],
+          "artefacts": ["@acme/sdk"],
+          "environments": ["staging"]
+        }
+      },
+      "recoveryMerges": [
+        {
+          "prUrl": "https://github.com/acme/api/pull/381",
+          "headSha": "9a783d8f17071d63f2d5d764d43a29837c365920",
+          "reason": "operator-instructed"
+        }
+      ],
+      "reporting": {
+        "scope": "material"
+      },
+      "workspaceRoot": "~/.omp/conductor/worktrees",
+      "mirrorRoot": "~/.omp/conductor/mirrors"
+    }
+  ]
+}
+```
+
+Field notes:
+
+| Field | Notes |
+| --- | --- |
+| `version` | Must be `2`. A `version: 1` file still loads, drops the caps this build no longer enforces, and is rewritten as `2` on the next save. Present from day one so a format change can be migrated instead of silently misread. |
+| `defaults` | Every `Caps` field. Anything omitted falls back to the built-in default. |
+| `tracker.repo` | `owner/repo`. `tracker.kind` may be omitted; `"github"` is the only accepted value. |
+| `queueLabel` | The one label meaning "a human has signed this off as agent-ready". Matched exactly, case-sensitively. |
+| `release.versionFile` | Optional, per repo: a repo-relative JSON file with a top-level string `version`, such as `omp/package.json`. Declares that tags must match the version already landed on the live default branch. A delegated `git-tag` for such a repo requires delegated `version-bump-pr` too; otherwise config loading fails with the missing preparation path instead of granting an impossible release. Absolute paths and `..` are refused. |
+| `groomBelow` | Optional; default `4`. Routable candidates below this count make the orchestrator's tick prompt say the queue is running low and to groom it (Duty 2). An integer ≥ 1; anything else degrades to the default. |
+| `stateLabels` | Optional; defaults to `agent:in-progress`, `agent:blocked`, `agent:failed`. |
+| `routing.labelPrefix` | Optional; defaults to `repo:`. |
+| `routing.repos` | At least one entry, or nothing can be routed. `name` defaults to the map key, `defaultBranch` to `main`. |
+| `gates` | The exact cheap commands CI also runs, each with the `cwd` it runs from (`cwd` defaults to `.`). Running the real gate locally is what makes an unattended push safe — a subset lets an error outside the source dir reach the runners. |
+| `graphProject` | Optional, per repo. Absolute path of the **index-only clone** whose code graph this repo's workers query — conductor's own disposable clone, pinned to the repo's default branch, never a checkout you work in and never a worker's worktree. Written by the wizard; `~` is expanded, and a relative path is an error rather than something resolved against whichever cwd happened to read the file. Absent means this repo has no graph and its briefs say nothing about one. See [Code-graph discovery](#code-graph-discovery). |
+| `migrations` | Optional, per repo: `{ "dir": "backend/alembic/versions" }`. Names the repo-relative directory of an Alembic-style ordered migration chain (`revision` / `down_revision` in `*.py`). When set, `conductor_pr_merge` **refuses** a merge that would corrupt the chain at the base tip: reusing a revision id another file already declares, deleting a published migration, or a merge that would leave the combined graph with more than one head (so a stale parent is refused, and a fork-repair merge migration that unifies the heads passes). Absent means the repo opts out of the chain check entirely. Repo-relative only: a leading `/` or `..` is an error. |
+| `caps` | Per-project overrides; omit it or pin only the fields you want to change. |
+| `escalation.fallbackToIssueComment` | Defaults to `true`. Absent means "yes, still tell me". |
+| `escalation.telegramTopicId` | Optional forum topic for everything conductor sends: tier-2 pages, reports, digests, arm challenges, `omp-conductor message`. Setup offers the topics omp-telegram has claimed, naming each one's herdr space. The bridge re-claims a pane's topic across restarts — including the restarts `upgrade` and `restart` perform — so a pinned id that is no longer claimed is replaced at send time by the live claim whose **herdr space** is this project, falling back to one titled for the project, logged without ids (#407, #412). The space is read first because the bridge titles a topic `ownAgentName ?? basename(cwd)`, and a multi-project host whose panes sit under one state directory gives every claim the same title. An identity two claims share is treated as no match at all rather than a guess. A pin that is still claimed always wins, so a deliberately separate topic is never hijacked. Absent keeps flat-chat behaviour. |
+| `escalation.orchestrator` | Optional; `"embedded"` (default) or `"external"`. `external` means an orchestrator session already runs elsewhere: the daemon starts none, and tier-1 escalations post as issue comments for that session to drain. Any other value is an error. |
+| `authority` | Optional; `{ "merge": …, "release": … }`, each `"human"` (default) or `"orchestrator"`. It grants nothing to the daemon — it words the orchestrator's standing orders and the Releases paragraph of the rendered brief, so the config and the prompt cannot disagree about who holds the merge button. Unknown keys and any other value are errors, never folded to the default. |
+| `releasePolicy` | Optional; a per-shape map whose values are `"human"` (default) or `"orchestrator"`. Shapes are `version-bump-pr`, `git-tag`, `git-push-tags`, `package-publish`, `github-release`, and `deploy`. The legacy `"none"` denies every shape; legacy `"operator-brief"` grants the artifact-producing shapes, including reviewed version preparation, but keeps deploy human-owned. The in-session tripwire blocks recognised raw release/deploy calls before execution. Every rejection is written to `release-policy-blocks.jsonl`; the heartbeat carries that day's count into the daily digest. This is the mechanical gate; `authority.release` still says who owns the decision. |
+| `recoveryMerges` | Optional, hand-edited recovery authority for a PR that has no conductor run record. Each entry is an exact `{ prUrl, headSha, reason: "operator-instructed" }` tuple. When all three values match, `conductor_pr_merge` may merge that one PR even while the fleet is held and even when standing merge authority is `"human"`. It still requires a routed project repo, an open PR at that exact live head, green checks, the migration-chain guard, and the single-flight lock—the same safety path as an ordinary merge. Duplicate PR URLs and malformed values make config loading fail closed. Setup preserves entries but never creates them. Remove an entry after the recovery is complete. |
+| `reporting` | Optional; a **legacy scope preset** (`reporting.scope` — `"material"` default, `"decisions"`, `"escalations"`) or the **explicit form** `{ "interruptOn": [...], "digest": { ... }, "availability": { ... } }`. The preset writes which categories may page the operator (`interruptOn`) and when the rollup happens (`digest.cadence`); the explicit form sets both directly and may add a weekly operator-availability window. The two forms are mutually exclusive in one config. See [Reporting policy](#reporting-policy-reporting). |
+| `orchestratorReadPaths` | **Retired in 0.4.3.** Still accepted in a config and ignored, so a fleet carrying it upgrades without an edit. It widened the orchestrator's file-tool allowlist; there is no allowlist any more — the orchestrator is [unconfined by design](#the-orchestrator-is-unconfined-deliberately). |
+| `policy` | Optional; the gating conditions a merge or a release must satisfy, in two sections — `policy.merge` and `policy.release`. Any member may be omitted and the loader fills it from the strict default; an unknown key in either section, or a value outside its vocabulary, is an error naming the field, never a silent downgrade. See [Merge and release preconditions](#merge-and-release-preconditions-policy). |
+| `workspaceRoot` / `mirrorRoot` | Optional; default to `worktrees/` and `mirrors/` under the state directory. `~` is expanded. |
+
+Prefer an SSH `cloneUrl`, or an https URL backed by a credential helper. A clone URL
+with credentials embedded is persisted into the mirror's git config, exactly as it
+would be for a hand-run clone.
+
+### Reporting policy (`reporting`)
+
+What may interrupt the operator's phone, and when the daily rollup happens. Two
+spellings, mutually exclusive in one config (the loader rejects a `scope` next to
+`interruptOn`/`digest`):
+
+- **Preset** — `reporting.scope`, the three legacy values, mapped verbatim:
+  - `material` (default) → `interruptOn: [tier2, decision-needed, fleet-stopped, confirmed-failure, material]`, digest `per-tick`.
+  - `decisions` → `interruptOn: [tier2, decision-needed, fleet-stopped]`, digest `per-tick`.
+  - `escalations` → `interruptOn: [tier2, fleet-stopped]`, digest `daily` (model-timed).
+- **Explicit** — `reporting: { "interruptOn": ["tier2", "fleet-stopped", ...], "digest": { "cadence": "none" | "per-tick" | "daily" } }`.
+  `interruptOn` must be a non-empty array of known categories (`tier2`, `decision-needed`, `fleet-stopped`, `confirmed-failure`, `material`), each an escalation's tier-2 category. `daily` may add `at` (`HH:MM`, 24h) and `timezone` (a known IANA zone, defaulting to the host zone) — both only valid with `daily`.
+
+The explicit form may add a weekly local-time window:
+
+```json
+{
+  "reporting": {
+    "interruptOn": ["tier2", "fleet-stopped"],
+    "digest": { "cadence": "daily", "at": "17:00", "timezone": "Europe/London" },
+    "availability": {
+      "timezone": "Europe/London",
+      "days": ["mon", "tue", "wed", "thu", "fri"],
+      "start": "09:00",
+      "end": "17:00",
+      "bypass": ["fleet-stopped"]
+    }
+  }
+}
+```
+
+`timezone` must be a known IANA zone. For a daily digest, its timezone defaults
+to this value and must match it when both are set.
+
+`days` is a non-empty set of `mon` through `sun`; `start` is inclusive and
+`end` is exclusive. A start later than the end defines an overnight window on
+the day it opens. `bypass` is an explicit list of known interrupt categories
+that may still page outside the window; it may be empty. For ordinary notices,
+a bypass has no effect on a category omitted from `interruptOn`. Urgent recovery
+notices may bypass category batching when the digest loop itself is unavailable,
+but they still require the configured availability bypass outside the window.
+
+The setup wizard offers this as **Weekly availability window** and asks for the
+zone, days, start/end, bypass categories, and digest schedule: every tick,
+model-timed daily, disabled, or a fixed daily `HH:MM`. Re-running setup or
+amending reporting preselects and preserves the configured `none`, `per-tick`,
+or `daily` cadence. Choosing **Continuous (24-hour interrupts)** is the explicit
+opt-out and preserves the behavior of every existing config; an absent
+`availability` key also means continuous operation.
+
+Outside the window, an otherwise interruptible escalation is stored durably
+instead of sent. A daily digest may consume it first. Otherwise the daemon
+atomically queues one working-hours catch-up report when the window opens,
+including after downtime; associating the held rows before delivery prevents a
+later tick from authoring a duplicate. Each heartbeat prompt names the
+mechanically computed current mode and next transition. `status` shows the same
+state plus the next digest opportunity (`due now`, every tick, disabled, or its
+next operator-local timestamp). Config, escalation routing, and report transport
+are re-read at tick or send time, so changing the window or Telegram target
+does not require a daemon restart.
+
+Attachment-bearing autonomous Telegram sends cannot be replayed by the text
+digest, so they are blocked with an explicit “nothing sent or held” error rather
+than silently dropping their files.
+
+A tier-2 escalation whose category is **not** in `interruptOn` is not dropped: it
+is held (`held_notices`) and the next accepted digest is its delivery authority.
+A `daily` digest is at-most-once per local day (`digest:<YYYY-MM-DD>` in the
+configured zone), which remains the delivery authority across restarts.
+`per-tick` digests are not daily-deduplicated, so a later tick can claim newly
+accumulated rows. A scheduled `daily` digest is only sent on a day it has not
+already run, once the local clock has passed `at`; a restart after `at` still
+sends today's (one catch-up), and a fully missed day is skipped, never sent late.
+
+**What the scope does:** the [orchestrator heartbeat](#orchestrator-tick) appends
+the current constraint to every tick it sends, so the reporting contract arrives
+with the prompt instead of only in a brief the session read hours ago. Explicit
+policies name their actual interrupt categories and digest cadence. The policy is
+re-read from `~/.omp/conductor/config.json` on **every** tick, and escalation,
+direct Telegram, and durable report paths apply it mechanically. Turning the
+volume up or down — `omp-conductor setup` again, or an edit to the file — therefore
+binds the next tick without restarting the session.
+
+No config, an unreadable or invalid config, or several unnamed projects fall
+back to the legacy `material` scope for the heartbeat and log the reason once.
+An invalid live availability policy blocks autonomous Telegram fail-closed; it
+does not guess that the operator is awake.
+
+Changing the key later does not rewrite an `ORCHESTRATOR.md` you already have.
+The generated `POLICY.md` describes every scope without pinning the current
+choice; the tick constraint remains derived from live config. Keep any
+operator-owned reporting additions in `ORCHESTRATOR.md` consistent with it.
+
+### Merge and release preconditions (`policy`)
+
+These used to be sentences in your `POLICY.md`: when a PR may be merged, what
+must be green, what a release requires. Prose cannot be checked, so every tick
+re-decided them by reading and interpreting them again. They are configuration
+now, `POLICY.md` keeps only judgement, and the rendered brief *describes* the
+policy instead of restating it — no threshold lives in two places.
+
+`policy.merge`:
+
+| Field | Values | Default | Means |
+| --- | --- | --- | --- |
+| `requiredChecks` | any check names | `[]` | Checks that must have concluded successfully. **Empty is the strict answer** — it means every check the PR reports, not "no checks". |
+| `baseFreshness` | `up-to-date`, `any` | `up-to-date` | Whether the head must be level with the base branch. `any` accepts a verdict produced against an older base. |
+| `drafts` | `block`, `allow` | `block` | Whether a draft PR can be merged at all. |
+| `whenBehindBase` | `update-branch`, `hold`, `escalate` | `update-branch` | What to do with a green PR that fell behind. `update-branch` runs `gh pr update-branch` and waits for the fresh run. Closing it and an admin bypass are not spellable. |
+
+`policy.release`:
+
+| Field | Values | Default | Means |
+| --- | --- | --- | --- |
+| `requires` | `runs-settled`, `no-open-prs`, `queue-drained`, `base-branch-green`, `epic-children-closed` | `["runs-settled"]` | What must already have landed. `runs-settled` reads each active run's PR fact at release time: a pushed run whose PR has merged counts as settled even when the settle sweep has not yet written the terminal row — so a hold-drained release does not wait an extra tick the operator reached the gate by holding. Live workers and unmerged/unknown PRs still refuse, and the message names which is which. `base-branch-green` requires the current live head's push-triggered workflow verdict for that routed repository to be green; pending, unknown, red, or no observation refuses release. Order and duplicates do not matter; the loader canonicalises. |
+| `requiredChecks` | any check names | `[]` | Checks that must be green on the branch being released. Empty means every check it reports. |
+| `artefacts` | any names | `[]` | The packages or images this project releases. **Empty denies**: nothing has been authorised to ship. |
+| `environments` | any names | `[]` | Deploy targets. **Empty denies** every environment. |
+
+A project with no `policy` block loads as the whole default above, which is the
+strictest reading of the prose it replaced. `omp-conductor setup` asks for all of
+it under the **merge & release preconditions** area, so changing one condition
+costs eight prompts rather than a hand-edit — see
+[Changing one setting](#changing-one-setting).
+
+This key grants nothing. Who *may* merge or release is
+[`authority`](#configuration), and which release tool calls are mechanically
+permitted is [`releasePolicy`](#configuration). `policy` says what must be true
+before the act, whoever is doing it.
+
+#### Reasons are a closed vocabulary
+
+Where an automated verb takes a `reason`, the argument is one value out of a
+fixed set, not free text — a reason a rule matches on is a reason that decides,
+and a decision made out of a model's own wording is one no two runs spell the
+same way. A reason outside its set is refused, and the refusal names every
+accepted value.
+
+| Verb | Accepted reasons |
+| --- | --- |
+| merge | `preconditions-met`, `behind-base-refreshed`, `operator-instructed`, `release-blocking` |
+| release | `batch-complete`, `epic-closed`, `hotfix`, `operator-instructed` |
+| label change | `promoted-to-queue`, `re-briefed`, `needs-human`, `duplicate`, `superseded`, `out-of-scope` |
+
+Free-form rationale still has a home: it rides alongside as a separate
+`rationale` field, is written into the audit trail verbatim, and is never
+parsed or matched by anything.
+
+## Orchestrator tick
+
+The escalation path above assumes an orchestrator session that is actually
+running its loop. A 24/7 omp session with a standing brief and nobody typing into
+it never gets prompted, so it never runs anything. Installing
+`omp plugin install omp-conductor` also installs a heartbeat that prompts it.
+
+The heartbeat is **inert unless the session cwd contains
+`.conductor-tick.json`**, so an ordinary session has no timer. `omp-conductor setup`
+writes this file for external orchestration. A manual configuration has this form:
+
+```json
+{
+  "intervalSeconds": 900,
+  "project": "fleet",
+  "armedFile": "/home/fleet/.omp/conductor/armed-fleet",
+  "accessFile": "/home/fleet/.omp/agent/telegram/access.json",
+  "message": "Run your standing loop from ORCHESTRATOR.md now."
+}
+```
+
+| Key | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `intervalSeconds` | yes | — | Whole seconds between ticks, minimum `60`. A tick costs a full turn of a frontier model, so a sub-minute period is refused rather than obeyed. |
+| `project` | no | the only configured project | Which conductor project this fleet session ticks for. `setup host` stamps it, one tick config per fleet cwd, and it is what lets a host with several configured projects resolve *this* fleet's brief, reporting policy, digest ledger and release grants. Omitting it is the pre-multi-project spelling: correct on a single-project host, and on a host with two or more it degrades every tick to the default reporting scope with no release grants — `status` and the tick log then name the one fix (`re-run omp-conductor setup host`). A name no configured project has degrades the same way. |
+| `budgetSeconds` | no | `600` | Seconds a turn may run before the tick guard refuses its remaining tool calls (#189), and before a queued operator message preempts them. An integer ≥ 60; anything else degrades to the default. |
+| `askTimeoutSeconds` | no | `300` | Seconds one `conductor_ask` call waits for the operator before its declared `on-timeout` outcome fires (#438). An integer 60–3600; anything else degrades to the default. The resolved ceiling is always capped at the turn budget, so an ask can never outlive the turn it runs in. |
+| `armedFile` | no | none — the gate passes | Path to the arm marker. A tick does nothing while the file is missing. **Re-read from disk on every tick**, so a `setup host` restamp onto `armed-<project>` binds on the next heartbeat instead of leaving a live pane watching the path it captured at session start. Relative paths resolve against the session cwd, so `state/armed` means `<cwd>/state/armed`. `setup host` writes `<state dir>/armed-<project>`, one marker per project, so `arm --project A` cannot arm B. A value it did not generate is left alone as your own choice. |
+| `accessFile` | no | none — the gate passes | Path to the Telegram bridge's `access.json`. Every tick re-reads it and requires `enabled: true` with exactly one entry in `allowFrom`. Relative paths resolve against the session cwd. **Configure this on any fleet deploy** — see below. |
+| `message` | no | `Tick <ISO timestamp>: re-read <workspaceRoot>/ORCHESTRATOR.md from disk, then run your standing loop from it.`, then the reporting-policy line, delivery rule, and mechanical availability state | When set, this text replaces the ordinary reporting-policy line and delivery rule, but the runtime-owned availability state is still appended: a custom prompt cannot infer whether the operator may be interrupted. Re-read from disk on **every** tick, so rewording it binds the next heartbeat instead of waiting for a session restart; a re-read that fails — caught mid-edit, removed, or invalid — keeps the value read at session start rather than stopping the heartbeat. `intervalSeconds` is *not* re-read: rescheduling a live timer still needs a restart. The default *orders* the session to re-read its brief, naming the path resolved from the project's `workspaceRoot`, because a standing prompt drifts out of a long-lived session's context while the file on disk does not. |
+| `agentName` | no | the project name, else `fleet` | The herdr agent name the orchestrator's pane is registered under. Under herdr this is the whole of the identity check below. `setup host` writes the project name, so two fleets in one herdr session are distinguishable; when no tick config names one, the fallback matches `AGENT_NAME=${AGENT_NAME:-fleet}` in the recovery plugin's `recover.sh`, so both halves key on one name. Rename the agent and set this to match. |
+
+#### Bounded operator asks (#438)
+
+On 2026-08-16 an unanswered `telegram_ask` blocked the orchestrator turn for
+six hours; every duty behind the question stopped with it. `telegram_ask` is
+omp-telegram's tool and it waits as long as the answer takes, so on a locally
+injected tick the extension refuses it and mounts its own bounded surface,
+`conductor_ask`:
+
+- The call carries `question`, `on-timeout` (`auto-proceed` or `park`, required),
+  and optionally `timeoutSeconds`, `blocks`, `recommended`, `options` and
+  `category`.
+- The tool records a decision row first (durable, seven-day expiry), then
+  delivers the question through the same path `omp-conductor message` uses —
+  immediately when the reporting policy permits, durably held otherwise.
+- It waits at most the ceiling: `timeoutSeconds` if the ask names one, else the
+  tick config's `askTimeoutSeconds`, else 300 seconds — always capped at the
+  turn budget, so the ask can never outlive the turn it runs in. An ask issued
+  without a timeout gets the default all the same.
+- On timeout, `auto-proceed` applies the recommended option and resolves the row
+  with `"<option> (auto-applied on ask timeout)"` so the record never reads as a
+  human choice; `park` leaves the row open and pending — re-surfaced in every
+  tick prompt until answered or the seven-day expiry — and the caller takes the
+  blocked work out of the claimable queue. A timeout is "nobody answered yet",
+  never a cancelled/errored ask and never an operator no.
+
+The refusal of the raw tool is mechanical (the tool-call gate), not a prompt
+reminder: a model cannot wait unbounded on a local tick even by omitting the
+timeout argument.
+
+#### Upgrading from one shared arm marker
+
+Before per-project markers every project was given the same `<state dir>/armed`,
+so arming one fleet armed all of them. `setup host` rewrites that value — and
+only that value — to `armed-<project>`. The old bare marker is honoured for one
+more cycle on a **single-project** host, so the upgrade never silently disarms a
+live fleet, and the next `arm` or `disarm` retires it. On a host with **two or
+more** projects it arms nothing: `status` reports `legacy global arm marker —
+re-run setup host, then arm per project`, and every tick stays disarmed until each
+project is armed on its own marker.
+
+The same restamp renames the identity this pane ticks under: an `agentName` of
+`fleet` — the value every project used to be given — becomes the project name.
+**Under herdr that is an operator step, not a no-op.** Ownership is proved against
+the pane's registered herdr agent, so after re-running `setup host` the live fleet
+pane needs the new name.
+
+**Rename the agent herdr already detects — do not `agent start`.** `herdr agent
+start` submits omp *into* the pane's existing shell and requires a pane sitting at
+a shell prompt with no agent on it; the live orchestrator pane is neither, so it
+is refused at best and starts a second omp in that pane at worst. `rename` touches
+no process and keeps the session as it is:
+
+```sh
+herdr --session <session> agent list                      # find the fleet's pane_id
+herdr --session <session> agent rename <pane-id> <project>
+```
+
+If the name cannot be reassigned in place, stop and resume rather than starting a
+second orchestrator — the same shape `recover.sh` uses, so the omp session is
+preserved rather than replaced:
+
+```sh
+herdr --session <session> agent get <pane-id>   # note agent_session.value — the session ref
+# exit omp in that pane (/exit) so the pane is back at a shell prompt, then:
+herdr --session <session> agent start <project> --kind omp --pane <pane-id> -- --resume=<ref>
+```
+
+Until the pane carries the new name it declines to tick and logs which agent it
+actually is versus the one the tick config names, with the `rename` command in the
+line — the heartbeat fails closed and says so rather than letting two fleets both
+answer to `fleet`. Set `agentName` explicitly if you would rather keep the old
+name; a value that is not the shared default is never rewritten.
+
+The marker itself needs no restart: `armedFile` is re-read from disk every tick, so
+the restamped path binds on the next heartbeat. Before 0.15.2 it was read once at
+session start, and a restamp under a live pane left that pane watching a path the
+restamp had just replaced — `status` reported `armed` from the file while the
+heartbeat skipped silently as "not armed", which writes no stall marker.
+
+Recovery is fail-closed across that window. A restamped `agentName` moves the
+recovery plugin's own state files to per-agent paths that do not exist yet, and
+the live pane is still saved under `fleet`, so the snapshot offers no candidate
+for the new name. `herdr-conductor` treats the pre-rename identity and bootstrap
+marker as proof a fleet has already lived on this host whatever it is called now:
+it pages `no fleet identity to recover for agent <project>` instead of
+provisioning a second workspace beside the live orchestrator. Finish the rename
+and the next pass recovers normally.
+
+A default tick sends one message (`customType` `omp-conductor.tick`, attributed
+to the user): the standing-loop prompt, the reporting-policy constraint re-read
+from conductor config on every tick, the delivery rule, and the mechanically
+computed operator-availability state. A configured `message` replaces the first
+three parts but not that clock state. The delivery rule is there
+because end-of-turn text reaches the operator's Telegram only on a turn that
+*began* as an inbound Telegram message: a tick is injected locally, so anything
+the session merely writes at the end of one is read by nobody, and a reportable
+event has to be delivered by an explicit `telegram_send` call the session
+watched succeed. The tick starts a turn if the session is idle; while a turn is
+streaming it is queued as a follow-up and consumed when that turn ends.
+It sends **nothing** when:
+
+- `armedFile` is configured and missing;
+- `accessFile` is configured and the escalation channel is not verifiably up;
+- an earlier tick is still queued. Ticks coalesce rather than stack, so a slow
+  turn cannot leave a backlog of heartbeats behind it — and two coalesced ticks
+  in a row are the signal that the session is not slow but wedged, which is
+  what the [stall marker](#a-wedged-session-and-the-marker-that-notices) is for.
+
+### One session per directory ticks, and it says which
+
+Activation is a property of the *directory*, so before it arms anything the
+heartbeat asks whether this session is the orchestrator or merely a session
+standing in its directory. It has to: opening a second omp session in the fleet's
+cwd — a shell to read state, say — used to arm a second heartbeat that prompted
+*that* session with the standing loop, and with
+[`authority`](#configuration) delegated it would consider itself entitled to
+merge PRs and cut releases. Two brains, one queue, and nothing in the log to tell
+them apart.
+
+**Under herdr** (`HERDR_ENV=1` with a `HERDR_PANE_ID`), the answer is the pane's
+registered agent name: the heartbeat asks `herdr agent list` for the entry whose
+`pane_id` is this pane's and ticks only when its `name` equals `agentName`. Fleetness
+is the *session* — every pane in it shares `HERDR_SESSION` and the cwd — and
+herdr's `agent` field is the *runtime*, `omp` for the orchestrator and for the
+shell beside it, so neither can tell them apart. The registered name can, it is
+what `herdr agent start fleet --kind omp --pane <id>` sets when the recovery plugin
+starts a fleet into an empty pane — and what `herdr agent rename <pane-id> fleet`
+sets on a pane whose agent herdr already detects, which is the only safe spelling
+while omp is running in it. It is the same identity the recovery plugin keys on. A
+pane with a different name, or no name at all, stays inert.
+
+**Without herdr**, the session claims the directory in a sibling
+`.conductor-tick-owner.json` (pid, session file, claim time) and ticks only while
+it is the live claimant. Liveness is a **pid check, never a timestamp**: a crashed
+orchestrator's claim is reclaimed by the next session rather than wedging the
+fleet until somebody deletes a file, and a slow-but-running orchestrator never
+loses its claim to a lease that expired.
+
+Declining is logged once, at session start, naming the holder — which is the whole
+point, because the original failure was that the second ticker was
+indistinguishable from the first:
+
+```text
+[omp-conductor] orchestrator tick inactive: pane w1:p1 (agent "fleet") owns the fleet tick here — this session will not tick
+[omp-conductor] orchestrator tick inactive: this pane is agent "scratch", not the fleet agent "fleet" — this session will not tick
+[omp-conductor] orchestrator tick inactive: pid 12345 (claimed 2026-01-02T03:04:05.000Z, session …/fleet.jsonl) owns the fleet tick in /home/conductor/.omp/conductor — this session will not tick
+```
+
+A `herdr agent list` that does not answer also declines, for the same reason the
+escalation channel fails closed: under herdr this session is one pane of several
+in that directory, and an unproven identity is exactly the case the check exists
+for. That includes `herdr` not being on the session's `PATH` — worth checking on a
+fleet host, where the orchestrator's environment comes from a unit file rather
+than a login shell — and `HERDR_BIN_PATH` names the binary when it is not, the
+same escape hatch the recovery plugin's `recover.sh` has. On a host with no herdr
+and no prior claimant — the ordinary single-session case — nothing changes.
+
+### The escalation channel is a gate, and it fails closed
+
+Unattended dispatch is only defensible while a tier-2 escalation can reach a
+person. So `accessFile` is checked on **every** tick and never cached at session
+start: the bridge is reconfigured out-of-band, and a heartbeat that trusted a
+startup snapshot would keep dispatching for days after the channel went away. A
+stale arm marker must not outlive the channel that makes running unattended safe.
+
+The check passes only when a bot token is resolvable — `TELEGRAM_BOT_TOKEN` in
+the environment, or in the `.env` beside `accessFile` — and the file parses to an
+object with `enabled: true` and exactly one `allowFrom` entry. Everything else
+stops the heartbeat: no token, so nothing outbound works at all; file missing,
+unreadable or truncated; not JSON, or JSON that is not an object; `enabled`
+absent or false; zero owners paired (nobody to page) or more than one (ambiguous:
+the conductor refuses to guess which human is on the hook). Failure modes are
+deliberately not distinguished in the decision: each one means a page lands
+nowhere. `omp-conductor status` is where they are told apart — its `telegram` row
+names the specific fault.
+
+One caveat the file cannot express: omp-telegram binds its own copy of the token
+in `startBot()` at session start, and only when the bridge is switched on. It
+rebinds only on `/telegram token` or `/telegram on`. So writing a token into
+`.env` out-of-band — or flipping `enabled` to true by hand — restores tier-2
+paging immediately, because conductor sends those itself, while the bridge's own
+tools, `telegram_send` and `telegram_ask`, stay dead until you reload it. After
+either edit, run `/telegram on` in the orchestrator session. Until you do, ticks
+carry an explicit note that an amendment cannot be approved on this surface, and
+the conductor never assumes an answer it did not receive.
+
+Leaving `accessFile` unset passes the gate, because an ordinary developer session
+that happens to have a `.conductor-tick.json` has no bridge to check. It is not an
+off switch for the check: **a fleet deploy always sets it.**
+
+Every tick — sent or skipped — is logged with its reason (`not armed`,
+`escalation channel down`, `tick already pending`) to the omp log. `omp-conductor
+hold` is deliberately **not** one of the gates: hold stops the *dispatcher*
+claiming work, and the tick drives a different session — one whose duties
+(grooming the queue, draining escalations, reporting) are exactly what stays
+useful while dispatch is stopped. Its own off switch is the arm marker. Skips
+are deliberately silent in the UI: a disarmed fleet would otherwise raise a
+notification every interval, forever. The one exception is a malformed
+`.conductor-tick.json`,
+which notifies once at session start and leaves the heartbeat off; silent failure
+there is the failure mode the heartbeat exists to prevent. A conductor config that
+cannot supply a reporting scope logs `tick reporting scope: using material` once
+per session. The interval does not re-log it, because the file is unlikely to fix
+itself between two ticks.
+
+### A wedged session, and the marker that notices
+
+Coalescing is also the only wedge detector this package has. On 2026-08-07 the
+dogfood fleet's orchestrator finished a turn, logged `ui.loop-blocked` right
+after an auto-compaction threshold decision, and never started another. The
+process stayed alive, so herdr's recovery — agent listed AND a non-shell
+foreground process — read healthy. The dispatch daemon is a separate process and
+kept working, so `/healthz` was green all night, while the one brain holding
+merge authority sat on a green PR it never merged. A tick injected two minutes
+into the wedge and an operator's Telegram message five minutes later both went
+unconsumed for 23 minutes, until a manual `SIGTERM`. The heartbeat logged `tick
+skipped: tick already pending` throughout, which is exactly what a merely slow
+turn looks like.
+
+So the heartbeat counts them. Two consecutive coalesced ticks — a full hour at
+the reference 1800-second interval, generous by construction — mean the last
+prompt was never consumed, and the extension:
+
+- writes `<session cwd>/.conductor-stalled`, one line of `<ISO timestamp>
+  <diagnosis>`.
+- logs at **error** level: `orchestrator stalled: 2 ticks queued unconsumed —
+  the agent loop is not draining; see .conductor-stalled`.
+
+Both escapes deliberately leave the session, because a loop that cannot drain
+its queue cannot report on itself — that is the whole failure.
+
+**The daemon reads it.** A marker nobody consumes is an artifact, not an alert,
+so the dispatch daemon checks it on its own five-minute tick — and *before* its
+pause check. The orchestrator is a different process and can be wedged while
+the fleet is deliberately paused, which is precisely the state the dogfood
+fleet was in when this happened. One tier-2 page per stall, keyed on the
+marker's own timestamp so a second wedge the same day is not swallowed as a
+repeat, re-armed when the marker clears, and latched only once the page is
+confirmed delivered — an escalation channel that fails on the one tick that
+noticed must not buy permanent silence.
+
+It restarts nothing. A wedge lands mid-turn, and no other process can tell a
+half-applied edit from an idle loop; the operator attaches, looks, and decides.
+
+**herdr-conductor deliberately does not read it**, though its liveness test
+(agent listed AND a non-shell foreground process) passes straight through a
+wedge. That plugin only runs on `startup`, `pane.exited` and
+`pane.agent_detected`, and a session that stays alive and stops working emits
+none of them — so the check could never fire during the wedge itself. What it
+*would* catch is the recovery afterwards: the marker survives a restart until
+the new session consumes a tick, so every operator SIGTERM-and-resume would
+page about the healthy session they just fixed. Telling those apart needs the
+process start time against the marker's, and herdr's `pane process-info`
+reports pids, not start times. The daemon gives up at most one tick of
+coverage and never cries wolf.
+
+The first tick that actually sends clears the counter and deletes the marker,
+and it deletes one it did not write: recovery normally arrives as a fresh
+process resuming the same transcript, so the session doing the clearing is not
+the session that stalled. Nothing else removes the file. Neither the write nor
+the delete can take the heartbeat down — a filesystem error is logged and the
+tick carries on.
+
+`omp-conductor status` reads the same marker from the **state directory** and
+prints one more line under the daemon block:
+
+```text
+orchestrator   STALLED since 2026-08-07T06:27:55.123Z — 2 ticks queued unconsumed — the agent loop is not draining
+```
+
+That reading is the reference deploy's convention — the orchestrator session
+runs from `~/.omp/conductor`, which is the state directory — and it is
+one-directional: a line there proves a wedge, and its absence proves nothing,
+least of all on a fleet whose session lives somewhere else.
+
+## CLI reference
+
+```bash
+omp-conductor setup [area] [--no-ai] [--project NAME]
+omp-conductor setup host [NAME] [--project NAME]
+omp-conductor setup graph [--no-seed] [--print] [--project NAME]
+omp-conductor start [--port N] [--project NAME]
+omp-conductor --version
+omp-conductor stop
+omp-conductor restart [--now] [--timeout SECONDS] [--port N] [--project NAME]
+omp-conductor upgrade [--to VERSION] [--project NAME]
+omp-conductor upgrade-install --to VERSION [--project NAME]
+omp-conductor upgrade-rollback
+omp-conductor status [--project NAME]
+omp-conductor doctor [--project NAME] [--json] [--probe-telegram]
+omp-conductor ledger [--issue N] [--limit N] [--project NAME]
+omp-conductor board [--project NAME]
+omp-conductor hold [--keep-ticks] [--project NAME]
+omp-conductor stop [--pane] [--project NAME]
+omp-conductor arm [--project NAME]
+omp-conductor disarm [--project NAME]
+omp-conductor tail <issue> [--project NAME]
+omp-conductor extend <issue> --turns N [--project NAME]
+omp-conductor worker pause <issue> [--project NAME]
+omp-conductor worker resume <issue> [--project NAME]
+omp-conductor worker stop <issue> --reason TEXT [--project NAME]
+omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
+omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
+omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
+omp-conductor event record --category NAME --summary TEXT --evidence REF [--occurred-at ISO] [--project NAME]
+omp-conductor report --text TEXT [--kind material|digest|tier2|decision-needed|fleet-stopped|confirmed-failure] [--events IDS] [--notices IDS] [--project NAME]
+omp-conductor message --text TEXT [--project NAME]
+omp-conductor decision open --question TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
+omp-conductor decision resolve <id> --answer TEXT [--project NAME]
+omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
+omp-conductor decision list [--project NAME]
+omp-conductor daemon [--once] [--port N] [--project NAME]
+omp-conductor resume [--project NAME]
+omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
+omp-conductor help
+```
+
+| Command | Scope | Behaviour |
+| --- | --- | --- |
+| `setup [area] [--no-ai] [--project NAME]` | project | The deterministic interview, in a plain terminal — the same prompts, the same one-writer apply sequence, and the same single consent gate as `omp-conductor setup`, which is now one dialog implementation of the shared surface rather than the only way in. Bare is a full first run, or — when the project already exists — a chooser of which area to amend. Naming an area positionally skips that chooser and amends only that area: `tracker`, `gates`, `caps`, `code-graph`, `authority`, `policy`, `escalation`, `reporting`, `brief`. `host` and `graph` are install subcommands rather than areas and are matched first; anything else exits `2` listing both vocabularies. Every prompt shows its current value as the default, and Enter accepts what you see; `Ctrl-C` at any prompt abandons the run and writes nothing. Setup also **reads your repos to propose answers**: the gates prompt is pre-filled from what CI actually runs, and the brief's `## Project context` and release procedure are drafted from every routing repo and shown for confirmation before anything is written. Each probe is a short session with **no shell, no editor and no verbs** in a throwaway shallow clone, and every answer is a proposal you edit or decline — a probe that cannot clone, cannot reach a model, or answers unusably costs you one warning and the shipped stub. `--no-ai` asks every question with the reading half removed. |
+| `setup host [--project NAME]` | host | Re-render and stage the systemd unit, then **run** the install: `install -m 0644` into `/etc/systemd/system`, `daemon-reload`, `enable`, `restart`. Stages the fleet recovery oneshot (`omp-conductor-recover.service`) and its playbook (`/usr/local/sbin/omp-conductor-recover`) alongside, and installs them **before** the fleet units: both fleet units carry `OnFailure=` to the recovery unit, so a crash-looped daemon or herdr session now collects evidence durably, attempts one bounded recovery, and pages tier-2 instead of dying silently (#485). Every command is shown with its exact argv, one confirm covers the batch, and `sudo` asks for your password once before the first step — or is skipped entirely on a fleet that genuinely runs as root. The first failure stops the rest and prints the un-run remainder verbatim so you can finish by hand. Refuses an *escalated* invocation (`sudo`, or `sudo -i`/`su -` detected by the invoking account disagreeing with the fleet's) before writing anything, naming both accounts, because staging derives the unit's `User=`/`HOME=` from whoever ran it. On a non-Linux host the files are still staged and only the `systemctl` steps are refused. |
+| `setup graph [--no-seed] [--print] [--project NAME]` | project | The code-graph install end to end, in one preview and one confirm: check the prerequisites read-only and stop before installing anything when `codebase-memory-mcp` is absent or no MCP entry mounts it (printing the entry to add); `git clone` each missing index-only checkout **as you, never through sudo**; install and enable `cbm-reindex.timer` as root; then seed one indexing run so the first fetch happens while you watch, and verify with the same probe `status` uses. A repo that does not verify is a failure with the remediation, not a success — staged-but-not-trusted is how you discover months later that no worker read an index. `--no-seed` enables the timer without the seeding run and says plainly the graph is unusable until it first fires; it never skips the prerequisite or clone steps. `--print` changes nothing. Exits `1` when no repo has [`graphProject`](#configuration). |
+| `start` | host | Start `herdr-fleet.service` when that optional unit is installed, clearing a previous pane-recovery pin, then start the dispatch daemon and wait until it answers `GET /healthz`. When `omp-conductor.service` is installed, systemd is the only start path: even `start --project NAME` restores the shared unit and uses the name only to verify that `/healthz` serves the requested project. A detached daemon is allowed only when the unit is proven absent. It never clears pause or arms ticks. Refuses if a daemon is already live, naming its pid; manager refusal or unprovable ownership is an error rather than a detached fallback. |
+| `stop` | fleet | Prefer `systemctl stop omp-conductor.service` when that unit's MainPID is the live daemon — systemd then owns the stop and will not schedule a restart for the exit it just requested. Otherwise `SIGTERM`, then `SIGKILL` after a 10-second grace period. Prints `not running` when there is nothing to stop, and tags the confirmation with `(via systemctl)` when the unit path was used. |
+| `restart [--now] [--timeout SECONDS] [--port N] [--project NAME]` | host | Drains the fleet by default: pause new claims, wait until live workers reach `0 / N` (bounded by `--timeout SECONDS`, default 1800 = 30 min), restart, then restore the prior dispatch state. A daemon serving multiple configured projects makes restart host-wide: `--project` is rejected because draining one queue and restarting the shared process would kill another project's workers. Prefer `systemctl restart` when the unit owns the live pid so the replacement stays supervised; only a host proven not to have the installed unit may fall back to the standalone stop/start path. `--now` skips the drain and restarts immediately, orphaning any live runs (old behaviour). A drain that hits `--timeout` restarts nothing and leaves dispatch paused — `omp-conductor resume` lifts it, or re-run `restart` to keep waiting. The new process **salvages dirty live worktrees before orphaning** those rows — see [Deploying a new package onto a busy fleet](#deploying-a-new-package-onto-a-busy-fleet). |
+| `upgrade [--to VERSION] [--project NAME]` | host | Deterministically update the Bun-global CLI, omp plugin, Herdr recovery plugin, and managed brief as one release. Resolves the npm version and exact `gitHead`, pauses only new claims, drains active workers, installs all surfaces, reloads Herdr and the daemon, waits for pane recovery, verifies identities and fleet health twice, then restores the original dispatch state. Host-wide by default: one daemon serves every configured project, so a bare run drains all of them and refreshes every brief. `--project` is rejected when the live daemon serves several projects — draining one queue and restarting the shared daemon would kill another's workers. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. The same transaction runs detached, without a human, as the fleet-installs-itself path: the orchestrator calls the `conductor_install` verb under the granted `install` shape, the daemon validates the version against npm and starts a transient systemd unit (`upgrade-install`) outside the pane and the daemon, and the first tick after the restart verifies version, `/healthz`, ticks, pane and `doctor` against the durable upgrade journal before restoring dispatch — rolling back and paging tier-2 on any gap. |
+| `status [--project NAME]` | fleet | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `brief` / `decisions` / optional `failure classes` and `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, bounded hold groups, and the GitHub API budget (`graphql` / `core` remaining and reset, in the caps block); API failures are marked `DEGRADED` so queue starvation cannot look idle. Active-run lines overlay cooperative worker `paused`/`pausing` from `/healthz` without changing SQLite `running` state or the live worker count. The next tick comes from the live heartbeat process, not a guess from log timestamps. Telegram health uses `getMe` to prove API authentication without sending a message and reports inbound bridge configuration separately. Configured graphs report prerequisites, indexed repos, timer state, and refresh freshness without blocking dispatch. A `reports` block lists everything the outbox has not delivered, with its age, and prints `pending` (nobody has it) differently from `SENDING` (outcome unknown, it may already have arrived) — see [Report delivery](#report-delivery-the-outbox). The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
+| `ledger [--issue N] [--limit N]` | project | The action audit: every [mediated-verb](#the-mediated-verbs-126) mutation and every next-attempt turn budget. Verb entries include the arguments, decision, named refusal, and resulting SHA. Turn-budget entries remain after an override is replaced or consumed. Reads (`conductor_pr_status`) are absent so polling cannot bury the signal. `--issue` narrows both histories; `--limit` defaults to 50. Recent verb refusals and pending turn overrides also appear in `status`. |
+| `board [--project NAME]` | fleet | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`, plus the tracker's current labels: Queue, Claimed, Running, Green, Blocked, Failed, Orphaned, the last 24 hours of Merged and Settled, and Parked (an issue the tracker has not confirmed closed — still open, or a label read that failed — so nothing dispatches it until a human labels it). Columns are mutually exclusive and describe current state, not the newest run row, so a requeued issue is queued rather than failed and a closed issue is neither. Refreshes run/spend/turn values every second, and health plus the label read every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow on a Blocked, Failed, or Orphaned card; `i` / `p` open the issue / PR; `r` refreshes health; `?` shows all keys. Requires an interactive terminal of at least 50×20. |
+| `hold [--keep-ticks] [--project NAME]` | fleet | Soft stop: pause claiming **and** disarm ticks. Daemon and pane stay up. Prefer this when the intent is "stop the conductor" without killing processes. `--keep-ticks` pauses claiming but leaves the arm marker, so the heartbeat keeps reporting and `resume` alone restores the fleet — no fresh arm challenge. See [Stop the conductor](README.md#stop-the-conductor-hold--stop). |
+| `stop [--pane] [--project NAME]` | fleet | Stop the conductor: pause claiming, disarm ticks, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `stop --pane` also pins herdr-conductor recovery off for the conductor agent only — it does **not** stop `herdr-fleet.service` or any other herdr session. Fail-closed: exits nonzero unless the agent is proven gone. To bounce the daemon without stopping the fleet, use `restart`. |
+| `arm [--project NAME]` | fleet | Proof-gated: send a Telegram challenge and write this project's arm marker only after your reply appears as a user turn in the orchestrator transcript. The challenge names the project, so a host running two fleets is not ambiguous. Never auto-armed by `resume` / `hold`. |
+| `disarm [--project NAME]` | fleet | Remove this project's arm marker so its ticks skip; another project's ticks keep running. Also clears a pre-per-project shared `armed` marker while that marker is still what holds this fleet's gate open — otherwise the disarm would not disarm. Processes untouched. |
+| `tail <issue>` | project | Follow the newest run for that issue: the worker's assistant text as `assistant: …` and each tool it calls as `tool: <name>`, printed as they land. Workers are omp sessions inside the daemon rather than terminals, so this is the only way to watch one live — a herdr pane running it becomes an observation window. Starts from the top of the transcript, not the end, so attaching to a run that is already ten turns in shows those ten turns. Exits `1` with `no run recorded for #N` when the issue has never been dispatched, or `no transcript yet (state: …)` when the attempt has not opened one. Otherwise it runs until `Ctrl-C`, or until the run has finished and its transcript has been silent for five seconds, and prints `run ended: <state>`. |
+| `extend <issue> --turns N [--project NAME]` | project | Raise a live worker's effective turn ceiling through its owning daemon without restarting its session. If the latest run is failed, killed, orphaned, or blocked and has no live controller, store a one-shot ceiling for that issue's next claimed attempt instead. A next-attempt value must exceed the project base, every extension must stay at or below `workerMaxTurnsCeiling`, and live extensions remain monotonic. The pending value appears in `status`, is recorded in `ledger`, and is consumed atomically by one claim. |
+| `worker pause <issue>` / `worker resume <issue>` | project | Cooperatively park one live worker without changing its run state or lane. Pause aborts the active turn to harness idle and freezes the remaining wall-clock budget; resume continues the same session with a prompt to re-check its last action before repeating it. This is separate from fleet-level `hold`, which refuses new claims and work-starting mutations while allowing pre-pause completion work and releases. |
+| `worker stop <issue> --reason TEXT [--project NAME]` | project | Terminally end a running or cooperatively paused worker. The reason is required (1–500 characters) and persisted on the run. The command waits for settlement, records the distinct `stopped` state, salvages and publishes dirty work, removes `agent:in-progress` through the durable label outbox, and consumes neither failed-attempt nor continuation budget. If salvage fails, the tree holding the only copy stays in place and the command names it. Repeating stop is idempotent and reports the run's already-terminal state. |
+| `unblock <issue> [--force] [--no-requeue]` | project | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again, and restore the project queue label by default so the dispatcher actually sees it. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label (and the queue label stays off until that run settles), and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. The label changes go through the [label projection outbox](#how-one-tick-works): they are applied inline before the command returns, but **a tracker that refuses them (403, rate limit) no longer fails the verb** — it exits `0`, the intended label state is durable and the daemon retries it, and the output says `label sync queued (N pending) — the daemon retries` instead of claiming the labels were restored. Safety is preserved, but the issue is only claimable once the queue label itself lands: the queue read asks GitHub for issues carrying that label, so a refused queue-label add keeps the issue out of dispatch until projection succeeds. `--no-requeue` clears the state labels only, leaving the queue label untouched — the case where you are about to close the issue. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
+| `verb <conductor_*> [--arg k=v ...]` | project | Run one [mediated verb](#the-mediated-verbs-126) as the orchestrator, from the CLI — the external-orchestrator half of the verb surface. Every argument goes in as a `--arg k=v` string; an orchestrator can merge (`conductor_pr_merge`), label (`conductor_label`), release (`conductor_release`), update a branch (`conductor_pr_update_branch`) or title/body (`conductor_pr_update`), or read PR state (`conductor_pr_status`). The daemon applies the same checks and writes the same ledger rows a session's call would; a missing `--arg` is refused exactly as a missing tool argument is, worker-only verbs (`conductor_push`, `conductor_pr_create`) are refused with `role-not-allowed`, and a refusal exits `3`. An unknown verb exits `2`. |
+| `friction <kind> --detail TEXT [--issue N]` | project | Record one bounded judgment the daemon cannot infer: an escalation belonged in a digest, or a tick report was noise/surprising. The detail is limited to 160 characters. One event never changes policy; three observations inside seven days make the aggregate eligible for one Learning-loop prompt, followed by a seven-day cooldown. |
+| `report --text TEXT [--kind material|digest|tier2|decision-needed|fleet-stopped|confirmed-failure]` | project | Hand a rendered report to the daemon's durable outbox. The command persists the text **before** anything can send and prints a durable handoff id. A material report submitted during quiet hours becomes a held notice until the window opens; otherwise it becomes a report whose delivery the daemon owns, retries with bounded backoff, and records. Delivery is [at-least-once](#report-delivery-the-outbox), so a crash mid-send is retried as a possible repeat and `delivered` never proves exactly one message. `--kind digest` is accepted at most once per local day, decided from the ledger; an unknown `--kind` exits `2`. The remaining kinds declare the report's interrupt category — the escalation handoff: the reporting policy decides between immediate delivery and a durable hold exactly as for a daemon escalation of that category, A repeated identical call exits `2` only while the earlier handoff is still queued undelivered; once it lands, the same text is admitted again (the handoff state decides, not a permanent ledger). Anything still owed appears in `status` with its age. |
+| `decision open --question TEXT [--blocks TEXT] [--resolves-when COND]` | project | Record a question the orchestrator has put to you, and print its id. A question that lives only in a session's context is lost at the next compaction — after which it is either asked twice or dropped silently. `--resolves-when` attaches a machine-checkable condition: `pr-merged:<https url>`, `pr-checks-green:<https url>`, `pr-mergeable:<https url>`, `issue-closed:<n>`, `npm-version:<pkg>@<version>`, or `rate-limit-reset:github`; anything else exits `2` listing the six forms. See [The decision ledger](#the-decision-ledger-136). |
+| `decision resolve <id> --answer TEXT` | project | Record what you decided. Exits `1` naming the id when it is unknown or no longer open, so a second answer cannot overwrite the first. |
+| `decision withdraw <id> [--reason TEXT]` | project | Close a question the session stopped needing, with why. Same guard as `resolve`. |
+| `decision list` | project | Open questions, oldest first: id, age, what each blocks, whether its condition is met, and the question. Prints `no open decisions` when there are none. |
+| `daemon` | host | Run the loop in the **foreground**, ticking every 5 minutes and serving `/healthz`. Admitted workers run in a tracked background pool, so settlement and capacity checks remain periodic while they work; shutdown drains the pool before closing the store. This is what `start` launches and what a systemd unit should call. |
+| `daemon --once` | host | Run a single tick, wait for workers admitted by that tick, and exit. No HTTP server or pidfile — a drill must not register itself as the daemon, or the next reader believes it and the real daemon's in-flight runs get reconciled as orphans. |
+| `--port N` | — | Accepted by `start`, `restart` and `daemon`. Both `--port 9000` and `--port=9000` work; missing or out of range exits `2` rather than falling back to the default, because probing the wrong endpoint is worse than a hard failure. |
+| `--project NAME` | — | Selects a project for project-scoped commands and foreground `daemon`. On an installed shared service, `start --project NAME` still starts the host-wide unit and uses the name only to verify `/healthz`; a draining `restart --project NAME` is rejected when that daemon serves multiple projects. A project-only daemon is available only through an explicit foreground `daemon --project NAME` or standalone start on a host proven not to have the unit. On a multi-project host, `setup host` refuses without a name and says which part needs it: the units it installs are host-global, and only the per-project tail (tick config, brief link) is per-project — pass `--project NAME` or the positional `setup host NAME`. |
+| `pause [--reason TEXT]` | fleet | Stop new claims and work-starting mutations only. The running daemon notices on its next tick; runs already in flight finish. The orchestrator may still merge, update, or label runs admitted before the pause, and may release when the release policy's own preconditions hold. The orchestrator heartbeat keeps ticking if armed — its gate is the arm marker, not this flag. Per-worker pause is separate. Prefer `hold` to silence both. `--reason TEXT` is recorded in the pause sentinel, which `status` shows as the pause provenance. |
+| `resume [--project NAME]` | fleet | Clear pause and any `stop --pane` recovery pin — does **not** re-arm. Run `arm` after an inbound Telegram proof to resume ticks. |
+| `--version`, `-V`, `version` | none | Print the installed `omp-conductor` package version and exit `0`. Works from the global binary and npm/plugin install because it reads the package metadata beside the shipped CLI. |
+| `brief-upgrade` | project | Inspect the package-floor + shared policy (when present) + `POLICY.md` overlay. Reports by default, naming which layers compose; see [Keeping a brief current](#keeping-a-brief-current). |
+| `--migrate` | — | Only for `brief-upgrade`. Lift a bannered `ORCHESTRATOR.md` owned half into `POLICY.md` and recompose. Dry-run unless `--apply`. |
+| `--retrofit` | — | Only for `brief-upgrade`. Propose (or with `--apply`, write) a `YOURS TO EDIT` banner before the first owned-topic heading on a hand-written brief. |
+| `--apply` | — | Only for `brief-upgrade`. Confirms `--migrate` / `--retrofit`. On its own it exits `2`: the legacy single-file merge was removed in 0.4.3. |
+| `--file PATH` | — | Only for `brief-upgrade`. Check a brief that is not where the wizard would have put it, on a host that may have no config at all. |
+| `help`, `--help`, `-h` | none | Print usage. An unknown or missing verb prints it too, and exits `2`. |
+
+Pause is a sentinel under the state directory and survives a daemon restart.
+`hold --project NAME` writes `paused-<name>` for that project only; a bare
+`paused` file (legacy / all-projects) pauses every project. It refuses new claims
+and work-starting mutations, allows completion verbs only for runs admitted
+before the pause, and leaves `conductor_release` to its normal authority, grant,
+and precondition checks. Per-worker pause is independent. Hold also removes the
+arm marker the heartbeat reads, so both brains go quiet without killing processes.
+
+Every one of these is a verb on the `omp-conductor` binary, and the Scope column
+is its project classification, declared once in `src/commands/context.ts`
+(`COMMAND_SCOPES`) and enforced by the tests there (#514):
+
+- **project** — acts on exactly one configured project; a multi-project host
+  demands `--project NAME` (or the documented positional form, e.g.
+  `setup host NAME`).
+- **host** — acts on the one shared host (units, daemon, package surfaces);
+  never resolves a project, so a multi-project config cannot make it ambiguous.
+  `--project` is accepted only for the documented per-project tail that row
+  names, and refused whenever it cannot be honoured (upgrade/restart reject
+  narrowing the shared daemon; `upgrade-rollback` rejects it outright).
+- **fleet** — acts on every configured project by default (or `--all`), with
+  `--project NAME` narrowing to one.
+- **—** (em dash) — the row is a flag rather than a command, or the command
+  takes no project at all.
+
+There is no in-session command: an omp session that wants any of them shells out
+to the binary, which is what keeps one implementation and one ledger entry per
+action.
+
+### Health endpoint
+
+```bash
+curl -s localhost:8787/healthz
+```
+
+```json
+{
+  "ok": true,
+  "rssBytes": 123456789,
+  "projects": [
+    {
+      "ok": true,
+      "paused": false,
+      "activeRuns": 1,
+      "project": "demo",
+      "dispatch": {
+        "completedAt": 1786185678000,
+        "ready": 8,
+        "routed": 8,
+        "admitted": 0,
+        "degraded": true,
+        "holds": [
+          { "reason": "parent-lookup-error", "count": 8, "issues": [321, 320, 318] }
+        ]
+      },
+      "codeGraph": {
+        "configured": true,
+        "status": "degraded",
+        "checkedAt": "2026-08-08T13:00:00.000Z",
+        "prerequisites": { "indexer": "present", "mcpMount": "missing" },
+        "repos": [
+          {
+            "name": "api",
+            "path": "/home/fleet/.cache/conductor-graph/acme/api",
+            "clone": "present",
+            "index": "present"
+          }
+        ],
+        "timer": { "enabled": "enabled", "active": "active" },
+        "refresh": {
+          "result": "success",
+          "fresh": true,
+          "lastSuccessAt": "2026-08-08T12:50:00.000Z",
+          "ageMs": 600000
+        },
+        "reasons": ["worker MCP configuration does not mount the indexer"]
+      }
+    }
+  ]
+}
+```
+
+Any other path or method returns `404`. Top-level `ok` is process liveness across
+every served project; top-level `rssBytes` is the daemon's resident set.
+Per-project blocks keep `paused`, `activeRuns`, `dispatch`, `codeGraph`, and
+`workers`. Nonfatal admission errors and graph degradation keep `ok` `true` so a
+supervisor does not restart-loop. Inspect `dispatch.degraded` and its bounded
+reason groups for queue starvation; inspect `codeGraph` for configured graph
+health. `activeRuns` counts occupied issues — live workers plus green PRs
+awaiting merge.
+
+## What a worker may and may not do
+
+Each worker gets one brief, one worktree, one branch, and no knowledge of the
+dispatcher. The brief is explicit about the boundary:
+
+| It may | It must not |
+| --- | --- |
+| Read the issue and the repo's own guidance (`AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, relevant ADRs) before writing anything. | Touch any path outside its worktree, or switch branches. |
+| Query its repo's [code graph](#code-graph-discovery), when one is configured, by the project name whose `root_path` matches the clone its brief names. | Query that graph by its own cwd or worktree path — no index of a worktree exists — or treat what it returns as current. It is a snapshot of the clone's default branch; the real file in the worktree wins. |
+| Edit code inside its own worktree. | Weaken, skip, delete or loosen **any test it did not write** — that is a design question to escalate, and it is checked by diff review before the push. |
+| Add or update tests for behaviour it introduced. | Suppress a warning, delete an assertion, or special-case an input to make a check pass. |
+| Run the repo's configured cheap gates, each from its listed `cwd`, over the whole tree. | Run docker or image builds, production builds, browser/e2e suites, or the full test suite on the shared host — CI owns the heavy gates. |
+| Review its whole diff, then commit and publish once with `conductor_push`. One corrective push if CI is red. | Force-push, `git add -f`, or add AI/co-author attribution. There is no force path to reach: `conductor_push` publishes that run's branch fast-forward only and takes no other ref. Red twice means stop and report, not push a third time. |
+| Open a PR with `conductor_pr_create`, and poll CI to a verdict with `conductor_pr_status`. | Run `gh pr merge` — or reach `conductor_pr_merge`, which refuses a worker session mechanically. **A worker is never authorised to merge**, whoever else holds the authority, so PRs land one at a time with a freshness re-check; two workers merging concurrently is how agent PRs clobber each other. Who *may* merge is the [`authority`](#configuration) answer, and it is never the worker. The verb refusal is mechanical, and so is the channel: each one is bound to the pid the daemon spawned, so reaching for the orchestrator's socket is refused rather than honoured (see [The transport](#the-transport)). Shelling out to `gh` remains a prohibition, not an impossibility — a session shares the daemon's credentials. |
+| Escalate: ambiguity, a cross-repo contract, a needed credential, a product or data-migration decision, a blocking existing test, CI red twice, or most of the wall-clock budget burned. | Cut a release, push a tag, publish to npm, edit a deployment pin, deploy, or touch infrastructure or secrets. `conductor_release` and `conductor_label` refuse a worker whatever `releasePolicy` says, because the check compares the caller against the configured holder rather than ruling one value out. The in-session tripwire still blocks recognised release/deploy tool calls early and audits the attempt, but it is [defence in depth](#the-mediated-verbs-126), not the gate. |
+
+The worker ends with a seven-line evidence report (issue, PR, observed head SHA,
+state, gates, changed, next). A textual `pushed-green` claim is not success: the
+daemon repeats the PR/head/check verification before it records that state.
+
+### Worker confinement and the integrity tripwire
+
+A worker session is rooted at its worktree `cwd`. **Structured file tools are
+gated mechanically:** `runWorker` asks `createSession({ role: "worker" })`,
+which installs an inline harness extension that blocks `write` / `edit` /
+`read` / `grep` / `glob` when the tool's path resolves outside that worktree
+(symlink-aware). Target selection was already mechanical — only a repo in
+`routing.repos` is ever checked out — and the caps still bound *how much* work
+happens.
+
+General shell access is not confined to the worktree. Its argument is an opaque
+program, so the brief still forbids path escape and the deploy-level answer is a
+least-privilege worker uid (below). The narrower release-policy tripwire does
+inspect explicit command shapes such as `git tag`, `npm publish`, and deploy
+verbs; it blocks those before execution when `releasePolicy` is `none`.
+
+#### Integrity tripwire (package self-hash)
+
+Separately, the conductor watches *itself*. At startup the daemon sha256s every
+`.ts` and `.md` file of its own installed `src/` — the dispatcher and the briefs
+both, since rewriting a brief buys more than rewriting the loop — and re-walks
+that tree on every tick (about 0.6 ms). Any difference at all, changed or added
+or removed, is read as the package having been modified underneath a running
+daemon: the tick claims nothing, the fleet is paused, and a tier-2 escalation
+naming the first few differing paths pages you **once**, not every five minutes.
+
+**A normal deploy never trips it.** The baseline is recorded per daemon process,
+so installing a new build and restarting the unit re-records it from the new
+files; only a change that lands *while* a daemon is holding the package open can
+diverge from it. That also means `omp-conductor resume` on its own will not hold
+— the next tick re-walks, still differs, and pauses again. Put the files back, or
+restart onto the build you meant to be running.
+
+This catches a worker (or human) that still managed to edit the live install —
+including via `bash` — after the fact. It is detection for the package boundary,
+not a substitute for the worktree gate or a dedicated uid.
+
+#### Least-privilege worker uid (deploy)
+
+The largest remaining win is OS-level: run the daemon (or at least worker
+sessions, when the harness supports a uid switch) as a user that can write only
+its worktrees and mirrors. A sketch that matches the reference single-host
+deploy:
+
+1. Create a system user, e.g. `conductor-worker`, with home under
+   `/var/lib/conductor-worker` (or similar).
+2. `chown` the project's `workspaceRoot` and `mirrorRoot` to that user; leave
+   `~/.omp/conductor/config.json` readable only by the operator/daemon account
+   (`0600` as shipped).
+3. Do **not** put the worker uid in `docker` / `sudoers`, and do not give it the
+   operator's `gh` auth if a narrower deploy token can open PRs in the routed
+   repos alone.
+4. Point the [example systemd unit](systemd/omp-conductor.service.example)
+   `User=` / `Group=` at that account once the daemon itself should run
+   unprivileged end-to-end.
+
+Until that uid exists, a root-or-operator daemon still has a mechanical
+worktree gate on structured tools and an integrity tripwire on its own package —
+but `bash` plus host credentials remain a prompt-and-deploy problem.
+
+### The orchestrator is unconfined, deliberately
+
+There is **no mechanical file gate on the orchestrator session**, and that is an
+operator decision rather than an omission (#143).
+
+A previous release jailed it to an allowlist. That gate could only ever be
+installed by `createLocalSession`, so it existed exactly in the sessions this
+daemon spawns — and the supported shape for a heartbeat orchestrator is an
+`omp` session the operator starts themselves, which never had it. A boundary
+present in one deployment out of two is not a boundary, and the brief asserting
+it was absolute was the worse half of the bug: a session that believes it is
+gated stops checking itself.
+
+What holds the orchestrator instead:
+
+| | |
+| --- | --- |
+| **The brief** | `ORCHESTRATOR.md`'s hard boundaries — never read or edit a worker's checkout or the mirror cache; when you need a run's code, read its PR. |
+| **The action ledger** | Every `conductor_*` mutation and operator-selected next-attempt turn budget remains auditable. `omp-conductor ledger` shows both, including refused calls and consumed or replaced budget overrides. |
+| **The dispatcher** | Merge, label and release authority are checked in the daemon against the operator's grant, across a process boundary, never in the prompt. |
+
+Unconfined means auditable, not licensed. `orchestratorReadPaths` is retired: it
+is still accepted in a config and ignored, so a fleet carrying it upgrades
+without editing anything.
+
+## The mediated verbs (#126)
+
+A session can reach `gh`: it inherits the daemon's environment, credentials and
+all. It is told not to publish with it. These verbs are the sanctioned route
+instead, because the dispatcher owns the settlement record — a push or a PR the
+daemon did not perform is a run it cannot account for, and the checks that would
+have refused it never ran. The point of them is *where those checks run*: in the
+daemon, across a process boundary, not in a prompt the model can rewrite.
+
+### The verbs
+
+| Verb | Allowed caller | What the daemon checks before acting |
+| --- | --- | --- |
+| `conductor_push` | the worker owning the run | The ref is exactly `refs/heads/<that run's branch>`. Fast-forward only; there is no force argument to reject because none is declared. |
+| `conductor_pr_create` | the worker owning the run | The run has no open PR (the same guard admission uses); head is the run branch; base is the repo's configured `defaultBranch`. |
+| `conductor_pr_status` | worker or orchestrator | Read-only — nothing to gate. A worker reads only its own run's PR; an orchestrator may name any syntactically valid PR URL, open, merged, or closed, and gets its live state and head (checks are reported when available; a merged or closed PR reports its state instead of an `expected OPEN` refusal). |
+| `conductor_pr_update_branch` | orchestrator, or the worker owning the run | The PR belongs to this project and is open. A worker may only name its own run's PR. |
+| `conductor_pr_merge` | **orchestrator only** | Ordinarily, `authority.merge` equals the caller. A hand-edited `recoveryMerges` entry may instead authorize one exact unrecorded PR/head/reason while held. In both paths, `headSha` equals the live head *at execution time*; checks are green at that same SHA; the project route and migration chain are valid; the project's single merge slot is free. |
+| `conductor_label` | **orchestrator only** | The label is in the project's own vocabulary. Lifecycle labels stay the daemon's. |
+| `conductor_release` | **orchestrator only** | `authority.release` equals the caller; the per-shape grant permits it; the artefact or environment was declared; the release preconditions hold; the `reason` is in the closed enum. `version-bump-pr` creates or re-validates one deterministic version-only PR and, on a later call, merges only its exact green head through the project's single merge slot. |
+| `conductor_install` | **orchestrator only** | Gated like a release act: the `install` shape defaults to `human` and a grant is what moves it. The daemon refuses a version npm does not expose with a full `gitHead`, refuses while another install is still in flight, and otherwise starts a detached transient unit that pauses, drains, installs the CLI/omp plugin/Herdr plugin and reloads — outside this session and the daemon. The unit never declares its own success; the first tick after the restart verifies and reports through the durable outbox. |
+
+Standing merge and release authority use the same exact rule: **the caller's
+role must equal the configured holder.** `authority` has exactly two values, so
+a `!== "human"` test would have let a *worker* release. A worker is refused
+every release shape under the most permissive config there is. The exact
+operator-authored recovery tuple below is the sole authority exception inside
+`conductor_pr_merge`; a reviewed version bump is instead a `conductor_release`
+operation governed throughout by release authority.
+
+`recoveryMerges` is deliberately narrower than standing merge authority. It is
+an operator-authored, one-PR escape hatch for a recovery branch that cannot have
+a run row—for example, a conflict repair created after the fleet was held. It
+does not admit new work, unpause the fleet, widen repository routing, bypass
+live-head or check validation, or make a general class of PRs mergeable.
+Authorizations are re-read from config on every call and every attempted merge
+is written to the ordinary verb ledger, including refusals.
+
+For a repo with `release.versionFile`, call `conductor_release` with
+`shape=version-bump-pr` and the intended `v<semver>` tag. The requested version
+must be newer than the live semantic version. The first call creates
+`conductor/release-<version>` from the live default branch, changes only the
+declared JSON `version`, and opens a normal PR. Call it again after CI: the daemon
+re-reads that exact PR head, verifies the PR contains only the semantic version
+change, requires green checks, and merges with GitHub's exact-head guard. The
+ordinary action ledger records both calls. A raw source push is never delegated,
+and a worker makes no release decision.
+
+For Git-backed releases, a repo that declares `release.versionFile` refuses both
+tag creation and a new tag push until the live default branch's version matches
+the requested tag. `git-tag` is idempotent when the named tag exists locally but
+has not been pushed: it re-points the tag to the verified live default-branch
+head. `git-push-tags` performs the same re-point immediately before pushing if
+the default branch moved between the two calls. A tag already published on
+origin is immutable: an identical tag is accepted as already complete, while a
+different published target is refused and must use a new tag name.
+
+A `github-release` for the same repo likewise requires that reviewed tag to be
+present on origin and verifies the tag's version file before creating the
+release; it never lets GitHub synthesize the missing tag.
+
+### The transport
+
+Identity is never an argument. `project`, `run`, `issue` and the caller's role
+come from **which socket the call arrived on**, and a request carrying any of
+those field names is refused outright, named. So a worker on run X cannot *ask*
+to merge run Y's PR — on its own channel that request is unexpressible.
+
+**Each channel is bound to one process, because the modes cannot tell sessions
+apart.** Every session runs as the daemon's own uid, so it matches the *owner*
+class here: it can list this directory and connect to any socket in it, including
+the orchestrator's. Authorisation and the ledger both read the role from the
+channel, so a worker doing that would have been authorised as the orchestrator
+(under `authority.merge: "orchestrator"`) *and recorded as* the orchestrator. No
+file mode closes that — the owner bits belong to the uid the session already has.
+
+So the daemon binds each channel to the **pid it spawned for that session**, and
+refuses a connection from anything else without answering it, logged the way an
+impersonation is. Until a channel is bound it refuses everything, because the
+socket necessarily exists before the child that connects to it. The kernel
+supplies the pid: `SO_PEERCRED` on Linux, `LOCAL_PEERPID` on macOS. A host where
+neither can be asked — no loadable libc, or the call refused — refuses every
+connection on a bound channel and says so at startup, rather than falling back to
+the uid, which under one shared uid is no check at all.
+
+The residual is narrow, real, and worth stating: one uid can `ptrace` and signal
+its siblings, so a determined session can still interfere with the process that
+*is* bound. That is a far higher bar than connecting to a socket, and closing it
+needs separate OS principals.
+
+```
+<state dir>/verbs/                 daemon-owned, mode 0711
+  run-7-9a783d877d422b9e.sock      0600, bound for run 7
+  run-9-1c40e2a5b6d3f018.sock      0600, bound for run 9
+  orchestrator-4b1f...c2.sock      0600, the orchestrator's
+```
+
+**What these modes buy, and what they do not.** They keep every *other local
+account* out: `0711` on the parent is traversable but not listable, so no other
+user can enumerate the fleet's sockets, the suffixes are unguessable, and only
+the daemon's uid can connect to a `0600` socket at all.
+
+They are **not** a boundary between runs. Sessions are child processes of the
+daemon running as its own uid, so a session matches the owner class on all of
+these: it could list the directory and connect to a sibling's socket. Each run is
+*handed* its own path and nothing else, which is a convention the run has no
+reason to break — not an enforcement. What makes breaking it visible is the
+[ledger](#the-ledger): every call is recorded with the channel it
+arrived on, so a worker calling on another run's socket is in the record.
+
+Closing that properly needs the sessions to be different OS principals. A
+per-run credential boundary that did exactly this shipped and was removed in
+0.5.0 — it worked, and the cost was that it also hid the operator's own model
+credential from every session, so nothing could start. It is not worth
+re-litigating without solving that first.
+
+Before binding, the daemon verifies every component of the path is owned by
+itself (or root), free of symlinks, and unwritable by anyone else; a failed
+check **refuses dispatch** rather than degrading. Paths are unguessably
+suffixed, and only the daemon ever unlinks one.
+
+Peer credentials are asserted server-side — `getpeereid` on macOS, `SO_PEERCRED`
+on Linux — and the daemon states at startup exactly what that buys rather than
+implying more. Sessions are child processes running under the daemon's own uid,
+so the peer check proves the caller is a local process on this host; it is the
+socket, not the uid, that says which run is calling. A connection whose peer
+cannot be read at all is closed with no reply and logged.
+
+```
+verb transport: verb sockets in ~/.omp/conductor/verbs (mode 711); each socket
+0600 under the daemon's own uid; peer uid asserted with getpeereid
+```
+
+**No mutation route exists on the HTTP port**, and none may be added. That
+surface is unauthenticated loopback TCP reachable by any local user; a `PUT` or
+`POST` at any verb path answers 404, pinned by a test.
+
+The child-side tool handler is a thin client only. It forwards arguments and
+renders the answer — no policy branch, no local fallback, no second route. With
+no socket it fails closed and says so, rather than reaching for `git push`.
+
+### The ledger
+
+Every mutating verb call is recorded with its arguments, the decision, the
+named refusal reason and any resulting SHA. Reads are not: a status poll every
+thirty seconds would bury the refusals the record exists to surface.
+
+Every `extend` that sets a next-attempt budget also appends an audit entry.
+Replacing or consuming the pending override does not erase that history.
+
+```console
+$ omp-conductor ledger --issue 7
+acme — 3 verb call(s), 1 refused (newest first)
+  2026-08-09 11:04:12  REFUSE  conductor_pr_merge         worker #7  [role-not-allowed]
+      prUrl=https://github.com/acme/api/pull/7 headSha=9a783d8… reason=preconditions-met
+      refused: merge authority is the orchestrator's, never a worker session's.
+  2026-08-09 10:58:03  ALLOW   conductor_pr_create        worker #7
+      title=fix: settle the head check body=Closes acme/tracker#7
+      opened https://github.com/acme/api/pull/7 (conductor/issue-7 → main).
+  2026-08-09 10:57:41  ALLOW   conductor_push             worker #7  9a783d877d42
+      (no arguments)
+      pushed refs/heads/conductor/issue-7 at 9a783d877d42….
+```
+
+The newest few also appear in `omp-conductor status`, because a refused merge is
+news: it means a session tried to do something the config does not permit.
+
+`release-policy.ts` stays installed as defence in depth — it refuses early, in
+the session, with an explanation the model can act on in the same turn, and it
+leaves a durable record that something tried. It is no longer what *stops* a
+release. Treat a block there as evidence about a session's intentions; the
+daemon is what prevented it.
+
+
+## Limitations
+
+Known and deliberate in this version:
+
+- **`gh` is shelled out to.** Every tracker operation spawns a process and does its
+  own TLS handshake (roughly 200-400 ms each), and failures are classified by
+  matching human-readable stderr rather than a status code. The upside is that no
+  token is ever handled, stored or logged by the daemon.
+- **`listReady` fetches a single page of 100 issues.** A queue deeper than 100
+  ready issues truncates silently. A backlog that size is a staffing problem before
+  it is a paging one.
+- **Spend accounting depends on harness telemetry.** Cost arrives only when the
+  harness run carries it; without it `spendUsd` reads `0`, `status` shows `$0.00`,
+  and the daily-spend cap never fires. The turn and wall-clock ceilings are what
+  actually bound a runaway in that case. Do not treat `$0.00` as proof that nothing
+  was spent.
+- **GitHub is the only tracker.** The internal `Tracker` port is deliberately
+  provider-neutral, but `tracker.kind` accepts only `"github"` today.
+- **One daemon serves every configured project by default.** `setup host` writes a
+  unit without `--project`. Pass `--project NAME` only to filter a foreground or
+  temporary daemon down to one project.
+- **Labels are matched exactly and case-sensitively.** `Ready-For-Agent` is not
+  `ready-for-agent`, and the mismatch is silent: the issue is simply never picked
+  up.
+- **No cross-process lock on the mirrors.** Two dispatch loops fetching the same
+  repo at the same instant can collide on git's ref locks; the run fails and is
+  retried rather than corrupted.
+- **Uniquely local mirror branches are retained.** Terminal runs are reaped
+  automatically only after every commit exists on a remote ref. A failed salvage
+  push deliberately leaves its branch and tree for an operator rather than
+  trading disk hygiene for data loss.
+- **`stop` is a bounded best-effort drain.** A signal stops new ticks and the
+  daemon waits for its active worker pool before closing the store. The CLI
+  escalates to `SIGKILL` after 10 seconds, so a worker that needs longer is
+  orphaned and salvaged on restart. Use `pause`, wait for `workers 0 / N`, then
+  stop when a clean drain matters. The supervising unit keeps
+  `SuccessExitStatus=0 143` and renders `Restart=always` (#546): systemd
+  restarts the daemon on any exit — clean or signalled — **except** an explicit
+  `systemctl stop`, which it records as intentional and never undoes. So an
+  unattended SIGTERM (a worker's `bun test`) costs a few seconds of downtime
+  instead of an outage that waits for a human, while the operator's own stop
+  still stops and stays stopped. A genuine crash loop still trips the
+  start-limit burst and reaches the recovery unit through `OnFailure=`, so the
+  restart policy stays a visible detector rather than a silent spin. Prefer
+  `omp-conductor stop` / `systemctl stop` over raw `kill`: a raw kill is not an
+  intentional stop, and the daemon comes straight back.
+- **A failed orchestrator degrades quietly.** The daemon logs a warning and keeps
+  running, but tier-1 escalations then land in issue comments — which is exactly the
+  "nobody reads it until morning" path the orchestrator exists to avoid. The warning
+  is in `daemon.log`; nothing pages you about it.
+- **Workers are not terminal panes, so you cannot watch them there.** Each
+  worker is an omp session the daemon starts as a child process. The resident
+  daemon tracks workers in a background pool so the five-minute loop keeps
+  settling PRs and checking capacity; shutdown waits for that pool. Herdr still
+  shows exactly one pane (the orchestrator's) regardless of concurrency.
+
+  The cap does work. The admission loop (`admitCandidates` in `src/daemon.ts`) computes
+  `slots = maxConcurrentWorkers - live workers`, admits at most that many issues
+  per tick, and dispatches them together. To see them, read `omp-conductor
+  status`, which lists every occupied issue, or follow `daemon.log`.
+- **Report delivery is at-least-once, never exactly-once.** The Telegram Bot API
+  takes no client-supplied idempotency key, so the window between "Telegram
+  accepted it" and "SQLite recorded that" is irreducible. The daemon resolves it
+  toward a duplicate — the report is retried and the retry says it may be a
+  repeat — because a duplicate you can recognise by its report id is cheaper
+  than a silently dropped page. `delivered` means Telegram accepted an attempt,
+  not that exactly one message exists. See
+  [Report delivery](#report-delivery-the-outbox).
+- **Workers stop at green PRs.** They are never authorised to merge, release or
+  deploy: those actions default to a human, and while setup may grant either to
+  the orchestrator, `authority` never grants them to a worker or the dispatch
+  daemon. The verbs refuse a worker mechanically, and a worker reaching for
+  another session's channel is refused too — each channel is bound to the pid the
+  daemon spawned for it. What remains a prohibition rather than a gate is shelling
+  out to `gh` directly: sessions inherit the daemon's credentials. That shows up as
+  a mutation with no matching ledger entry, which is a mismatch an operator can
+  find.
+- **The worker gate is partial, and the orchestrator has none.** A worker's
+  structured `write` / `edit` / `read` / `grep` / `glob` calls are gated to its
+  worktree by an inline harness extension; `bash` is not, so a shell one-liner
+  can still leave the tree, and no claim in this README says otherwise. The
+  orchestrator is [unconfined on purpose](#the-orchestrator-is-unconfined-deliberately)
+  — its boundaries are its brief and the verb ledger. Prefer a
+  [least-privilege worker uid](#least-privilege-worker-uid-deploy); the
+  [integrity tripwire](#integrity-tripwire-package-self-hash) still pages if the
+  installed package itself changes under a live daemon.
+
+
+## License
+
+MIT