omp-conductor 0.16.2 → 0.17.1

package/README.md

@@ -154,6 +154,26 @@ completions this way and adds the rc source line only when it is absent.
 
    The wizard reads the tracker with the same routing code as the daemon. It shows every issue that the next tick can route.
 
+   On an interactive TTY, setup uses the styled Clack interface. Piped setup
+   keeps the stable line protocol for automation. Set
+   `OMP_CONDUCTOR_PLAIN_UI=1` to use the readline interface on a TTY and replace
+   Clack progress in other verbs with their stable plain messages.
+
+   To make an interactive run replayable, save every accepted answer by its
+   stable key:
+
+   ```bash
+   omp-conductor setup --save-answers ./setup-answers.json
+   omp-conductor setup --answers ./setup-answers.json
+   ```
+
+   An answers file is a JSON object whose values are strings or booleans.
+   Confirmations require booleans, text prompts require strings, and select
+   prompts require the exact displayed label. `--answers` never falls back to
+   an interactive prompt: a missing key or wrong value fails with the key and
+   question name. Piped line input remains supported, but an exhausted pipe
+   fails with the `--answers` alternative instead of waiting indefinitely.
+
    Nothing changes before the consent step. After consent, setup does these actions:
 
    - creates the required labels;
@@ -381,6 +401,19 @@ fleet, and both are covered above under
 paused-fleet failure hides. `tail`, `extend`, `unblock` and the `worker`
 controls are the day-to-day levers:
 
+For automation, `status --json` emits the same project, layer, daemon,
+Telegram, code-graph, run, cap, report, and sibling data as the text report.
+The other read-only ledgers have stable JSON forms too:
+
+```bash
+omp-conductor ledger --json
+omp-conductor decision list --json
+omp-conductor watch list --json
+```
+
+JSON output is never styled. Empty ledgers return their normal top-level object
+with an empty `entries`, `decisions`, or `watches` array.
+
 ### Outcomes and cost: `stats`
 
 `omp-conductor stats [--since 7d | 30d | YYYY-MM-DD] [--project NAME] [--json]`
@@ -545,13 +578,13 @@ reference — usage strings, flags and per-command behaviour — is in the
 
 | Verb | What it does |
 | --- | --- |
-| `setup [area]` | The wizard: interview + probes. `--no-ai`, per-area amend, `host`, `graph`. |
+| `setup [area]` | The wizard: interview + probes. `--no-ai`, `--answers FILE`, `--save-answers FILE`, per-area amend, `host`, `graph`. |
 | `start` / `stop` / `restart` | Run the dispatch daemon. `restart` drains first; `stop --pane` also halts the pane. |
 | `upgrade [--to VERSION]` | Pin one published npm release across CLI, omp plugin, Herdr plugin and brief. |
-| `status` | Layered fleet report: dispatch, ticks, pane, recovery, telegram, daemon, then the project body. |
+| `status [--json]` | Layered fleet report: dispatch, ticks, pane, recovery, telegram, daemon, then the project body. |
 | `stats [--since 7d|30d|YYYY-MM-DD] [--json]` | What the fleet accomplished and at what cost, from the local store only: merges, merge rate, lead time, attempts and metered cost per merged issue, failure classes, gh calls. |
 | `doctor [--json] [--probe-telegram]` | Read-only deployment health — gh auth, exact-case labels, systemd drift, config backup, sqlite integrity, spend telemetry, timezones, Telegram. Run after install and after every upgrade; exit 0 only when nothing failed. |
-| `ledger` | The action audit — every mediated verb, refusal and turn budget. |
+| `ledger [--json]` | The action audit — every mediated verb, refusal and turn budget. |
 | `board` | Live terminal kanban from Queue to Settled. |
 | `dashboard [--port N] [--host ADDR]` | Browser UI plus bearer-authenticated `/api/projects`: every project's daemon state, port and healthz. Loopback by default; the token lives at `<state>/dashboard-token`. |
 | `hold [--keep-ticks]` | Pause claims and disarm ticks — the soft stop. |
@@ -563,7 +596,8 @@ reference — usage strings, flags and per-command behaviour — is in the
 | `verb <conductor_*>` | Run a mediated verb from the CLI (external orchestration). |
 | `friction <kind> --detail TEXT` | Record a bounded operator judgment — an escalation that belonged in a digest, or a report that was noise/surprising — feeding the learning loop. |
 | `event record` / `report` / `message` | Record and deliver reports and messages through the durable outbox. |
