omp-conductor 0.17.1 → 0.18.1

package/README.md

@@ -271,6 +271,40 @@ The Herdr half owns recovery, not dispatch or policy: it restores the exact
 session identity, requests an immediate heartbeat, or reports through Telegram
 and a Herdr notification that the fleet is down.
 
+### The worker identity and its harness binding
+
+Worker sessions do not run as you. `setup host` creates a dedicated
+unprivileged account, `omp-worker` (home `/var/lib/omp-worker`), and the daemon
+launches every worker session under it through `setpriv`. The account is granted
+search access to the paths a session needs and read access to your agent config
+files; its writable world is the worktree and session directory dispatch hands
+it per run, and nothing else.
+
+That boundary means the account cannot list your home — which is also where
+`omp-conductor` and its `@oh-my-pi/pi-coding-agent` peer are installed, and
+module resolution needs to list a directory to find the `node_modules` inside
+it. Left there, a worker silently resolved a *different* harness version out of
+its own package cache. So `setup host` also installs one mount unit,
+`var-lib-omp\x2dworker\x2dharness-node_modules.mount`, binding your install
+read-only at `/var/lib/omp-worker-harness/node_modules`, and launches worker
+children from that path. It is a bind, not a copy: upgrade the harness and every
+worker picks it up with nothing to re-materialise. The mount's parent directory
+is `root:omp-worker` `0750`, so the bound tree is reachable by root and the
+worker account and by no other local account.
+
+Three consequences worth knowing:
+
+- `omp-conductor` must be installed, not run from a source checkout, for worker
+  dispatch to work — a checkout has no install root to bind.
+- If the binding is missing or no longer resolves to your install, the daemon
+  refuses to launch workers and says so (`setup host` reports the same thing as
+  pending work). Re-run `omp-conductor setup host`; no attempt is charged to the
+  issue, because no session ever started.
+- The check runs at every launch, not once at daemon startup. The mount unit is
+  ordered before the daemon, so a reboot brings them up in the right order — and
+  if the binding ever arrives late anyway, the next dispatch picks it up with no
+  restart needed.
+
 ### Stop the conductor (hold / stop)
 
 Two words, and one of them takes a flag:

package/REFERENCE.md

@@ -763,6 +763,40 @@ or `/`) is `bug`, and `feat` otherwise. The slug is the issue title folded to
 issue alone, so a retried run recomputes the same branch and finds its own work
 instead of forking a second one.
 
