omp-conductor 0.18.2 → 0.19.1

package/REFERENCE.md

@@ -180,6 +180,19 @@ 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).
 
+One finding is a conjunction rather than a fault. `bootstrap-deadlock` (#910)
+fires when no worker on this host can start — because the *installed* conductor
+cannot load its harness, exercised the way a worker does by running
+`harness-loader.ts` under `bun --no-install` — and says the other half out loud:
+a release cannot publish the fix either, because publishing needs a merged
+worker pull request, so the broken install blocks its own replacement. It is
+deliberately its own finding rather than a sentence appended to the stale-setup
+ones, because the two states call for opposite actions: "run `setup host`" is
+correct advice for a stale install and useless here, since no amount of
+re-running setup replaces the installed package. Its fix names the one command
+that breaks the cycle — `upgrade --bootstrap <sha> --source <checkout>` — and an
+ordinary stale host still reads exactly as it did.
+
 ## Onboarding
 
 `omp-conductor setup` is the whole of it. One command, in a plain terminal, doing
@@ -271,6 +284,27 @@ names the first missing key instead of prompting. Add `--save-answers FILE`
 to an interactive run to capture only accepted answers for deterministic
 replay. Unknown keys are ignored so one file can cover a larger interview.
 
+**A failed apply keeps its answers (#864).** The interview is the expensive half
+and it usually is not what failed: on 2026-08-21 `setup policy` failed at its
+post-interview gates several times, and every retry re-asked the whole merge,
+release, arming and review interview — the same `runs-settled` value was typed
+five times while the real fault was a runtime gate. So when the apply phase
+throws, the confirmed answers are written to
+`<state dir>/setup-resume-<project>.json` (mode `0600`, beside the config they
+describe) and the failure names the exact command that replays them:
+
+```bash
+omp-conductor setup policy --project conductor --resume ~/.omp/conductor/setup-resume-conductor.json
+```
+
+`--resume` is `--answers` with a binding, and the binding is the point: the file
+records a hash of the config it was answered against and the version that wrote
+it. A changed config refuses, naming both generations — replaying an old plan
+over newer policy would silently overwrite whatever changed it — and so does a
+version mismatch, because the answer keys are a schema an upgrade may have
+renamed. A completed setup deletes its own resume file, so a stale one cannot
+invite a replay of answers that already landed.
+
 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:
 
@@ -446,6 +480,23 @@ Per tick, for the daemon's project:
 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.
+
+   A lifecycle label read from that **list** is a suspicion, not a verdict
+   (#891). `listReady` is a label-filtered search, and GitHub's search index is
+   eventually consistent, so an `unblock` that has already landed can still come
+   back carrying the label it cleared. Before a candidate is dropped for a
+   lifecycle label, the daemon re-reads that one issue's live labels
+   (`issueSnapshot`, a direct REST read) and admits normally when the exact read
+   is clean. Measured 2026-08-22T09:18Z: `unblock 889` cleared `agent:failed`,
+   `gh issue view` returned the clean set immediately, and the pass woken right
+   after still held it `stale-lifecycle` with the fleet at 0/5.
+
+   The re-read is bounded to candidates a lifecycle label would otherwise drop,
+   and skips two of those: an issue whose newest run is active (its own row is
+   the authority) and an operator-parked one (a park is a decision, not a stale
+   label). An unreadable re-read is **fail-closed** — the issue stays out of the
+   pass and is held as `issue-state-lookup-error`, never as `stale-lifecycle`,
+   because "the tracker could not say" is not evidence of a residual label.
 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
@@ -797,6 +848,75 @@ the queue label is refused with `file-lane-unparseable` and an actionable
 message, because promoting beside overlapping work on a section that plainly
 tried to declare is the exact gap the interlock exists to close.
 
+#### What status shows
+
+`status` renders the two lifecycle kinds as two blocks, because "a branch is
+holding a file" and "a worker is editing that file" need different answers:
+
+- **`mutation leases`** — a live worker, or a dispatched unsettled review
+  revision. Each carries the run holding the lease, how long it has held it, the
+  read the interlock proves occupancy with (`worktree` for a live checkout,
+  `branch` for a worker-free row's mirror branch — the same condition
+  `probeRunLane` uses), and the files its declaration occupies.
+
+  Two further lines hang off a lease when they have something to say. **`pane`**
+  names the Herdr pane representing that worker, or `degraded` with the reason
+  there is none (#841) — see [the worker-pane
+  contract](#a-worker-gets-a-herdr-pane-but-the-pane-is-never-the-worker-840).
+  **`tokens`** appears only when a run's reasoning share of its output tokens is
+  disproportionate (≥80%, #518): the fact that distinguishes a run deliberating
+  expensively in wall clock but cheaply in dollars from one that is idle or
+  stuck. Run 42f73f52 read `24/180 turns  $0.05` after 43 minutes and looked
+  barely started; 96% of its 106.3k output tokens were reasoning, its turns were
+  arriving at 200 seconds each, and the 180-turn cap was therefore unreachable —
+  the wall clock was the only ceiling that could ever fire. Both numbers come off
+  the same `usage` block the spend already comes from, so neither costs a
+  provider call, and both are recorded live rather than at settlement: the moment
+  this explains is forty minutes before `wall-clock-cap-spinning` (#494) fires.
+  An ordinary reasoning share prints nothing, and a run with no token counts
+  makes no claim about them — absent is not 0%.
+- **`preserved artifacts`** — worker-free `pushed-green` / `pushed-pending` rows.
+  Durable work with nothing editing it, so it is shown with how long it has been
+  waiting and on what: a PR to review and merge, or (with no PR) a branch
+  `conductor_pr_recover` can still publish. No turn rate and no cap projection —
+  those describe a session in progress, and printing them beside work nobody is
+  running is how a settled artifact came to read as a busy one.
+
+Membership is the union of the run's own live state and the snapshot's recorded
+`leasedRunIds`, never the ids alone: a live worker is a lease by definition, and
+the recorded set exists to add the case a state read cannot see — a dispatched
+revision on a row that still says `pushed-green`. Both blocks are rendered from
+the snapshot alone, so a status read never probes git and never mutates anything.
+
+#### What holds a lane, and what merely owns an artifact
+
+Occupancy follows the **mutation lease** (#899): the runs something is writing
+through right now — a live worker (`claimed`/`running`), or a review revision the
+daemon has dispatched and that has not settled. A worker-free `pushed-green` /
+`pushed-pending` row still owns its issue and its PR, so its work is never
+re-implemented, but it no longer holds its files: holding them meant one settled
+artifact idled every overlapping candidate until a human merged it.
+
+The trade is deliberate. A merge conflict is a later, recoverable event
+(`conductor_pr_update_branch`, or the `merge-conflict` failure class); an idle
+fleet is an immediate, unrecoverable one.
+
+Because a released branch's files may legitimately be taken by someone else,
+every path that *resumes* writing one re-proves the lane first (#925):
+
+- a **continuation** is held (`file-lane`) when the branch it resumes actually
+  carries a file a lease holds — read from the branch, not from the candidate's
+  declaration, which may be narrower or absent;
+- **`conductor_pr_recover`** refuses (`recovery-lane-occupied`) rather than
+  publishing a frozen branch into review beside a worker still rewriting one of
+  its files. Adopting an already-open PR is not gated: it publishes nothing.
+
+The two sides fail in opposite directions, on purpose. Admission is unattended
+and continuous, so an unreadable probe admits (fail open) rather than stalling
+the queue on a transient git read. Recovery is one deliberate call whose refusal
+is legible and retryable, so an unreadable lane refuses
+(`recovery-lane-unprovable`) rather than publishing on an unproven one.
+
 ## Routing
 
 An issue must carry **exactly one** `repo:<name>` label naming a repo in
@@ -875,7 +995,8 @@ rest. `0` is a real value (a hard stop), not "unset".
 | --- | --- | --- |
 | `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`. |
+| `dailySpendUsd` | `25` | Rolling-day spend ceiling in **estimated** USD, or `null` for no spend gate. `0` is a hard stop. Metered from assistant `usage.cost.total` — OMP's own local price for the tokens a session recorded, not the provider's bill. |
+| `maxRunSpendUsd` | `null` (derived: `dailySpendUsd / maxConcurrentWorkers`) | Ceiling on what **one run** may spend, and the amount admission reserves from the day's budget before launching it. Positive, or `null` to derive; never larger than `dailySpendUsd`. See [Per-run spend reservations](#per-run-spend-reservations-851). |
 | `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. |
@@ -891,6 +1012,149 @@ 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`.
 
+### Install-surface parity, recorded (#919)
+
+`omp-conductor` installs onto three surfaces — the Bun-global CLI/daemon tree,
+the omp plugin, and the herdr recovery plugin — and on a host whose installs are
+manual they diverge silently. Measured on this host, 2026-08-22: the omp plugin
+sat on the withdrawn 0.18.1 release beside a 0.18.0 daemon for about a day, with
+no finding, no status line and no escalation.
+
+The dispatch pass records the three identities once per pass, and the cheap
+surfaces read that row:
+
+- `status` is silent while they agree, prints the mismatch with
+  `omp-conductor upgrade --to <version>` when they disagree, and says
+  **`not observed yet`** before the first pass has looked — never "they agree";
+- the tick digest names a **proven** mismatch only.
+
+Neither spawns a process for it, and that is the design rather than an
+optimisation: probing costs three subprocesses, and doing it at render time took
+the tick's own suite from 8.4s to 83.4s while spawning three children every
+fifteen minutes to answer a question that changes only when someone installs
+something.
+
+An absent surface, a `local:` herdr link and a pin whose release could not be
+verified are steady states someone chose, so they produce no status row and no
+tick line — a warning repeated every fifteen minutes trains an operator to
+ignore the row that matters. `omp-conductor doctor` keeps the full nuance,
+including those cases, and is still the on-demand answer.
+
+### The one peer plugin that is also a contract (#961)
+
+The same pass records three more versions, about `omp-telegram`: what is
+installed, what its running daemon reports, and what is published. That plugin
+gets this treatment and no other because a *conductor* instruction depends on its
+behaviour — the floor tells every session answering an inbound message to call
+`telegram_send` with neither `chat_id` nor `thread_id`, so the reply stays in the
+topic it arrived in.
+
+Measured on this host: the installed 0.12.1 predated that ladder. Its send path
+had two rungs (explicit `chat_id`, then in-process `lastTarget`), so the mandated
+call refused with `no active telegram chat` three times on 2026-08-21, and each
+refusal cost an improvised recovery — once by passing route ids by hand, which is
+precisely the anti-pattern #882 names as its own silent fake. The published
+0.12.2 has the four-rung ladder plus per-rung diagnostics. **The fix had been on
+npm for days, and no surface said so**, so three sessions did transcript
+archaeology to reach a conclusion `npm view` answers in one call.
+
+- `status` grows a `tg-plugin` row **only** on a proven divergence: installed
+  behind published, or a daemon serving something other than what is installed.
+  Silent otherwise, and silent when nothing was recorded — a fleet that does not
+  use Telegram must not grow a permanent row about a plugin it does not have.
+- `doctor` reports the finding at full nuance, always `warn` and never `fail`:
+  the fleet dispatches, merges and reports fine on a stale plugin. One
+  instruction does not, and the remedy is an install the operator owns.
+
+Behind-published outranks daemon-stale deliberately, because the remedies
+compose: an install without a restart leaves the daemon on the old code. And an
+unreachable registry is **`unknown`**, never `current` — a check that could not
+run must not certify, and a host with no outbound npm access must not grow a
+permanent warning about it. No minimum version is compiled in: a baked-in
+baseline goes stale in exactly the way this check exists to catch, and would
+re-create #904's divergence with one more copy of the number.
+
+### Per-run spend reservations (#851)
+
+A daily cap alone is a *post-spend* stop: it compares spend-to-date at
+admission and pauses the fleet on the **next** pass, so one expensive run can
+cross the ceiling by its whole cost before anything objects. Measured on this
+package's own fleet, 2026-08-21: one `@slow` run spent an estimated $25.16
+against a $25.00 daily cap, and the fleet paused only after it had settled.
+
+So the cap is enforced in two places, and both are mechanical:
+
+- **At admission, as a reservation.** Before a run launches, its whole per-run
+  allowance is reserved out of the day's budget and recorded on the run row. A
+  candidate is held (`spend-reservation`) when spend-to-date plus every live
+  run's reservation plus its own would exceed `dailySpendUsd`. The reservation
+  lives on the row, so a daemon restart re-reads it instead of forgetting it,
+  and a run that settles for less than it reserved releases the remainder
+  simply by ceasing to be live — there is no release step to forget.
+- **Inside the run, as a ceiling.** A session that reaches its allowance is
+  killed like any other cap kill, through the ordinary salvage path, so its
+  work is preserved and its PR (if any) survives. Response cost is known only
+  when a response completes, so the **declared overshoot is exactly one model
+  response** — never zero, and never a whole run.
+
+The allowance is `maxRunSpendUsd` when set, and otherwise
+`dailySpendUsd / maxConcurrentWorkers`: the largest per-run reservation that
+still lets the fleet run at its configured concurrency. Reserving the whole
+daily cap per run would bound overshoot just as well and would silently
+serialise every fleet on defaults, which is a concurrency change disguised as a
+spend guard; N reservations of cap/N are still the cap, so nothing is given
+away. Set `maxRunSpendUsd` explicitly to bound one run harder.
+
+`status` labels the figure **estimated** for the same reason the table above
+does: on the 2026-08-21 incident the local estimate read $25.16 while roughly
+$16 of provider credit actually moved, so presenting it as billed spend would
+assert something conductor cannot see. Reservations are shown beside it, because
+that — not spend-to-date — is what the next admission subtracts.
+
+#### And whether that figure means anything (#970)
+
+Both halves of the cap read one column: `spendUsd`, summed by
+`store.spendSince`. When the harness stops reporting cost the column reads
+`0.00`, the sum shrinks, and the cap compares a fraction of reality against its
+ceiling — #46's *"the daily spend cap is theater"*, recurring. The check's own
+wording has always said the quiet part: **$0.00 spend is not proof of no spend.**
+
+Measured on this fleet, counting only runs that did any work:
+
+| day | worked | reported $0.00 |
+|---|---|---|
+| 2026-08-15 → 20 | 15–118 | 0.0–3.8% |
+| **2026-08-21** | 22 | **31.8%** |
+| **2026-08-22** | 12 | **75.0%** |
+
+Six days of baseline, then a regression — with one run taking 213 turns for
+$0.00. Three things were wrong with the detection, and all three are fixed:
+
+- **It was all-or-nothing.** The predicate was `window.every(spendUsd === 0)`,
+  so it fired only on total loss. Replayed over all 410 windows in this fleet's
+  recorded history it would have fired 14 times while staying silent through
+  **37** windows that had lost a majority — partial loss, the common case, was
+  the invisible one. On 2026-08-21 every window contained one metered run, so it
+  was silent all day. It is now a share of the window, reported at a majority.
+- **It counted runs that never worked.** A kill before the first turn records
+  `$0.00` honestly, and 26 of this project's 48 zero-spend rows are exactly
+  those. They are excluded from both sides now, so a burst of administrative
+  kills neither fires a telemetry finding nor dilutes a real one. The sampler
+  over-reads to compensate.
+- **It was on-demand only.** `spend-telemetry` lived in `doctor` and nowhere
+  else, which is precisely the gap #919 closed for install surfaces — and the
+  stake here is a spend *control*. `status` now carries a `spend telemetry` row
+  directly beneath the figure it qualifies, computed from the same store read,
+  silent while telemetry is healthy.
+
+The threshold is a majority rather than any single zero, because the healthy
+baseline is 0–3.8% and not zero: a legitimately cheap run happens, and a row
+that fires on one of them is a row an operator learns to skip.
+
+Deliberately absent: any attempt to *estimate* the missing cost from turns or
+tokens. That would convert a known unknown into a confidently wrong number, on
+the one control whose job is to stop the fleet spending money.
+
 `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
@@ -1019,6 +1283,123 @@ honour the pattern it says so, and the daemon logs that per run:
 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.
 
+### Cap escalation (`workerEscalationModel`)
+
+A run that reaches a ceiling with no PR, no head and no salvage commit is
+classified `turn-cap-spinning` or `wall-clock-cap-spinning`, and normally that
+is a decomposition verdict: the slice was too big, and switching models would
+hide it. The cap classes are excluded from `modelFallbacks` for exactly that
+reason.
+
+`workerEscalationModel` buys one exception per issue, for the case where the
+slice was fine and the tier was not:
+
+```json
+"workerEscalationModel": "@slow"
+```
+
+It is an opaque selector like `workerModel` — a role, a pattern, whatever omp
+resolves — and conductor never interprets it. On the **first** artifact-free
+cap kill in an issue's run chain the settlement sweep records a one-shot marker
+and hands the queue label back — one store transaction, so a daemon that dies
+mid-recovery restarts into either "nothing happened" or "the continuation is
+owed", never a chain that reads as escalated with nothing queued — and the
+next dispatch launches on that selector; the page it sends says so instead of
+asking a human to requeue by hand. The run
+row records the selector it dispatched on (`model`) and, once the session
+settles, the model the harness actually resolved (`resolvedModel`).
+
+What it deliberately does not do:
+
+- **It never fires twice for one issue.** The marker is never removed, so a
+  restart cannot repeat it and a second cap follows the existing escalation
+  path — no climb to a third tier.
+- **It never fires for a `-progress` cap.** A cap kill with work to continue from
+  keeps decomposing.
+- **It is not a provider fallback.** `modelFallbacks` answers provider aborts,
+  credit refusals and capacity throttling, and still does: an escalated chain
+  fails over normally on top of its new primary, and a cap never advances or
+  resets the provider streak.
+
+Omit it and nothing changes: a spinning cap escalates to a human exactly as it
+did before, and the page says no escalation target is configured.
+
+### Required credential class (`requireOauthProviders`)
+
+On 2026-08-21 an Anthropic OAuth grant's refresh failed with `invalid_grant`. The
+exact selector `anthropic/claude-opus-5` still resolved — right provider, right
+model — through the *same provider's* API key, and one run spent an estimated
+$25.16 on billing nobody chose.
+
+That is documented harness behaviour, not a bug. `AuthStorage.getApiKey`
+resolves first-match-wins across runtime override → config override → stored
+OAuth → login-sourced API key → provider env var → other stored API key →
+fallback resolver, and **a model selector does not stop that cascade**. Nothing
+omp exposes can constrain it: `models.yml` `auth: "oauth"` only shapes the
+request, a provider-id variant like `xai-oauth` is a real provider that also
+accepts `XAI_API_KEY`, and there is no setting, env var, selector suffix or
+request option for it. So this is conductor's fence, not a config passthrough:
+
+```json
+"requireOauthProviders": ["anthropic", "openai-codex"]
+```
+
+**Declared per provider, never per model or per run.** A credential belongs to a
+provider — a model has none of its own — and a run's provider is not knowable in
+advance: `workerModel` is an opaque selector that may be a role alias, and the
+provider-fault fallback chain can move a live run onto another provider
+mid-flight. A per-run inference would be a guess dressed as a fact. So the
+declaration reads "this provider must bill to its subscription", and while that
+is untrue every candidate waits.
+
+It is checked at **three** points, and each closes a window the others cannot:
+
+- **Admission** holds every candidate with the `credential-class` reason, and the
+  hold's detail names the provider, what it resolves to instead, the disabled
+  cause (`invalid_grant` — the actionable half) and the remediation. Fleet-wide
+  like `plan-usage-cap`, and self-clearing: re-authenticate and the next pass
+  admits. Nothing pages, because a page for something an operator fixes in a
+  minute costs more attention than the guard saves.
+- **Before provisioning**, so a run that cannot launch never clones a mirror or
+  cuts a worktree.
+- **Immediately before the spawn**, which is the only one that closes the
+  admission-to-session window — a grant can be disabled in it. A run closed here
+  settles `stopped`, with the reason in its report, and **does not spend a failed
+  attempt**: the issue is not what is wrong, the host's credentials are, and
+  charging an attempt would exhaust an issue while the operator re-authenticates.
+
+The reader is a runnable probe (`src/credential-class.ts`) spawned per check with
+`--no-install`, exactly as `harness-loader.ts` asks the installed harness its own
+question. Out of process for two reasons: it keeps the harness's module graph and
+credential database out of the long-lived daemon, and every read is taken *now*
+rather than against a pool this process cached an hour ago. It calls the harness's
+own exported API — `getCredentialOrigin`, `listDisabledCredentials` — never a
+query against `agent.db`, and prints only an origin kind, an optional
+environment-variable *name* and disabled classes with their causes. There is
+nothing in that surface that could carry credential material.
+
+**This gate fails closed, and that is deliberate.** A probe that cannot answer —
+no harness, no `bun`, malformed output, an answer about a different provider —
+refuses, because "we could not check" costs exactly what "it is wrong" costs.
+That is the opposite posture from the lane interlock, which is inert without its
+probe.
+
+**The residue, which this does not fix and must not pretend to.** It is a state
+check, not an atomic guarantee. If OAuth becomes invalid *during* a request, the
+installed resolver still disables it and falls through to a same-provider API
+key, and nothing conductor can pass prevents that: there is no class constraint,
+and no after-the-fact answer either — `getApiKey` returns a bearer string with no
+class, assistant messages carry no credential field, and session `credential_pin`
+entries are OAuth-only *and* change-only, so neither a stale pin nor a missing one
+proves anything. A transcript audit of billing class would be a fabrication. The
+only hard lever is omp's own `disabledProviders`, which removes the provider
+before credential checks — and also removes the subscription route, which is why
+it stays an operator action. The real fix is upstream: an `AuthApiKeyOptions` that
+can require a credential class and refuse rather than descend.
+
+Omit it and nothing changes — no probe runs, and dispatch is byte-for-byte what
+it was.
+
 ## Omp settings overlay
 
 `ompSettings` on a project is the fleet-owned channel for saying "this project's
@@ -1333,6 +1714,18 @@ the command prints that held-notice id instead of claiming delivery — a
 not default to the marker. It is also not a report — it
 leaves no `reports` row, and nothing retries it.
 
+Every held notice also names the live path (#882). A hold reaches nobody now, so
+it is the wrong answer for somebody who is waiting: on 2026-08-21T20:48Z an
+interrupted tick fell back to this command and the operator's answer sat in the
+outbox until the 23:30 digest while they waited in the topic they had written in.
+The hold was correct policy and "nothing was sent" was already printed; what was
+missing is that `telegram_send` (or `telegram_ask` for a choice) reaches that
+person in their own topic right now. The line is conditional, because this
+command runs in a different process from the session and cannot know whether an
+inbound message is waiting — guessing would either nag every legitimate
+digest-only note or quietly bypass the availability policy on a hunch. The caller
+knows; one sentence makes holding a choice rather than a default.
+
 ### 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
@@ -1515,13 +1908,33 @@ omp-conductor watch list
 A watch is a row `kind: watch` that the orchestrator opened for itself — either
 a `--resolves-when` condition (the daemon checks it and wakes the next tick when
 met, exactly as for a question), or a plain carry note the next tick should
-read. It renders under its own "Watches" heading, is never offered to you to
-resolve, and has **no seven-day expiry** — that deadline is for a question
-nobody answered; silently expiring a watch could drop a release the day its
-condition finally fires. A superseded watch is closed with the ordinary
+read. It renders under its own "Watches" heading and is never offered to you to
+resolve. A superseded watch is closed with the ordinary
 `decision withdraw <id>`. `decision open --resolves-when` still records an
 operator question: a condition governs *when* to ask, not *who* answers.
 
+**The seven-day deadline starts when the condition fires, not when the watch was
+opened** (#966). While a watch is waiting — an unfired condition, or no condition
+at all — it never expires, because that deadline is for a question nobody
+answered and silently dropping a watch could lose a release the day its condition
+finally fires. The moment `conditionMetAt` is stamped the row stops waiting: it
+is an actionable item, which is exactly what the question deadline bounds, so it
+gets the ordinary window measured from that instant and closes itself if nobody
+acts.
+
+Measured on this fleet 2026-08-23, which is why: three watches had carried
+`[CONDITION MET — act on this now]` for 10–12 hours over work that was entirely
+closed (#809 and #888 closed, `omp-conductor@0.18.2` published *and* installed),
+and would have carried it forever. The codebase already names that cost for
+install surfaces — *a warning repeated every fifteen minutes trains an operator
+to ignore the row that matters* — and a permanent "act on this now" is that,
+aimed at the orchestrator's own attention.
+
+Two details keep it honest. Re-observing an already-met condition is refused, so
+the deadline cannot be pushed out on every pass. And clearing a met condition —
+which `pr-checks-green` and `pr-review-ready` do when the head moves (#808) —
+restores `never`: a PR that went red again is waiting, not ignored.
+
 ## Failure classes and recovery by class (#132)
 
 Every run that did not reach a merged PR used to end at a human. The
@@ -1593,11 +2006,57 @@ 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.
 
+### Grooming verdicts are reconciled too (#964)
+
+Same reasoning, one surface over. A verdict describes an **open** issue —
+`promotable` means "promote this" — and nothing retired one when its issue
+closed. `reconcileGrooming` clears only the two per-pass admission holds
+(`file-lane`, `depends-on`), which are correctly self-clearing; every other row
+was written once and never removed.
+
+Measured on this fleet 2026-08-23: **64 of 65 rows named a closed issue, and all
+26 `promotable` ones did**, so `status` advertised 26 candidates ready to promote
+on a repo whose only open issue was blocked on an operator. The tick prompt said
+"Promote the promotable or groom new issues" over the same rows.
+
+Each pass now retires every row whose issue is absent from a complete
+`listOpenIssues` snapshot. Three properties make that safe rather than
+destructive:
+
+- **A complete snapshot, never a filtered one.** `listOpenIssues` paginates to
+  the end and is conditional (an unchanged repo costs a 304). Reconciling against
+  `listReady` or `listLabeled` would condemn every verdict the filter did not
+  mention — and a promotable issue carries no label at all, which is also why
+  this cannot live inside the label reconcile above.
+- **Fail closed.** An unreadable tracker retires nothing and logs why. An
+  unreadable tracker and "no issues are open" look identical, and acting on the
+  second the first time GitHub rate-limits a pass would empty the table.
+- **Silent when nothing changed.** A line every fifteen minutes saying "0
+  retired" is a line nobody reads.
+
+Note what was *not* broken: candidate selection already built its pool from a
+live open-issue snapshot (#848) and used grooming rows only as exclusions, so a
+closed issue was never offered to a to-spec batch. The rot was in what the
+surfaces reported, and — latently — in `claimable = routed − knownBlocked`, which
+is arithmetic over the one subset that *was* being reconciled.
+
 ### 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.
+- `omp-conductor status` grows up to two blocks, and they answer different
+  questions. **`failure classes (awaiting recovery)`** counts rows whose
+  recovery has not run *and* whose action the sweep will actually take; it is
+  omitted when empty, because empty is the healthy answer. **`failure classes
+  (classified, no action by design)`** counts the two recorded-only actions,
+  `none` and `hold` — a `hold` waits on a human by design, and `none` is what
+  the settle sweep writes beside `returned-for-revision` when a reviewer closes
+  pushed work without merging, where the remedy is the queue label the sweep
+  deliberately leaves on rather than anything a sweep does.
+
+  They were one list until it grew a monotonically increasing tally: on this
+  fleet `returned-for-revision` reached **44** while every actionable class sat
+  at zero and invisible beneath it. That is the #109 defect one level up — a row
+  state is not an issue state, and a count nobody can act on is not a backlog.
+  Classes rather than row states, for the same original reason.
 - 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
@@ -1927,16 +2386,41 @@ 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.
 
+Read from `VERB_SPECS` on 2026-08-23. This table had drifted twice — `label
+change` was missing `completed`, and `pr review` was absent altogether — which is
+the ordinary hazard of writing a closed set down in two places. The refusal names
+the live set, and is the authority when they disagree.
+
 | 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` |
+| label change | `promoted-to-queue`, `re-briefed`, `completed`, `needs-human`, `duplicate`, `superseded`, `out-of-scope` |
+| pr review | `blocking-findings` |
 
 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.
 
+**And the refusal says so** (#968), because for a long time it did not. An
+out-of-enum `reason` was refused with the field, every accepted value and the
+rejected text quoted back — everything except where to put the sentence. Measured
+on this fleet 2026-08-23, `reason-not-in-enum` was the **largest single refusal
+cause in the ledger**: 99 of 241, across all four closed-set verbs, over 7.6
+days. Every one of the 99 carried real audit content — *"landed directly in PR
+#940; queue label would re-dispatch finished work"* — and **none supplied
+`rationale`**, because the moment a caller has a sentence to record is the moment
+they are told only that `reason` is closed. 7578 characters of accounting were
+refused and discarded.
+
+So the refusal now ends: *Pick the enum value that fits and put that sentence in
+`"rationale"`, which is logged verbatim.* It is keyed on the verb's own spec, not
+a hardcoded list — advising a field the verb would then refuse as
+`unknown-argument` turns one wasted round trip into two — and it is offered only
+for `reason`, never for another enum argument like `action`, where prose was
+never the intent. A test pins the invariant that makes the advice always
+available: every verb with a closed `reason` set also declares `rationale`.
+
 ## Orchestrator tick
 
 The escalation path above assumes an orchestrator session that is actually
@@ -2007,6 +2491,41 @@ 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.
 
+#### The spec-out questionnaire (#947)
+
+Decomposing a big issue needs several judgement calls about **one** issue, and
+asking them one at a time is what left #291's two — *is a Gitea fleet actually
+wanted*, *refuse-and-document versus emulate epic links* — as prose in an issue
+body that nothing tracked. `conductor_questionnaire` asks them together:
+
+- `spec-issue` names the issue being specced, and every item's decision row
+  carries it. That binding is the point: the answers become that issue's
+  provenance, so the next reader sees why a slice is shaped the way it is
+  instead of re-litigating it. A group without one is refused.
+- `items` are ordinary bounded asks — the same schema, composed rather than
+  restated, so an item can never accept something `conductor_ask` refuses. At
+  most six, and an item that fails validation (including the question-shape
+  ceiling) refuses the **whole group** rather than delivering a question set the
+  rows behind it do not match.
+- Every row is written in **one transaction, before the single delivery**, so an
+  operator is never shown a question nothing is waiting on.
+- **One delivery, N decisions.** The items go out as a single numbered message,
+  answerable in any order, and each resolves independently: answering item 2
+  leaves item 1 open. The group is bounded by the same ask ceiling — a
+  questionnaire never waits longer than one `conductor_ask` may.
+- At the ceiling each unanswered item takes its **own** declared `on-timeout`:
+  `auto-proceed` resolves with `"<option> (auto-applied on ask timeout)"`,
+  `park` stays open. An item the operator answered keeps that answer — the group
+  never resolves atomically, because that would discard the answers they gave.
+- This path is deliberately plain text rather than six button posts, since six
+  posts is exactly what it exists not to do. So a prose reply is not itself a row
+  resolution — the same contract a degraded single ask has — and the result names
+  each row id plus `omp-conductor decision resolve <id> --answer "…"`.
+
+Both surfaces are mounted and unmounted together: a beat that cannot route one
+cannot route the other, and a half-present ask surface would leave a model
+choosing between a working tool and a broken one.
+
 #### Upgrading from one shared arm marker
 
 Before per-project markers every project was given the same `<state dir>/armed`,
@@ -2256,14 +2775,14 @@ least of all on a fleet whose session lives somewhere else.
 ## CLI reference
 
 ```bash
-omp-conductor setup [area] [--no-ai] [--answers FILE] [--save-answers FILE] [--project NAME]
+omp-conductor setup [area] [--no-ai] [--answers FILE] [--save-answers FILE] [--resume FILE] [--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 [--to VERSION] [--bootstrap SHA --source PATH] [--project NAME]
 omp-conductor upgrade-install --to VERSION [--project NAME]
 omp-conductor upgrade-rollback
 omp-conductor status [--project NAME] [--json]
@@ -2305,13 +2824,13 @@ omp-conductor help
 | Command | Scope | Behaviour |
 | --- | --- | --- |
 | `setup [area] [--no-ai] [--answers FILE] [--save-answers FILE] [--project NAME]` | project | The deterministic interview, with styled Clack prompts on an interactive TTY and byte-stable plain output for pipes or `OMP_CONDUCTOR_PLAIN_UI=1`. `--answers` validates a JSON object of stable prompt keys before setup and replaces every prompt; a missing required key exits `1` naming the key and file instead of hanging. `--save-answers` records accepted interactive answers as replayable JSON after a successful run. Bare setup 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 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. On a herdr host the last step is `systemctl restart herdr-fleet.service`, which kills every pane in that session — so an invocation from *inside* it is refused before the plan is staged or a single step runs, naming the unit and a context the restart cannot reach (a login shell outside herdr, or a detached `systemd-run` unit). The hazard is the reason, not the herdr host: a plan with no such restart step — a non-herdr host, or a no-op re-run — installs normally from a pane, and `upgrade` has refused the same context since #486 (#834). It also decides who owns the fleet Herdr session before it mutates anything (#893): systemd cannot adopt an already-running process, so an unmanaged `herdr --session <name> server` holding the session makes every start of the unit exit 1 — and because the unit is `Type=simple`, `systemctl restart` returns 0 before the child discovers that. An unmanaged session is therefore stopped inside the same confirmed batch (unprivileged, before the unit install) so the unit can take it over, and a fact that cannot be read is refused rather than guessed — the remedy stops somebody's live session. Success is then proven rather than assumed: a bounded readiness gate re-reads until the unit is `active (running)` with a main pid AND the session answers, so an auto-restart loop is a failed setup. That failure leaves dispatch **paused** (unlike an ordinary failed step, which restores it) and names what it saw: a fleet nobody supervises must not admit workers. |
 | `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); stage this project's `cbm-reindex-<project>.{sh,service,timer}` **after** the confirm — never before, so a declined run leaves the staged tree byte-identical — refusing a stem that already belongs to another project or to a file it did not generate (#720); `git clone` each missing index-only checkout **as you, never through sudo**; install and enable `cbm-reindex-<project>.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] [--json]` | 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. `--json` emits the stable structured snapshot directly, without ANSI or prose, for automation. The text 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. |
+| `upgrade [--to VERSION] [--bootstrap SHA --source PATH] [--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. **`--bootstrap SHA --source PATH`** is the second accepted identity kind (#908), for the case a published version cannot express: the installed conductor is what is broken, and publishing the fix needs the workers that are broken. The sha is the whole identity (40 hex, never a range); `--source` is a checkout that must be AT that sha — verified with `git rev-parse HEAD` — and its only job is to be the tree `bun run check` runs against before anything is installed. A wrong sha, an unreadable tree, or a failing check **refuses**, naming the identity and what failed, with nothing installed. Otherwise it is the same transaction: the same journal (with the checks recorded as evidence), the same three surfaces from that one identity, the same attestation, the same rollback. The `--to` and `--bootstrap` identities are mutually exclusive. |
+| `status [--project NAME] [--json]` | 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. `--json` emits the stable structured snapshot directly, without ANSI or prose, for automation. The text 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. The `dispatch` line judges a **fence's owning process** when it has one (#938): a `setup` transaction records `owner=<pid>` in its sentinel, because its fence lives exactly as long as that process — so a killed setup renders `ABANDONED — its process (pid N) is gone` with the one command that clears it, while a live one renders `held by a live process`. An operator `hold`, and the durable hold a failed apply leaves behind, record no owner at all and are never described that way, whatever their age. Nothing here clears anything: a pid is reusable, a paused fleet is the safe state, and `doctor` carries the same verdict as a `dispatch-fence:<project>` warning. |
 | `ledger [--issue N] [--limit N] [--json]` | 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. `--json` emits one stable object with `project`, optional `issue`, `entries`, `refused`, and `turnOverrides`. 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). |
@@ -2323,15 +2842,16 @@ omp-conductor help
 | `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`), recover a settled run's missing PR (`conductor_pr_recover`), 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…
+| `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. |
+| `release-composition declare --campaign ID [--pr URL ...] [--reason TEXT]` · `override --pr URL [--reason TEXT]` · `complete|cancel [--reason TEXT]` · `status` | project | Declare the project's one active release (campaign + exact PR URLs), admit exactly one extra PR by recorded override, retire the guard, or inspect it. While a release is active, `conductor_pr_merge` refuses every other PR with `outside-active-release` — the [active release composition](#the-active-release-composition-850) guard — and the refusal clears only through this lifecycle, never through a merge reason. Every transition survives restarts and is recorded as an immutable material event. |
+| `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`), recover a settled run's missing PR (`conductor_pr_recover`), clear the review evidence standing at one exact head (`conductor_pr_review_clear`), 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…
 | `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 [--json]` | project | Open questions, oldest first: id, age, what each blocks, whether its condition is met, and the question. `--json` emits `{ project, decisions }`; the empty state is an empty array. Prints `no open decisions` in text mode when there are none. Watches are not listed here — `watch list` shows those. |
-| `watch add --note TEXT [--blocks TEXT] [--resolves-when COND]` | project | Record a condition or carry note the orchestrator set for itself, with no human in the loop (#459). `--resolves-when` attaches a machine-checkable condition the daemon checks for you; a met watch wakes the next tick exactly as a met question does. Renders under its own "Watches" heading, is never counted in `decisions N open`, and has no seven-day expiry. |
+| `watch add --note TEXT [--blocks TEXT] [--resolves-when COND]` | project | Record a condition or carry note the orchestrator set for itself, with no human in the loop (#459). `--resolves-when` attaches a machine-checkable condition the daemon checks for you; a met watch wakes the next tick exactly as a met question does. Renders under its own "Watches" heading, is never counted in `decisions N open`, and never expires while it is *waiting* — once a condition fires, the ordinary seven-day window runs from that instant (#966). |
 | `watch list [--json]` | project | Open watches, oldest first: id, age, what each blocks, whether its condition is met, and the note. `--json` emits `{ project, watches }`; the empty state is an empty array. Prints `no watches` in text mode 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. |
@@ -2519,6 +3039,20 @@ 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.
 
+**One attempt at this shipped and was withdrawn — read it before rebuilding it.**
+0.18.1 created an `omp-worker` account, launched sessions under it with
+`setpriv`, projected the operator's agent config to it by ACL, and bind-mounted
+the operator's `node_modules` read-only so the worker could resolve the harness.
+Every admitted worker then died before its first turn, one resolution layer at a
+time: config ACLs, a missing `zod`/`yaml`, a native addon looked up through a
+different per-UID Bun cache, package-export failures out of the bound tree. The
+lesson is not "fix the mount": exposing package *files* to another uid is not the
+same as giving it a runnable runtime. The rollback (#892) restored the
+fleet-account launch, and `setup host`/`upgrade` now retire that host state
+wherever it still exists. A next attempt needs an immutable self-contained worker
+runtime (a compiled binary or a package image), a real end-to-end session
+preflight before the switch, and atomic rollback — not a narrower ACL.
+
 ### The orchestrator is unconfined, deliberately
 
 There is **no mechanical file gate on the orchestrator session**, and that is an
@@ -2559,11 +3093,12 @@ daemon, across a process boundary, not in a prompt the model can rewrite.
 | --- | --- | --- |
 | `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_review` | **orchestrator only** | The PR is one a run of this project opened; the run is in a revisable settled state (`pushed-green`, or `failed`/`killed` after pushing green); the live head still equals the reviewed head and the checks at it are green; no review revision is already in flight; the review-round ceiling has not been reached. |
-| `conductor_pr_recover` | **orchestrator only** | The target issue has a recorded terminal run whose branch still exists at its exact recorded 40-hex head; the run is not live and not merged; the issue is open; no open PR already closes the issue at that head, and a recorded PR is open (returned), closed/merged (refused), definitively missing (replaced) or unreadable (retryable). Creates the one missing PR from that branch to the configured `defaultBranch` and records it on the run. |
+| `conductor_pr_review` | **orchestrator only** | The PR is one a run of this project opened; the run is in a revisable settled state (`pushed-green`, or `failed`/`killed` after pushing green); the live head still equals the reviewed head and the checks at it are green; no review revision is already in flight. At the review-round ceiling it no longer refuses: it admits one [final adjudication](#the-review-ceiling-adjudication-lifecycle-874) for that exact head under the project's `review.adjudicator` role, idempotently, without consuming a worker round (#932). |
+| `conductor_pr_review_clear` | **orchestrator only** | The PR is one a run of this project recorded (a `pushed-green` run is the normal case, so revisability is deliberately *not* required); `headSha` equals the live head; something actually blocks the merge at that head; `reason` is non-empty. Green is not required — the merge gate re-checks it. Records an append-only clearance plus a material event, and the [exact-head review gate](#the-exact-head-review-gate-888) then stops refusing that head. |
+| `conductor_pr_recover` | **orchestrator only** | The target issue has a recorded terminal run whose branch still exists at its exact recorded 40-hex head; the run is not live and not merged; the issue is open; no open PR already closes the issue at that head, and a recorded PR is open (returned), closed/merged (refused), definitively missing (replaced) or unreadable (retryable). No live [mutation lease](#what-holds-a-lane-and-what-merely-owns-an-artifact) holds a file the preserved branch carries — an overlap refuses `recovery-lane-occupied`, and a lane that cannot be read refuses `recovery-lane-unprovable` rather than publishing on an unproven one (#925). Creates the one missing PR from that branch to the configured `defaultBranch` and records it on the run. |
 | `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_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, while the project has an [active release composition](#the-active-release-composition-850), the PR must be named in it or carry an explicit operator override; then `headSha` equals the live head *at execution time*; checks are green at that same SHA; no [review evidence](#the-exact-head-review-gate-888) stands at that head without a recorded `conductor_pr_review_clear`; 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. Adding the queue label echoes the parsed [file lane](#the-file-lane-declaration), or refuses with `file-lane-unparseable` when a clearly delimited write-lane section parsed nothing — it never claims fail-open beside a declaration that was actually attempted. |
 | `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. |
@@ -2584,6 +3119,216 @@ 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.
 
+#### The refusals reach `status`, not only `ledger` (#972)
+
+`status` closes with a bounded verb-ledger block — newest first, five entries,
+silent when nothing has been called:
+
+```
+verb ledger  20 recent call(s), 3 refused  (omp-conductor ledger for the rest)
+  2026-08-23 01:13:23  REFUSE  conductor_label   orchestrator  [reason-not-in-enum]
+```
+
+The header counts every row the snapshot carries (`STATUS_LEDGER_SCAN`, 20), not
+the five printed: a count computed from the visible rows would report "1
+refused" on a fleet that refused eleven things that morning.
+
+This is the surface an operator reads, and the refusal *class* is what they come
+for. It had never appeared there. The block was written for `status` in #133 —
+its own doc comment and both constants say so — but was wired into a second,
+unshipped copy of the status body in `daemon.ts`, which was already not the live
+renderer on the day it landed. So for a fortnight the snapshot performed a
+20-row read on every single `status` call and discarded the result, while the
+dead copy was kept alive by exactly one test.
+
+What that cost is measurable: #968 — an out-of-enum `reason` accounting for 41%
+of every refusal on this fleet — was found by querying the sqlite file by hand.
+A header reading `99 refused` would have surfaced it in the first week.
+
+### A review round is charged only when its worker worked (#903)
+
+The review-round ceiling bounds *polishing*, so it counts rounds a worker
+actually ran. A revision dispatch that dies before its resumed session takes a
+turn — a host permission fault, a spawn failure, a daemon shutdown between the
+claim and the launch — worked no round: the same row is returned to the pending
+set with its round number, findings and target session unchanged, the run goes
+back to the exact `pushed-green` state the review verb recorded, and the next
+dispatch pass resumes it. No label changes and nothing escalates, because
+nothing has failed that a human can act on.
+
+The discriminator is "did the resumed session take a turn", never the error
+text: during the 2026-08-21/22 worker-mount outage every dispatch died at turn
+zero on an `EACCES` no signature list contained, each death consumed one of the
+PR's three rounds, and the ceiling then refused any further round — an outage
+turned into a permanently unmergeable PR. Matching on errno would only wait for
+the next outage to spell itself differently.
+
+Retries are counted on the row itself, so they survive a restart, and they are
+bounded: after three the round settles `failed` exactly as it always did, the
+issue takes the failed label, and one escalation names it. A round whose worker
+took even one turn is charged normally, whatever it then did — that is what
+keeps the ceiling meaningful.
+
+### The exact-head review gate (#888)
+
+Green checks say nothing about the review lifecycle, so `conductor_pr_merge`
+also refuses — with `merge-blocked-by-review` — when durable review evidence
+stands at exactly the head being merged: a review round that is queued, one
+that was dispatched and crashed mid-review, or one that settled `failed`
+there. The evidence is keyed by project + PR + head, so a finding tied to an
+older head never poisons a corrected push.
+
+That leaves the question of how a head that will *not* be corrected ever
+merges — a PR at the review-round ceiling, or one whose findings a human read
+and dismissed. Re-reviewing the same head is not the answer and never was:
+`conductor_pr_review` at an unchanged head appends to the pending round or
+opens a new one, and both block. The answer is an explicit, recorded
+disposition:
+
+```bash
+omp-conductor verb conductor_pr_review_clear --project acme \
+  --arg prUrl=https://github.com/acme/api/pull/12 \
+  --arg headSha=<the live head> \
+  --arg reason="findings answered in review thread; ceiling reached"
+```
+
+Three properties make it a disposition rather than a blanket override, and all
+three are mechanical:
+
+- **It clears backwards only.** A clearance suppresses evidence whose own last
+  activity is at or before the moment it was taken. A round recorded *after*
+  it blocks the merge again — so a clearance cannot be banked as a standing
+  pass.
+- **It is head-scoped and non-vacuous.** It names the exact live head, and a
+  clearance at a head where nothing blocks is refused (`review-clearance-vacuous`).
+- **It bypasses nothing else.** Authority, pause, base-red-freeze, exact-head,
+  green checks, the migration chain, the active release composition and
+  single-flight all still apply to the merge that follows.
+
+Like the composition override, it is deliberately a separate verb: a merge
+call's own `reason` is not a clearance. Each clearance is an append-only row
+with its reason, a verb-ledger entry, and a material event in the digest.
+
+### The review-ceiling adjudication lifecycle (#874)
+
+A PR that reaches `review.maxRounds` has no worker rounds left, and returning it
+to the operator is what conductor exists to avoid. So the ceiling escalates the
+**automation**: `review.adjudicator` names an OMP model role (a role name, never
+a provider/model — OMP owns that selection), and a terminal adjudication decides
+the head with a stronger model.
+
+What exists today is the durable lifecycle underneath it. One adjudication is
+recorded per project + PR + **exact head**, and that uniqueness is a database
+index rather than a flag a caller remembers to check, so a repeated tick, two
+dispatchers and a daemon restart all re-read the same row instead of launching a
+second adjudicator. A live adjudication on the same PR at a *different* head is
+refused: the PR moved, and two live adjudications on one PR is exactly the
+duplicate this prevents.
+
+It is deliberately **not** a round in `review_revisions`. Reusing round N+1
+would spend a ceiling that is already exhausted, and would resume the same
+session and model for a nominal fourth opinion — the failure the escalation
+exists to end. The two tables also answer different questions: a revision says
+"go and change this", an adjudication says "decide about this".
+
+The terminal states **are** the verdict — `cleared`, `rejected`,
+`unavailable-model`, `stale-head`, `failed` — with no second verdict column to
+disagree with them. Stored beside the state is what it cannot say: the
+`evidence` that produced it, and the `disposition` applied because of it.
+`status` renders each one under its run as `adjudication <state>  role <asked>
+→ <model actually launched>`, matched on PR + head so a corrected push never
+appears to carry the older head's decision.
+
+**Reaching the ceiling now admits one instead of refusing.** `conductor_pr_review`
+at `maxRounds` used to refuse and tell the orchestrator to leave the PR open and
+escalate; it now records the adjudication for the head it just verified live and
+green, carrying the findings that provoked it — the most relevant single input the
+adjudicator gets. The ceiling on *worker* rounds is unchanged: no fourth revision
+is dispatched and no round is consumed. A repeated call at the same head is
+idempotent; a call whose head has moved has already refused (`head-stale`) before
+the admission, and one made while an adjudication is live at a different head
+refuses `review-in-flight`.
+
+**The daemon's own pass launches it**, next to review-revision dispatch and never
+inside it: a revision resumes an implementation worker to change code, an
+adjudication opens a fresh read-only session to decide about code, and folding
+them together is how "escalate the automation" quietly becomes "resume the same
+worker with a different label". The pass re-reads the live head first (a moved
+head settles `stale-head` without launching, an unreadable one stays pending for
+the next tick), claims `pending → running` — that transition is the single-flight
+guard — assembles the evidence from durable rows plus live tracker reads, and
+settles the row from the verdict:
+
+| Result | State |
+|---|---|
+| verdict `cleared` | `cleared` — the ordinary orchestrator-owned merge path |
+| verdict `rejected` | `rejected` — #876's autonomous disposition |
+| a verdict naming a different head | `stale-head`, fail-closed |
+| no verdict, zero turns | `unavailable-model` — the role never launched; a configuration fault |
+| no verdict, turns spent | `failed` |
+
+An adjudication occupies no worker slot and no issue, charges no failed attempt
+and no continuation, and its turn ceiling (`ADJUDICATION_MAX_TURNS`) is
+deliberately small: a verdict is a read and an answer, not an implementation. A
+daemon restart settles a `running` adjudication `failed` — its session died with
+the process, an adjudicator has no branch or transcript worth resuming, and
+re-queueing it would be a second launch for one head.
+
+**The verdict is then acted on** (#876), in its own pass, because a verdict and
+what was done about it are two facts:
+
+- **`cleared`** records a [`conductor_pr_review_clear`](#the-exact-head-review-gate-888)
+  at that exact head, by `adjudication:<role>`. That is the whole mechanism — the
+  merge gate already reads clearances, so there is no adjudication-shaped
+  exception inside `conductor_pr_merge` and one audit trail covers both. The head
+  is re-read first: if it moved, no clearance is recorded and the row says so.
+- **Every other terminal state** — `rejected`, `failed`, `unavailable-model`,
+  `stale-head` — closes the pull request, having first posted the adjudicator's
+  reasons and every preserved review finding on it. They all mean "this head is
+  not merging and no further round is coming", and the blocking artefact is the
+  same in each case: an open PR occupying the issue. The branch is untouched.
+
+Nothing here opens a review round, launches a second adjudicator, or asks an
+operator for anything. No budget is reset either: the closed PR is charged by the
+ordinary settle sweep exactly as any PR closed without merging, which is what
+lets this compose with a separate corrective-worker path instead of resetting its
+counters.
+
+The recorded `disposition` is the idempotency key — a row that already has one is
+skipped, so a restart or a retried tick cannot close one PR twice — and it is
+written only *after* the act succeeds, so a failed close leaves the row
+undisposed and retryable rather than claiming work it did not do. As a backstop,
+`conductor_pr_merge` refuses any head whose adjudication settled anything other
+than `cleared`, in case a close failed or raced.
+
+### The active release composition (#850)
+
+An early patch is only trustworthy while nothing unrelated slips into it, so a
+project can declare **one active release composition**: a campaign identifier
+(say `v0.18.1-reliability`) plus the full PR URLs allowed into that release.
+While one is active, `conductor_pr_merge` refuses every other PR with the
+`outside-active-release` refusal naming the campaign and the conflicting PR —
+checked before the merge lock and any tracker call, from SQLite rows that
+survive daemon restarts, so the guard is mechanical rather than a policy
+sentence or a status warning.
+
+The guard moves only through the explicit operator lifecycle:
+
+```bash
+omp-conductor release-composition declare --campaign v0.18.1-reliability \
+  --pr https://github.com/acme/api/pull/12        # open the release
+omp-conductor release-composition override --pr https://github.com/acme/api/pull/13 \
+  --reason "hotfix belongs in this patch"          # admit exactly one extra PR
+omp-conductor release-composition complete        # or cancel — retires the guard
+```
+
+A merge call's free-form `reason` is never an override, and an override bypasses
+only the composition check: authority, pause, base-red-freeze, review, exact-head,
+green-checks and single-flight all still apply to the admitted merge. Every
+transition writes an immutable material event, overrides stay in the audit trail
+scoped to their campaign, and merging a member PR never retires the composition —
+only `complete` or `cancel` does.
+
 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
@@ -2607,6 +3352,31 @@ 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.
 
+**Pinning a tag to one commit (#695).** Both tag shapes accept
+`--arg sha=<commit>`, and it removes the dependence on *when* the tag is cut.
+Without it the target is whatever the default branch is at cut time, which
+deadlocks any fleet whose queue is not empty: cutting needs a window with no
+unsettled run, reaching that window needs the open PR merged, and merging moves
+the branch past the tag that was just cut — leaving it unpushable (behind main),
+un-re-cuttable (a tag the tool cut is never force-moved) and with no shape able
+to clean it up. The 2026-08-18 occurrence burned a version number.
+
+With a pinned commit:
+
+- `git-tag` cuts at exactly that commit, and the "behind live main" refusal does
+  not apply — being behind is the point;
+- `git-push-tags` publishes that tag **unchanged**, instead of re-pointing it to
+  the live branch head as an unpinned push does. A local tag standing somewhere
+  other than the pinned commit is a refusal, never a silent move;
+- a commit the released repository does not have, or one **not reachable from
+  the released branch**, is refused naming the sha: a tag pointing off-branch is
+  a release of code nobody merged;
+- omitting `sha` leaves every existing behaviour exactly as it was, and the
+  argument is refused on any shape that cuts no tag rather than being ignored.
+
+Deliberately not fixed here: the `runs-settled` precondition's scope (see #603,
+already repo-scoped) and any tag-delete or re-cut shape.
+
 ### The transport
 
 Identity is never an argument. `project`, `run`, `issue` and the caller's role
@@ -2775,16 +3545,81 @@ Known and deliberate in this version:
   re-derived, not forgotten), and one closing notice lands when the orchestrator
   recovers. What remains a separate watchdog is the `.conductor-stalled` wedge
   path, for a session that stays alive but stops draining its queue.
-- **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`.
+- **A worker gets a Herdr pane, but the pane is never the worker (#840).** Each
+  worker is an omp session the daemon starts as a child process, and that child
+  stays the authoritative one: the typed control socket, the mediated verb
+  socket, the worktree, the transcript, the accounting and the output-schema
+  settlement are all its. What the workspace shows is a *representation* of that
+  exact child — a pane named `worker-<project>-<issue>-a<attempt>-<run>`, created
+  at spawn from the pid the spawn path itself reports, and reported to Herdr
+  through its external-supervisor verbs (`pane report-agent-session` for the run
+  and transcript identity, `pane report-agent` for `working`/`idle`/`blocked`,
+  `pane release-agent` when the child is gone).
+
+  Nothing starts a second OMP process, and nothing reads the pane back: no run
+  state, settlement, turn, spend or model fact is ever derived from terminal
+  output. The pane displays `omp-conductor tail`, the existing read-only
+  follower. Input cannot reach the session either, and that is structural rather
+  than a check — the authoritative child is spawned with `stdin: "ignore"`, so
+  there is no descriptor for a keystroke to travel down, and the pane's own
+  process is a follower whose stdin reaches only itself.
+
+  **The identity is durable, so the workspace survives the process (#842).** The
+  pid, pane id and label are written onto the run row the moment the pane is
+  established — before it is announced, because a pane the store does not know
+  about is a pane a restart cannot reconcile. Three consequences follow, and each
+  is the answer to a way the pre-#842 representation went wrong:
+
+  - **A re-entered launch adopts, never duplicates.** A run that already carries a
+    pane identity is re-reported against that pane; only a run with none creates
+    one. Two panes claiming one worker is worse than none, because both look real.
+  - **A restart releases what it inherits.** The startup orphan sweep hands the
+    pane of every reaped run back to Herdr (`releaseOrphanedWorkerPane`), so a
+    workspace never shows a live worker for a child that died with the previous
+    daemon. The recorded pid is deliberately *not* consulted for liveness: a
+    `session-host` child dies with the daemon that owned its verb socket, so the
+    worker is gone whatever the pid says — and pids are reused, so probing one is
+    exactly how a stranger's process comes to read as a live worker.
+  - **State is projected from transitions, never scraped.** Pause and resume reach
+    the pane through the control registry's own `onPhase` notifier — the phase the
+    control actually reached, fired only on success, so a refused pause never
+    shows as `idle`. A cap kill reports `unknown`. Each report carries the run's
+    own monotonic `seq`, so a late report cannot overwrite a newer state.
+
+  **Herdr unavailability is a named state, and retention is finite (#841).** A
+  worker with no pane keeps working — visibility is never a precondition — but it
+  never does so quietly: the reason is written to its run row and `omp-conductor
+  status` prints `pane   degraded — <reason>` on that run's own line, so a fleet
+  running blind cannot be mistaken for a fleet with nothing to show. Every
+  dispatch pass then reconciles the workspace against the live run set
+  (`reconcileWorkerPanes`), which is what makes the surface survive a *Herdr*
+  restart — an event conductor is never told about:
+
+  - A live run whose pane Herdr still has is left alone (`intact`), so repeated
+    passes converge instead of churning panes.
+  - A live run whose pane Herdr lost is re-associated: one new pane, for the pid
+    already on the row. No second OMP process is started, ever. A run with no
+    recorded pid stays `untracked` rather than getting a pane with nothing behind
+    it.
+  - A conductor-owned pane whose run id is not live is released — the retention
+    bound: a settled worker's pane is conductor's only until the next pass. It is
+    matched by the run id Herdr itself reports, never by label or age, so a live
+    worker's pane can never be cleaned up and a stale lookalike can never be
+    mistaken for one. Release, never close: nothing here can terminate a live
+    authoritative worker, because the only mutation is handing lifecycle
+    authority back.
+  - An unreadable or absent Herdr reconciles nothing and says so on every pass.
+    Failing to read the workspace is not evidence that a worker's pane is stale.
+
+  Fleet recovery knows the difference too: `herdr/bin/recover.sh` excludes any
+  pane carrying the `omp-conductor` source from its resume candidates, so a
+  released worker pane — which has no agent and sits in the fleet cwd, and so
+  looks free to every other check — is never where the orchestrator gets started.
+
+  The cap still does the 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. `omp-conductor
+  status` remains the authoritative list of occupied issues.
 - **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