-| `decision open/resolve/withdraw/list` | Read and answer questions in the decision ledger. |
+| `decision open/resolve/withdraw/list [--json]` | Read and answer questions in the decision ledger; JSON applies to `list`. |
+| `watch add/list [--json]` | Record or list orchestrator-only conditions and carry notes; JSON applies to `list`. |
 | `intake "<text>"` / `intake list` / `intake dismiss <id>` | Capture a raw idea durably (it lives in the store and survives restarts), list what is still pending, dismiss what turned out to be nothing. |
 | `daemon [--once]` | Run the loop in the foreground — systemd's entry point. |
 | `resume` | Clear pause and any `stop --pane` recovery pin; never re-arms. |

package/REFERENCE.md

@@ -265,6 +265,12 @@ Skip the reading half entirely with `--no-ai`:
 omp-conductor setup --no-ai
 ```
 
+For unattended setup, pass `--answers FILE` with a JSON object keyed by the
+stable prompt keys captured by `--save-answers`; the command exits `1` and
+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.
+
 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:
 
@@ -1858,7 +1864,7 @@ policy instead of restating it — no threshold lives in two places.
 
 | Field | Values | Default | Means |
 | --- | --- | --- | --- |
-| `requires` | `runs-settled`, `no-open-prs`, `queue-drained`, `base-branch-green`, `epic-children-closed` | `["runs-settled"]` | What must already have landed. `runs-settled` reads each active run's PR fact at release time: a pushed run whose PR has merged counts as settled even when the settle sweep has not yet written the terminal row — so a hold-drained release does not wait an extra tick the operator reached the gate by holding. Live workers and unmerged/unknown PRs still refuse, and the message names which is which. `base-branch-green` requires the current live head's push-triggered workflow verdict for that routed repository to be green; pending, unknown, red, or no observation refuses release. Order and duplicates do not matter; the loader canonicalises. |
+| `requires` | `runs-settled`, `fleet-runs-settled`, `no-open-prs`, `queue-drained`, `base-branch-green`, `epic-children-closed` | `["runs-settled"]` | What must already have landed. `runs-settled` reads each active run of the released repo's PR fact at release time: a pushed run whose PR has merged counts as settled even when the settle sweep has not yet written the terminal row — so a hold-drained release does not wait an extra tick the operator reached the gate by holding. Runs in other routed repos never gate a repo-scoped release — they cannot invalidate the artifact being shipped; a genuinely suite-wide shape (a pin or manifest consuming several repos) opts back into project-wide strictness with the named `fleet-runs-settled` requirement. Live workers and unmerged/unknown PRs still refuse, the message names which is which and which runs are blocking by repo and issue. `base-branch-green` requires the current live head's push-triggered workflow verdict for that routed repository to be green; pending, unknown, red, or no observation refuses release. Order and duplicates do not matter; the loader canonicali…
 | `requiredChecks` | any check names | `[]` | Checks that must be green on the branch being released. Empty means every check it reports. |
 | `artefacts` | any names | `[]` | The packages or images this project releases. **Empty denies**: nothing has been authorised to ship. |
 | `environments` | any names | `[]` | Deploy targets. **Empty denies** every environment. |
@@ -2202,7 +2208,7 @@ least of all on a fleet whose session lives somewhere else.
 ## CLI reference
 
 ```bash
-omp-conductor setup [area] [--no-ai] [--project NAME]
+omp-conductor setup [area] [--no-ai] [--answers FILE] [--save-answers 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]
@@ -2212,10 +2218,10 @@ omp-conductor restart [--now] [--timeout SECONDS] [--port N] [--project NAME]
 omp-conductor upgrade [--to VERSION] [--project NAME]
 omp-conductor upgrade-install --to VERSION [--project NAME]
 omp-conductor upgrade-rollback
-omp-conductor status [--project NAME]
+omp-conductor status [--project NAME] [--json]
 omp-conductor doctor [--project NAME] [--json] [--probe-telegram]
-omp-conductor ledger [--issue N] [--limit N] [--project NAME]
-omp-conductor board [--project NAME]
+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 stop [--pane] [--project NAME]
 omp-conductor arm [--project NAME]
@@ -2234,9 +2240,9 @@ omp-conductor message --text TEXT [--project NAME]
 omp-conductor decision open --question TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
 omp-conductor decision resolve <id> --answer TEXT [--project NAME]
 omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
-omp-conductor decision list [--project NAME]
+omp-conductor decision list [--project NAME] [--json]
 omp-conductor watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