+### The file-lane declaration
+
+Two workers writing the same file clobber each other, so admission holds a
+candidate whose declared lane overlaps a live run's actual lane (`file-lane`
+hold). The declaration is read from the issue body or a pre-dispatch comment —
+the two surfaces the worker brief renders — through one grammar, so the lane the
+gate enforces and the lane the promotion echo reports are always the same parse:
+
+- **Inline line** (the brief form since #555): a line beginning with `File
+  lane:` or `File-lane=` (case-insensitive, tolerating heading/list markers)
+  whose rest carries the paths, backtick-delimited, with a bare
+  comma/space-separated fallback for tokens that look like relative paths:
+  `**File lane:** `omp/src/a.ts`, `omp/src/b.ts` are yours — nothing else holds
+  them.`
+- **Write-lane section** (the package-floor decomposition form, #825): a
+  markdown heading `## Exact write lane` (or `## Write lane` /
+  `## write-lane`) whose immediately following bullet items carry one
+  backticked path each — `- `omp/src/types.ts` — why it changes`. Only the
+  contiguous bullet run under that heading is read: a following paragraph
+  (like a `Read only:` caveat) or the next section ends it, so read-only
+  entry points, proof commands and acceptance bullets elsewhere in the issue
+  are never captured as write files.
+
+When both are present, the inline line wins — it has held since #555, and the
+promotion echo shows exactly which declaration admission enforces. Across
+surfaces, the latest declaration among the body and the whole comment thread
+supersedes (a pre-dispatch correction comment replaces the body's lane). A body
+or thread with no declaration admits exactly as before: `fail open`, and the
+label response says `no lane declared (fail open)`. A clearly delimited
+write-lane section that parsed nothing is **not** an absent declaration: adding
+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.
+
 ## Routing
 
 An issue must carry **exactly one** `repo:<name>` label naming a repo in
@@ -1078,11 +1112,15 @@ omp-conductor setup graph --print     # print the plan: clones, index commands,
 omp-conductor setup graph             # run it: clone, install, enable, seed, verify
 ```
 
-`setup graph --print` prints a `git clone` for every clone that does not exist yet, the
-one-shot index command per repo, and a `cbm-reindex.service` + `cbm-reindex.timer`
-pair built from the project's own repos and branches. `--write` stages all three
-in the state directory and prints the two `sudo` lines that install and enable
-them; it never runs `systemctl`.
+`setup graph --print` prints the plan: the host prerequisites, a `git clone` for
+every clone that does not exist yet, the one-shot index command per repo, and
+this project's `cbm-reindex-<project>.sh` script plus `cbm-reindex-<project>.service`
++ `cbm-reindex-<project>.timer` unit pair, named for the project so a second
+project on the same host gets its own refresh instead of silently replacing the
+first project's (#720). A run stages those three files in the state directory
+**only after its consent prompt** — declining leaves the staged tree
+byte-identical — then clones, installs and enables the timer as root, seeds one
+indexing run, and verifies; it never runs `systemctl` on its own authority.
 
 **Run it as the account the fleet runs as, never under `sudo`** — it refuses if
 you try. Everything it derives resolves per-account: the config it loads, the
@@ -1416,7 +1454,7 @@ conditions, each one something this package can check without asking you:
 | Condition | Met when |
 | --- | --- |
 | `pr-merged:<https url>` | `gh` reports that pull request merged. |
-| `pr-checks-green:<https url>` | Every check on that pull request has a green verdict (a non-empty list, all `success`/`neutral`); a failing or still-pending check is not met. |
+| `pr-checks-green:<https url>` | Every check on that pull request has a green verdict (a non-empty list, all `success`/`neutral`); a failing or still-pending check is not met. The verdict is bound to the exact PR head it was observed at: if the head changes, the row returns to pending until the new head's own checks are green (#808). |
 | `pr-mergeable:<https url>` | The pull request is mergeable (`clean`, not `unknown` or conflicting). |
 | `issue-closed:<number>` | That issue is closed on the tracker. |
 | `npm-version:<pkg>@<version>` | `npm view <pkg>@<version> version` succeeds — the version is published. |
@@ -1430,10 +1468,11 @@ arm/channel/pending single-flight) instead of waiting a full interval. The poke
 reason and the digest flag `[CONDITION MET — act on this now]` both surface the
 wake so the session acts when the answer becomes actionable. Repeated sweeps
 while the condition stays true do nothing further — the store marks the
-transition once. After a green-but-behind PR is updated through
-`conductor_pr_update_branch`, open a fresh `pr-checks-green` watch on the new
-head so the next green transition can wake merge review the same way; nothing
-here merges on its own.
+transition once. A `pr-checks-green` watch survives a head change on its own:
+the binding is about the exact commit, so an updated branch drops the row back
+to pending and the new head's green transition wakes merge review the same way
+(`conductor_pr_update_branch` needs no fresh watch). Nothing here merges on its
+own.
 
 Anything else exits `2` and lists the six forms. An unparseable condition on an
 existing row is *listed and never treated as met*: a grammar a future release
@@ -1940,10 +1979,19 @@ injected tick the extension refuses it and mounts its own bounded surface,
 
 - The call carries `question`, `on-timeout` (`auto-proceed` or `park`, required),
   and optionally `timeoutSeconds`, `blocks`, `recommended`, `options` and
-  `category`.
+  `category`. `recommended` is required whenever `on-timeout` is `auto-proceed`
+  (the row must record what was auto-applied) and, when `options` are supplied,
+  must be one of their labels — the label as delivered, never an index.
 - The tool records a decision row first (durable, seven-day expiry), then
-  delivers the question through the same path `omp-conductor message` uses —
-  immediately when the reporting policy permits, durably held otherwise.
+  delivers the question. When the Telegram surface can (a bot token, a
+  configured escalation chat, a paired owner, and the reporting policy
+  permitting an interrupt), it posts the options as the same selectable
+  buttons `telegram_ask` posts and a tap resolves the decision row with the
+  chosen option's label. When it cannot, the question goes out as plain text
+  through the same path `omp-conductor message` uses — immediately when the
+  reporting policy permits, durably held otherwise — and the decision row
+  records the degraded delivery, so a prose reply is never treated as a
+  selection (resolve or withdraw the row by hand if the operator answers).
 - It waits at most the ceiling: `timeoutSeconds` if the ask names one, else the
   tick config's `askTimeoutSeconds`, else 300 seconds — always capped at the
   turn budget, so the ask can never outlive the turn it runs in. An ask issued
@@ -2223,6 +2271,9 @@ omp-conductor doctor [--project NAME] [--json] [--probe-telegram]
 omp-conductor ledger [--issue N] [--limit N] [--project NAME] [--json]
 omp-conductor board [--project NAME] [--json]
 omp-conductor hold [--keep-ticks] [--project NAME]
+omp-conductor drain start --until ISO|DURATION [--reason TEXT] [--project NAME]
+omp-conductor drain status [--project NAME]
+omp-conductor drain cancel [--project NAME]
 omp-conductor stop [--pane] [--project NAME]
 omp-conductor arm [--project NAME]
 omp-conductor disarm [--project NAME]
@@ -2255,7 +2306,7 @@ omp-conductor help
 | --- | --- | --- |
 | `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 graph [--no-seed] [--print] [--project NAME]` | project | The code-graph install end to end, in one preview and one confirm: check the prerequisites read-only and stop before installing anything when `codebase-memory-mcp` is absent or no MCP entry mounts it (printing the entry to add); `git clone` each missing index-only checkout **as you, never through sudo**; install and enable `cbm-reindex.timer` as root; then seed one indexing run so the first fetch happens while you watch, and verify with the same probe `status` uses. A repo that does not verify is a failure with the remediation, not a success — staged-but-not-trusted is how you discover months later that no worker read an index. `--no-seed` enables the timer without the seeding run and says plainly the graph is unusable until it first fires; it never skips the prerequisite or clone steps. `--print` changes nothing. Exits `1` when no repo has [`graphProject`](#configuration). |
+| `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). |
@@ -2264,6 +2315,7 @@ omp-conductor help
 | `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). |
+| `drain start --until ISO\|DURATION [--reason TEXT]` / `drain status` / `drain cancel` | project | Start, inspect, or cancel the project's self-expiring admission fence (#484): a durable, bounded alternative to queue-label churn before a release. `start` writes the project's drain record through the landed `createDrain` — new claims pause while active runs settle, and admission resumes automatically at the absolute deadline even if the orchestrator dies. A successful mediated `conductor_release` also clears the drain once the terminal release act completes — version-bump preparation stays latched until the tag is actually cut — so the release window ends with the release itself rather than latching until the deadline (#791). `--until` takes an ISO instant or a relative duration (`90s`, `45m`, `2h`, `1d`) that must be bounded and in the future; a missing, unparseable, unbounded, or past expiry exits `2` before any state changes. `--reason` (1–500 characters) is persisted on the record. `status` reports inactive, or the active drain's creation time, absolute expiry, reason, and remaining active runs from the structured status snapshot. `cancel` removes only the named project's drain and is idempotent. The drain never touches the pause sentinel, the arm marker, or any queue label — it is a file record, not a hold. |
 | `stop [--pane] [--project NAME]` | fleet | Stop the conductor: pause claiming, disarm ticks, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `stop --pane` also pins herdr-conductor recovery off for the conductor agent only — it does **not** stop `herdr-fleet.service` or any other herdr session. Fail-closed: exits nonzero unless the agent is proven gone. To bounce the daemon without stopping the fleet, use `restart`. |
 | `arm [--project NAME]` | fleet | Proof-gated: send a Telegram challenge and write this project's arm marker only after your reply appears as a user turn in the orchestrator transcript. The challenge names the project, so a host running two fleets is not ambiguous. Never auto-armed by `resume` / `hold`. |
 | `disarm [--project NAME]` | fleet | Remove this project's arm marker so its ticks skip; another project's ticks keep running. Also clears a pre-per-project shared `armed` marker while that marker is still what holds this fleet's gate open — otherwise the disarm would not disarm. Processes untouched. |
@@ -2272,7 +2324,7 @@ omp-conductor help
 | `worker pause <issue>` / `worker resume <issue>` | project | Cooperatively park one live worker without changing its run state or lane. Pause aborts the active turn to harness idle and freezes the remaining wall-clock budget; resume continues the same session with a prompt to re-check its last action before repeating it. This is separate from fleet-level `hold`, which refuses new claims and work-starting mutations while allowing pre-pause completion work and releases. |
 | `worker stop <issue> --reason TEXT [--project NAME]` | project | Terminally end a running or cooperatively paused worker. The reason is required (1–500 characters) and persisted on the run. The command waits for settlement, records the distinct `stopped` state, salvages and publishes dirty work, removes `agent:in-progress` through the durable label outbox, and consumes neither failed-attempt nor continuation budget. If salvage fails, the tree holding the only copy stays in place and the command names it. Repeating stop is idempotent and reports the run's already-terminal state. |
 | `unblock <issue> [--force] [--no-requeue]` | project | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again, and restore the project queue label by default so the dispatcher actually sees it. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label (and the queue label stays off until that run settles), and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. The label changes go through the [label projection outbox](#how-one-tick-works): they are applied inline before the command returns, but **a tracker that refuses them (403, rate limit) no longer fails the verb** — it exits `0`, the intended label state is durable and the daemon retries it, and the output says `label sync queued (N pending) — the daemon retries` instead of claiming the labels were restored. Safety is preserved, but the issue is only claimable once the queue label itself lands: the queue read asks GitHub for issues carrying that label, so a refused queue-label add keeps the issue out of dispatch until projection succeeds. `--no-requeue` clears the state labels only, leaving the queue label untouched — the case where you are about to close the issue. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
-| `verb <conductor_*> [--arg k=v ...]` | project | Run one [mediated verb](#the-mediated-verbs-126) as the orchestrator, from the CLI — the external-orchestrator half of the verb surface. Every argument goes in as a `--arg k=v` string; an orchestrator can merge (`conductor_pr_merge`), label (`conductor_label`), release (`conductor_release`), update a branch (`conductor_pr_update_branch`) or title/body (`conductor_pr_update`), or read PR state (`conductor_pr_status`). The daemon applies the same checks and writes the same ledger rows a session's call would; a missing `--arg` is refused exactly as a missing tool argument is, worker-only verbs (`conductor_push`, `conductor_pr_create`) are refused with `role-not-allowed`, and a refusal exits `3`. An unknown verb exits `2`. |
+| `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…
 | `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). |
@@ -2355,7 +2407,7 @@ curl -s localhost:8787/healthz
         "configured": true,
         "status": "degraded",
         "checkedAt": "2026-08-08T13:00:00.000Z",
-        "prerequisites": { "indexer": "present", "mcpMount": "missing" },
+        "prerequisites": { "indexer": "present", "mcpMount": "unconfigured" },
         "repos": [
           {
             "name": "api",
@@ -2507,10 +2559,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_status` | worker or orchestrator | Read-only — nothing to gate. A worker reads only its own run's PR; an orchestrator may name any syntactically valid PR URL, open, merged, or closed, and gets its live state and head (checks are reported when available; a merged or closed PR reports its state instead of an `expected OPEN` refusal). |
 | `conductor_pr_update_branch` | orchestrator, or the worker owning the run | The PR belongs to this project and is open. A worker may only name its own run's PR. |
 | `conductor_pr_merge` | **orchestrator only** | Ordinarily, `authority.merge` equals the caller. A hand-edited `recoveryMerges` entry may instead authorize one exact unrecorded PR/head/reason while held. In both paths, `headSha` equals the live head *at execution time*; checks are green at that same SHA; the project route and migration chain are valid; the project's single merge slot is free. |