-omp-conductor watch list [--project NAME]
+omp-conductor watch list [--project NAME] [--json]
 omp-conductor daemon [--once] [--port N] [--project NAME]
 omp-conductor resume [--project NAME]
 omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
@@ -2247,15 +2253,15 @@ omp-conductor help
 
 | Command | Scope | Behaviour |
 | --- | --- | --- |
-| `setup [area] [--no-ai] [--project NAME]` | project | The deterministic interview, in a plain terminal — the same prompts, the same one-writer apply sequence, and the same single consent gate as `omp-conductor setup`, which is now one dialog implementation of the shared surface rather than the only way in. Bare is a full first run, or — when the project already exists — a chooser of which area to amend. Naming an area positionally skips that chooser and amends only that area: `tracker`, `gates`, `caps`, `code-graph`, `authority`, `policy`, `escalation`, `reporting`, `brief`. `host` and `graph` are install subcommands rather than areas and are matched first; anything else exits `2` listing both vocabularies. Every prompt shows its current value as the default, and Enter accepts what you see; `Ctrl-C` at any prompt abandons the run and writes nothing. Setup also **reads your repos to propose answers**: the gates prompt is pre-filled from what CI actually runs, and the brief's `## Project context` and release procedure are drafted from every routing repo and shown for confirmation before anything is written. Each probe is a short session with **no shell, no editor and no verbs** in a throwaway shallow clone, and every answer is a proposal you edit or decline — a probe that cannot clone, cannot reach a model, or answers unusably costs you one warning and the shipped stub. `--no-ai` asks every question with the reading half removed. |
+| `setup [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). |
 | `start` | host | Start `herdr-fleet.service` when that optional unit is installed, clearing a previous pane-recovery pin, then start the dispatch daemon and wait until it answers `GET /healthz`. When `omp-conductor.service` is installed, systemd is the only start path: even `start --project NAME` restores the shared unit and uses the name only to verify that `/healthz` serves the requested project. A detached daemon is allowed only when the unit is proven absent. It never clears pause or arms ticks. Refuses if a daemon is already live, naming its pid; manager refusal or unprovable ownership is an error rather than a detached fallback. |
 | `stop` | fleet | Prefer `systemctl stop omp-conductor.service` when that unit's MainPID is the live daemon — systemd then owns the stop and will not schedule a restart for the exit it just requested. Otherwise `SIGTERM`, then `SIGKILL` after a 10-second grace period. Prints `not running` when there is nothing to stop, and tags the confirmation with `(via systemctl)` when the unit path was used. |
 | `restart [--now] [--timeout SECONDS] [--port N] [--project NAME]` | host | Drains the fleet by default: pause new claims, wait until live workers reach `0 / N` (bounded by `--timeout SECONDS`, default 1800 = 30 min), restart, then restore the prior dispatch state. A daemon serving multiple configured projects makes restart host-wide: `--project` is rejected because draining one queue and restarting the shared process would kill another project's workers. Prefer `systemctl restart` when the unit owns the live pid so the replacement stays supervised; only a host proven not to have the installed unit may fall back to the standalone stop/start path. `--now` skips the drain and restarts immediately, orphaning any live runs (old behaviour). A drain that hits `--timeout` restarts nothing and leaves dispatch paused — `omp-conductor resume` lifts it, or re-run `restart` to keep waiting. The new process **salvages dirty live worktrees before orphaning** those rows — see [Deploying a new package onto a busy fleet](#deploying-a-new-package-onto-a-busy-fleet). |
 | `upgrade [--to VERSION] [--project NAME]` | host | Deterministically update the Bun-global CLI, omp plugin, Herdr recovery plugin, and managed brief as one release. Resolves the npm version and exact `gitHead`, pauses only new claims, drains active workers, installs all surfaces, reloads Herdr and the daemon, waits for pane recovery, verifies identities and fleet health twice, then restores the original dispatch state. Host-wide by default: one daemon serves every configured project, so a bare run drains all of them and refreshes every brief. `--project` is rejected when the live daemon serves several projects — draining one queue and restarting the shared daemon would kill another's workers. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. The same transaction runs detached, without a human, as the fleet-installs-itself path: the orchestrator calls the `conductor_install` verb under the granted `install` shape, the daemon validates the version against npm and starts a transient systemd unit (`upgrade-install`) outside the pane and the daemon, and the first tick after the restart verifies version, `/healthz`, ticks, pane and `doctor` against the durable upgrade journal before restoring dispatch — rolling back and paging tier-2 on any gap. |
-| `status [--project NAME]` | fleet | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `brief` / `decisions` / optional `failure classes` and `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, bounded hold groups, and the GitHub API budget (`graphql` / `core` remaining and reset, in the caps block); API failures are marked `DEGRADED` so queue starvation cannot look idle. Active-run lines overlay cooperative worker `paused`/`pausing` from `/healthz` without changing SQLite `running` state or the live worker count. The next tick comes from the live heartbeat process, not a guess from log timestamps. Telegram health uses `getMe` to prove API authentication without sending a message and reports inbound bridge configuration separately. Configured graphs report prerequisites, indexed repos, timer state, and refresh freshness without blocking dispatch. A `reports` block lists everything the outbox has not delivered, with its age, and prints `pending` (nobody has it) differently from `SENDING` (outcome unknown, it may already have arrived) — see [Report delivery](#report-delivery-the-outbox). The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
-| `ledger [--issue N] [--limit N]` | project | The action audit: every [mediated-verb](#the-mediated-verbs-126) mutation and every next-attempt turn budget. Verb entries include the arguments, decision, named refusal, and resulting SHA. Turn-budget entries remain after an override is replaced or consumed. Reads (`conductor_pr_status`) are absent so polling cannot bury the signal. `--issue` narrows both histories; `--limit` defaults to 50. Recent verb refusals and pending turn overrides also appear in `status`. |
+| `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. |
+| `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). |
 | `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`. |
@@ -2272,9 +2278,9 @@ omp-conductor help
 | `decision open --question TEXT [--blocks TEXT] [--resolves-when COND]` | project | Record a question the orchestrator has put to you, and print its id. A question that lives only in a session's context is lost at the next compaction — after which it is either asked twice or dropped silently. `--resolves-when` attaches a machine-checkable condition: `pr-merged:<https url>`, `pr-checks-green:<https url>`, `pr-mergeable:<https url>`, `issue-closed:<n>`, `npm-version:<pkg>@<version>`, or `rate-limit-reset:github`; anything else exits `2` listing the six forms. See [The decision ledger](#the-decision-ledger-136). |
 | `decision resolve <id> --answer TEXT` | project | Record what you decided. Exits `1` naming the id when it is unknown or no longer open, so a second answer cannot overwrite the first. |
 | `decision withdraw <id> [--reason TEXT]` | project | Close a question the session stopped needing, with why. Same guard as `resolve`. |
-| `decision list` | project | Open questions, oldest first: id, age, what each blocks, whether its condition is met, and the question. Prints `no open decisions` when there are none. Watches are not listed here — `watch list` shows those. |
+| `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 list` | project | Open watches, oldest first: id, age, what each blocks, whether its condition is met, and the note. Prints `no watches` when there are none. |
+| `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. |
 | `--port N` | — | Accepted by `start`, `restart` and `daemon`. Both `--port 9000` and `--port=9000` work; missing or out of range exits `2` rather than falling back to the default, because probing the wrong endpoint is worse than a hard failure. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.16.2",
+  "version": "0.17.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.",
@@ -34,6 +34,7 @@
   },
   "dependencies": {
     "@bomb.sh/tab": "0.0.22",
+    "@clack/prompts": "1.7.0",
     "yaml": "^2.9.0",
     "zod": "^4"
   },

package/schema/config.schema.json

@@ -325,6 +325,21 @@
             },
             "additionalProperties": false
           },
+          "arm": {
+            "type": "object",
+            "properties": {
+              "proof": {
+                "default": "challenge",
+                "type": "string",
+                "enum": [
+                  "challenge",
+                  "claim-only"
+                ]
+              }
+            },
+            "additionalProperties": false,
+            "description": "How `arm` proves a human just approved arming"
+          },
           "authority": {
             "type": "object",
             "properties": {
@@ -433,6 +448,7 @@
                       "type": "string",
                       "enum": [
                         "runs-settled",
+                        "fleet-runs-settled",
                         "no-open-prs",
                         "queue-drained",
                         "base-branch-green",

package/src/admission.ts

@@ -19,6 +19,7 @@ import { log, errText, safeEscalate } from "./log.ts";
 import type {
   Caps,
   Escalation,
+  IssueComment,
   IssueSnapshot,
   OpenCloser,
   ProjectConfig,
@@ -28,7 +29,7 @@ import type {
   AdmissionHoldReason,
 } from "./types.ts";
 import { readPlanUsage, type PlanUsageStatus, type UsageSource } from "./usage.ts";
-import type { CriticalBaseProbe, CriticalBaseVerdict, RunLaneProbe } from "./gitops.ts";
+import type { CriticalBaseProbe, CriticalBaseVerdict, LaneFile, LaneSource, RunLaneProbe } from "./gitops.ts";
 import { repoSlugFor } from "./gitops.ts";
 import { branchName, type Routed } from "./routing.ts";
 import { parseDependsOn } from "./depends-on.ts";
@@ -77,10 +78,16 @@ export function hasFailedAttemptBudget(failures: number, maxAttempts: number): b
   return failures < maxAttempts;
 }
 
-/** A candidate cleared for dispatch, with the attempt number it will run as. */
+/** A candidate cleared for dispatch, with the attempt number it will run as.
+ *  `lane` is the effective file-lane declaration admission resolved for it
+ *  (#608): the exact snapshot the overlap gate enforced. Dispatch renders this
+ *  value into the worker brief, so a changed or failed second comment read can
+ *  neither hide nor reword the lane admission held — the gate and the
+ *  worker-visible brief are one value, not two reads of the same thread. */
 export interface Admission {
   r: Routed;
   attempt: number;
+  lane?: FileLane;
 }
 
 export interface AdmissionHold {
@@ -174,27 +181,82 @@ function planUsageEscalation(project: string, plan: PlanUsageStatus): Escalation
  * files an issue declares it will touch (#555).
  *
  * The orchestrator already writes exactly this list into every promotion brief
- * in prose; this parses that same sentence out of the issue body so the
- * interlock is load-bearing rather than advisory. A body line beginning with
- * "file lane" (case-insensitive, optional bold/heading markers) is accepted,
- * and paths are read as backtick-delimited spans (the brief form) with a bare
- * comma/space-separated fallback that keeps tokens that look like relative
- * paths. Anything else — including an absent line, which is the default — is
- * an empty lane: the issue is admitted exactly as today (`fail open`), and the
- * gate never refuse work for wanting a lane. Exported so the format is pinned
- * independent of admission.
+ * in prose; this parses that same sentence out of the issue body — or out of a
+ * pre-dispatch comment, which is the same sentence on a supported brief
+ * surface since #517 — so the interlock is load-bearing rather than advisory.
+ * A line beginning with "file lane" (case-insensitive, optional
+ * bold/heading markers) is accepted, and paths are read as backtick-delimited
+ * spans (the brief form) with a bare comma/space-separated fallback that keeps
+ * tokens that look like relative paths. A line whose tokens are not pathlike
+ * (like `File lane: none`) is not a declaration. Anything else — including an
+ * absent declaration, which is the default — is an empty lane: the issue is
+ * admitted exactly as today (`fail open`), and the gate never refuses work for
+ * wanting a lane. This is the one grammar for all surfaces; there is no second
+ * comment-only spelling.
  */
-export function declaredLane(body: string): string[] {
-  const match = body.match(
+export function laneDeclaration(text: string): LaneDeclaration | undefined {
+  const match = text.match(
     /^\s*(?:[#>*-]\s*)*file[- ]lane\s*[:=]\s*([^\n]*)$/im,
   );
-  if (match === null) return [];
+  if (match === null) return undefined;
   const rest = match[1] ?? "";
   const backticked = [...rest.matchAll(/`([^`]+)`/g)]
     .map((m) => m[1]!.trim())
     .filter(isPathLike);
-  if (backticked.length > 0) return [...new Set(backticked)];
-  return [...new Set(rest.split(/[,\s]+/).map((s) => s.trim()).filter(isPathLike))];
+  const files =
+    backticked.length > 0
+      ? [...new Set(backticked)]
+      : [...new Set(rest.split(/[,\s]+/).map((s) => s.trim()).filter(isPathLike))];
+  if (files.length === 0) return undefined;
+  return { files, source: match[0].trim() };
+}
+
+/** One parsed `File lane:` declaration: the paths and the verbatim source
+ *  line, so a renderer can reproduce the declaration itself rather than a
+ *  summary of it. Exported for the brief's guarantee that the gate's effective
+ *  lane is always visible to the worker (#608). */
+export interface LaneDeclaration {
+  files: string[];
+  /** The declaration line verbatim, as written on the surface it came from. */
+  source: string;
+}
+
+/**
+ * The effective file lane as both admission and the worker brief must read it
+ * (#608): the latest `File lane:` declaration among the issue body and every
+ * comment, in the tracker's oldest-first order. This is the "later correction
+ * visibly supersedes" contract applied across both surfaces at once, and it is
+ * the single source of truth the gate enforces and the brief renders — so a
+ * declaration can never control admission while staying invisible to the
+ * worker. `at` records which surface won (`"body"`, or the 0-based comment
+ * index), letting the brief reproduce the declaration verbatim when the
+ * winning comment sits beyond its rendered discussion budget.
+ */
+export interface FileLane extends LaneDeclaration {
+  at: "body" | number;
+}
+
+/** Who holds one file's lane this admission pass, and which read proved it.
+ *  `"declared"` is the same-pass half: an admitted candidate's own lane
+ *  occupies for the rest of the pass without any probe read. */
+export type LaneHolder = { issue: number; source: LaneSource | "declared" };
+
+/** Resolves the effective lane across the body and the whole comment thread. */
+export function effectiveLane(body: string, comments: IssueComment[]): FileLane | undefined {
+  let current: FileLane | undefined;
+  const bodyDecl = laneDeclaration(body);
+  if (bodyDecl !== undefined) current = { ...bodyDecl, at: "body" };
+  for (let i = 0; i < comments.length; i++) {
+    const decl = laneDeclaration(comments[i]!.body);
+    if (decl !== undefined) current = { ...decl, at: i };
+  }
+  return current;
+}
+
+/** The paths of an issue body's declared lane (empty for no declaration).
+ *  Exported so the format is pinned independent of admission. */
+export function declaredLane(body: string): string[] {
+  return laneDeclaration(body)?.files ?? [];
 }
 
 /** A plausible relative path: it has a `.` extension or a directory separator. */