-| `conductor_label` | **orchestrator only** | The label is in the project's own vocabulary. Lifecycle labels stay the daemon's. |
+| `conductor_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. |
 

package/agents/to-spec.md

@@ -0,0 +1,90 @@
+---
+name: to-spec
+description: Groom exactly ONE backlog candidate into a strict, source-verified to-spec verdict. Read-only: reads the candidate and the authoritative source, returns one fenced JSON block matching the to-spec schema. NEVER use for implementation or edits.
+tools: read, grep, glob, web_search
+read-summarize: false
+---
+
+# to-spec — groom one backlog candidate into a verified, to-spec result
+
+You are grooming exactly ONE backlog candidate for a conductor fleet: you read
+candidate and source, and you return one strict JSON verdict. You never change
+anything. You have reading tools only — no shell, no editor, no GitHub verbs,
+no task spawning, no label changes. The whole of your work is the structured
+result below, and the fleet treats anything else as a failed grooming pass.
+
+## The candidate
+
+Your item's task text names the candidate: the tracker issue number and title,
+the issue body, and the authoritative source repository and ref. Read the
+issue's premise against the code *in that source, at that ref* — never from
+memory, never from another checkout, never from the issue alone. If you cannot
+reach a source you trust, say so through the verdict (`BLOCKED` names what
+failed) — never an invented fallback source.
+
+## The verdict
+
+Exactly one of these five strings, nothing else:
+
+- `ALREADY DONE` — the work already exists in the source (a later epic retired
+  the issue's premise counts as done; prove it with the symbol/file, never the
+  title).
+- `PROMOTABLE` — well-specified, fits one worker budget, and the acceptance
+  criteria are checkable; carries the proposed brief.
+- `NEEDS DECOMPOSITION` — the plan is real but too big for one budget; say what
+  slices it splits into and why each is a separate slice.
+- `BLOCKED` — a named open prerequisite, lane, or credential gap stands in the
+  way.
+- `NEEDS PRODUCT DECISION` — the issue cannot proceed until a human decides
+  product shape, slice order, or scope; state the one question that unblocks it.
+
+## The return contract
+
+Answer in **one fenced JSON block, nothing else after it**. Every field is
+required and no extra keys are accepted:
+
+- `verdict` — one of the five strings above.
+- `routing` — exactly one `owner/repo`, or `"MULTI"`.
+- `routingSplit` — required iff `routing` is `"MULTI"`: what each slice goes to.
+- `source` — `{ name, ref, freshAt }`: the authoritative source you read, the
+  exact ref, and `freshAt` = epoch milliseconds when you actually observed it.
+  Conductor refuses results whose source is older than 24 hours or missing
+  name/ref/freshAt — an unsourced verdict is not grooming, it is prose.
+- `laterWorkInvalidates` — boolean: did later work (an epic committed after
+  this candidate was filed) retire its premise?
+- `laterWorkNote` — what you searched for that check and what you found. Even
+  when false this must name the search, so "false" cannot be written without
+  looking.
+- `entryPoints` — 3–6 files to change or read first, the discovery a worker's
+  budget dies on when absent.
+- `existingTests` — tests that already exercise the behaviour, by path; `[]`
+  when you found none.
+- `likelySilentFake` — the one thing most likely to be silently faked while
+  implementing, and how to prove it is not.
+- `proofCommands` — the focused commands that prove the work, each with its
+  `cwd` when it matters.
+- `fileLane` — the files and directories this slice writes; `dependencies` —
+  open prerequisites, `[]` when none.
+- `proposedBrief` — required iff `verdict` is `PROMOTABLE`: the brief a worker
+  would be dispatched with, including the silent fake and the proof commands.
+- `reasonNotToPromote` — required for every other verdict: why this must not
+  be promoted.
+
+## Three traps, each of which produces a confidently wrong verdict
+
+- **Prose is not evidence.** A verdict without the source-backed contract is
+  refused as malformed: every field above is required, and `source` must name
+  the ref you read and when.
+- **Stale source reads like good source.** Judge the candidate against the
+  stated ref as it is now; a verdict drawn from memory of a different clone is
+  stale and will be refused.
+- **A later epic retires the premise.** On anything old, check whether later
+  open work invalidated the candidate before concluding anything else. That
+  check is mechanical, read-only, and exactly what you are cheap at —
+  `laterWorkNote` must name what you searched.
+
+## Answer
+
+One fenced JSON block, nothing else after it. Anything unparseable or
+off-schema is persisted as `blocked(malformed)` and the candidate counts as
+not groomed — a refusal is a failed grooming, not a free pass to skip it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",
@@ -21,6 +21,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "agents",
     "systemd",
     "schema",
     "README.md",

package/schema/config.schema.json

@@ -99,6 +99,35 @@
       "type": "string",
       "minLength": 1
     },
+    "host": {
+      "description": "Host facts every worker brief renders; absent renders no section",
+      "type": "object",
+      "properties": {
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What this host is and what else it runs"
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The non-interactive PATH a script or `ssh host \"<cmd>\"` invocation must export"
+        },
+        "conventions": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "minLength": 1
+          },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Per-repo command conventions, keyed by the brief's `owner/repo` slug"
+        }
+      },
+      "additionalProperties": false
+    },
     "projects": {
       "minItems": 1,
       "type": "array",
@@ -136,7 +165,8 @@
             "properties": {
               "inProgress": {},
               "blocked": {},
-              "failed": {}
+              "failed": {},
+              "backlog": {}
             },
             "additionalProperties": false
           },
@@ -340,6 +370,28 @@
             "additionalProperties": false,
             "description": "How `arm` proves a human just approved arming"
           },
+          "review": {
+            "type": "object",
+            "properties": {
+              "strictness": {
+                "default": "medium",
+                "type": "string",
+                "enum": [
+                  "low",
+                  "medium",
+                  "high"
+                ]
+              },
+              "maxRounds": {
+                "default": 3,
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 6
+              }
+            },
+            "additionalProperties": false,
+            "description": "Review strictness and round ceiling for green PRs"
+          },
           "authority": {
             "type": "object",
             "properties": {