@@ -271,14 +333,14 @@ export async function admitCandidates(
   // and one on the web repo are different files. Built lazily and once, only
   // when the first candidate that declares a lane reaches the gate, so a queue
   // of laneless issues pays nothing for it.
-  let laneOccupancy: Map<string, Map<string, number>> | undefined;
-  const ensureLaneOccupancy = async (): Promise<Map<string, Map<string, number>>> => {
+  let laneOccupancy: Map<string, Map<string, LaneHolder>> | undefined;
+  const ensureLaneOccupancy = async (): Promise<Map<string, Map<string, LaneHolder>>> => {
     if (laneOccupancy !== undefined) return laneOccupancy;
-    const occupied = new Map<string, Map<string, number>>();
+    const occupied = new Map<string, Map<string, LaneHolder>>();
     for (const run of activeRuns) {
       if (d.probeWorktreeLane === undefined) break;
       const base = project.routing.repos[run.repo]?.defaultBranch ?? "main";
-      let files: string[];
+      let files: LaneFile[];
       try {
         files = await d.probeWorktreeLane({
           worktree: run.worktree,
@@ -291,20 +353,64 @@ export async function admitCandidates(
         // well-formed issue because one probe could not be answered.
         files = [];
       }
-      for (const file of files) {
-        if (occupied.get(run.repo)?.has(file) === true) continue;
+      for (const { file, source } of files) {
         let perRepo = occupied.get(run.repo);
         if (perRepo === undefined) {
           perRepo = new Map();
           occupied.set(run.repo, perRepo);
         }
-        perRepo.set(file, run.issue);
+        // First read wins: a file the run both commits and edits in its
+        // worktree is tagged by its live uncommitted half.
+        if (!perRepo.has(file)) perRepo.set(file, { issue: run.issue, source });
       }
     }
     laneOccupancy = occupied;
     return occupied;
   };
 
+  // The candidate half of the file-lane interlock (#555): the machine-readable
+  // lane an issue declares. Since #517 a promotion brief may live in a
+  // pre-dispatch comment rather than the body, so the lane is read from both
+  // surfaces — the same two the worker brief renders — through the tracker's
+  // existing comment port, never a second comment reader. Body and comments
+  // share the one `laneDeclaration` grammar, and the brief's "later correction
+  // visibly supersedes" contract holds: the effective lane is the latest
+  // declaration among the body and the WHOLE thread, so a correction posted as
+  // a comment replaces an earlier body lane instead of widening it (#608).
+  //
+  // Reading every comment — not just the ones the brief's discussion budget
+  // renders — is deliberate: this is the same `effectiveLane` the brief
+  // renders, and the dispatch side guarantees the winning declaration appears
+  // in the brief verbatim even when it sits beyond the budget. The gate and
+  // the worker therefore agree on one lane, which is the #608 defect's shape.
+  //
+  // Comments are read at most once per issue per pass — the lane feeds both
+  // the gate and the same-pass sibling occupancy below, so the cache is what
+  // stops one candidate costing two comment reads. Unreadable comments fail
+  // open to the body declaration (a body lane stays load-bearing), and with no
+  // readable declaration at all the #555 fail-open admission is unchanged.
+  //
+  // The resolved `FileLane` — not just its paths — is what an admitted
+  // candidate carries into dispatch (#608): the gate and the brief must agree
+  // on the *same declaration* (paths, verbatim source line, and which surface
+  // it came from), so dispatch renders this cached value rather than reading
+  // the thread a second time and hoping it did not change.
+  const laneCache = new Map<number, FileLane | undefined>();
+  const laneFor = async (r: Routed): Promise<FileLane | undefined> => {
+    const issue = r.issue.number;
+    if (laneCache.has(issue)) return laneCache.get(issue);
+    let lane: FileLane | undefined;
+    try {
+      lane = effectiveLane(r.issue.body, await tracker.listComments(issue));
+    } catch (err) {
+      const bodyDecl = laneDeclaration(r.issue.body);
+      lane = bodyDecl === undefined ? undefined : { ...bodyDecl, at: "body" };
+      log(`#${issue} comments unreadable at admission; the body's file lane stands: ${errText(err)}`);
+    }
+    laneCache.set(issue, lane);
+    return lane;
+  };
+
   // The plan allowance is a fleet-wide question, so it is asked once per pass
   // and answers for every candidate — unlike every gate below it, which is
   // per-issue. It sits here rather than beside the spend cap in `tick` for one
@@ -505,25 +611,30 @@ export async function admitCandidates(
       }
       if (verdict.state === "unknown") {
         // Fail closed: a branch that cannot be *proven* to contain the marker
-        // is refused, and the reason names the unverifiable marker so the
-        // operator can fix the fetch or the marker rather than guess.
-        hold(issue, "stale-base");
+        // is refused. This is a verification/lookup failure — the mirror fetch
+        // failed, the marker did not resolve, or no probe is wired — never
+        // evidence that the branch predates the marker. Hold with a distinct
+        // reason so status and the friction rollup do not read a provider
+        // outage as branch staleness, and prescribe no branch change: the next
+        // admission pass re-runs the probe and admits the unchanged branch
+        // once verification succeeds.
+        hold(issue, "critical-base-verify-error");
         log(
-          `#${issue} held (stale-base): continuation branch ${branch} could not be verified ` +
+          `#${issue} held (critical-base-verify-error): continuation branch ${branch} could not be verified ` +
             `against critical-base marker(s) ${markers.join(", ")} (${verdict.error})`,
         );
         await safeEscalate(d, {
           tier: 1,
           project: project.name,
           issue,
-          summary: `#${issue} continuation branch could not be verified against a critical base safety commit and is held (stale-base)`,
+          summary: `#${issue} continuation branch could not be verified against a critical base safety commit and is held (critical-base-verify-error)`,
           detail: [
             r.issue.title,
             r.issue.url,
             `The retained branch ${branch} could not be verified against critical-base marker(s) ${markers.join(", ")}: ${verdict.error}`,
-            "Recovery: merge current base into the branch so it contains the marker, and the next",
-            "admission pass re-admits it automatically without losing the branch's work; or review",
-            "the branch by hand and clear the hold once the fix is present.",
+            "The branch is not claimed to predate the marker: this is a verification failure.",
+            "No branch change is prescribed. The next admission pass retries the critical-base",
+            "verification automatically and admits the unchanged branch once the probe succeeds.",
           ].join("\n"),
         });
         continue;
@@ -795,18 +906,23 @@ export async function admitCandidates(
     // a live run's *actual* lane is held until that run's work has merged, so
     // no second worker is sent at files another worker is still writing. The
     // gate is the mechanical version of the prose rule that failed three times
-    // in one day. Only the machine-readable lane participates: a candidate
-    // without one is admitted exactly as today (fail open), and a candidate's
-    // own retained run never holds it — that is the continuation it continues.
-    const lane = declaredLane(r.issue.body);
-    if (lane.length > 0) {
+    // in one day. Only the machine-readable lane participates — read from the
+    // body and pre-dispatch comments alike, so the gate sees the same surface
+    // the worker brief renders (#608) — and a candidate without one is
+    // admitted exactly as today (fail open), while a candidate's own retained
+    // run never holds it — that is the continuation it continues.
+    const lane = await laneFor(r);
+    if (lane !== undefined && lane.files.length > 0) {
       const occupied = await ensureLaneOccupancy();
       const perRepo = occupied.get(r.repo.name);
       let blocked = false;
-      for (const file of lane) {
+      for (const file of lane.files) {
         const holder = perRepo?.get(file);
-        if (holder !== undefined && holder !== issue) {
-          const detail = `${file} held by run #${holder}`;
+        if (holder !== undefined && holder.issue !== issue) {
+          // The source names the probe read that proved the occupancy, so a
+          // hold reads as authored work — worktree or branch — rather than the
+          // base-reconciliation noise #684 filters out of the probe entirely.
+          const detail = `${file} held by run #${holder.issue} (${holder.source})`;
           hold(issue, "file-lane", detail);
           log(`#${issue} held (file-lane): ${detail}`);
           blocked = true;
@@ -816,20 +932,20 @@ export async function admitCandidates(
       if (blocked) continue;
     }
 
-    admitted.push({ r, attempt: priorRuns + 1 });
+    admitted.push({ r, attempt: priorRuns + 1, lane });
     liveByRepo.set(r.repo.name, (liveByRepo.get(r.repo.name) ?? 0) + 1);
     // Same-pass sibling occupancy for the file-lane gate: once admitted, a
     // candidate's declared lane occupies for the rest of the pass, so a later
     // overlapping candidate is held rather than both clearing in one tick.
-    if (lane.length > 0) {
+    if (lane !== undefined && lane.files.length > 0) {
       const occupied = await ensureLaneOccupancy();
       let perRepo = occupied.get(r.repo.name);
       if (perRepo === undefined) {
         perRepo = new Map();
         occupied.set(r.repo.name, perRepo);
       }
-      for (const file of lane) {
-        if (!perRepo.has(file)) perRepo.set(file, issue);
+      for (const file of lane.files) {
+        if (!perRepo.has(file)) perRepo.set(file, { issue, source: "declared" });
       }
     }
     if (parent !== undefined) {

package/src/availability.ts

@@ -91,17 +91,35 @@ export function availabilityDisposition(
   return "availability";
 }
 
+/** A question-kind category. Every ask surface — `message --category
+ *  decision-needed`, a `QUESTION:`-marked message, and `conductor_ask`'s
+ *  default — resolves to this one category, so treating it as
+ *  availability-deferred covers the whole question pathway at once (#596). */
+export const QUESTION_KIND: InterruptCategory = "decision-needed";
+
 /**
  * Decide one tier-2 category. `digest` means the category policy itself defers
  * it; `availability` means it was otherwise interruptible and may be released
  * when the configured window next opens.
+ *
+ * A question is availability-deferred, never digest-deferred (#596): the
+ * category policy decides what may interrupt the operator's phone, but a
+ * question's deferral is literally "the operator is not available" — it waits
+ * for the window and the working-hours catch-up can release it at the next
+ * opening. With no window configured the next opening is now, so a question
+ * delivers rather than being silently bound to the daily digest. The
+ * `interruptOn` list never applies to a question's deferral.
  */
 export function interruptDisposition(
   policy: ReportingPolicy | undefined,
   category: InterruptCategory,
   at: number,
 ): InterruptDisposition {
-  if (policy !== undefined && !policy.interruptOn.includes(category)) return "digest";
+  if (
+    policy !== undefined &&
+    category !== QUESTION_KIND &&
+    !policy.interruptOn.includes(category)
+  ) return "digest";
   return availabilityDisposition(policy?.availability, category, at);
 }
 
@@ -148,6 +166,14 @@ export function formatZonedMinute(at: number, timezone: string): string {
   return `${local.date} ${local.clock} ${timezone} (${new Date(at).toISOString()})`;
 }
 
+/** Compact local timestamp for a one-line future, e.g. "2026-08-24 09:00 UTC":
+ *  the same instant as {@link formatZonedMinute} without the ISO tail, so a
+ *  held-notice line read on a phone says plainly when the window opens. */
+export function formatNextWindowOpening(at: number, timezone: string): string {
+  const local = localMinute(at, timezone);
+  return `${local.date} ${local.clock} ${timezone}`;
+}
+
 /** One prompt sentence; the runtime gate, not this prose, owns the decision. */
 export function availabilityPrompt(policy: ReportingPolicy | undefined, now: number): string {
   const state = availabilityState(policy, now);

package/src/briefs/worker.md

@@ -98,6 +98,8 @@ These are the exact gates for `{{REPO}}`:
 
 {{GATES}}
 
+{{SHARED_HOST_NOTICE}}
+
 Run every one of them, from the directory listed, over the **whole tree** — not
 just the directory you edited. Linting only the source dir is how an error in a
 migration, a config file or a script reaches the runners.