omp-conductor 0.16.1 → 0.17.0

package/README.md

@@ -114,6 +114,31 @@ For what the host needs before anything runs — `bun`, an authenticated `gh`,
 `omp-telegram` for the escalation channel — see the
 [Install prerequisites](https://github.com/TerrifiedBug/conductor/blob/main/omp/REFERENCE.md#install-prerequisites) in the reference.
 
+### Shell completions
+
+`omp-conductor complete` generates completions for zsh, bash, fish, and
+PowerShell. Load them for the current shell:
+
+```bash
+source <(omp-conductor complete zsh)
+# or
+source <(omp-conductor complete bash)
+```
+
+For a persistent zsh install:
+
+```bash
+mkdir -p ~/.omp/conductor
+omp-conductor complete zsh > ~/.omp/conductor/completions.zsh
+echo '[ -f ~/.omp/conductor/completions.zsh ] && source ~/.omp/conductor/completions.zsh' >> ~/.zshrc
+```
+
+Use `bash` and `~/.bashrc` for the equivalent bash install. In fish, run
+`omp-conductor complete fish | source`; in PowerShell, run
+`omp-conductor complete powershell | Out-String | Invoke-Expression`.
+After a successful interactive setup, the wizard offers to install zsh or bash
+completions this way and adds the rc source line only when it is absent.
+
 ## Quick start
 
 1. Install `omp-conductor` and `omp-telegram`. Pair the Telegram bot and enable its bridge.
@@ -129,6 +154,26 @@ For what the host needs before anything runs — `bun`, an authenticated `gh`,
 
    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;
@@ -356,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]`
@@ -520,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. |
@@ -538,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:
 
@@ -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,26 +2240,28 @@ 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]
+omp-conductor complete <zsh|bash|fish|powershell>
+omp-conductor complete -- <args...>
 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`. |
@@ -2270,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. |
@@ -2285,6 +2293,7 @@ omp-conductor help
 | `--retrofit` | — | Only for `brief-upgrade`. Propose (or with `--apply`, write) a `YOURS TO EDIT` banner before the first owned-topic heading on a hand-written brief. |
 | `--apply` | — | Only for `brief-upgrade`. Confirms `--migrate` / `--retrofit`. On its own it exits `2`: the legacy single-file merge was removed in 0.4.3. |
 | `--file PATH` | — | Only for `brief-upgrade`. Check a brief that is not where the wizard would have put it, on a host that may have no config at all. |
+| `complete <zsh\|bash\|fish\|powershell>` | none | Print a shell completion script. Source it directly for a session or save it and source the file from the shell rc. Interactive setup offers the persistent zsh/bash install; fish and PowerShell remain available manually. `complete -- <args...>` is the fast shell callback protocol: static verbs, subcommands, flags and setup areas come from the command manifest, while project names load from config and fail empty on any read error. |
 | `help`, `--help`, `-h` | none | Print usage. An unknown or missing verb prints it too, and exits `2`. |
 
 Pause is a sentinel under the state directory and survives a daemon restart.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "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.",
@@ -33,6 +33,8 @@
     "schema": "bun run src/generate-schema.ts"
   },
   "dependencies": {
+    "@bomb.sh/tab": "0.0.22",
+    "@clack/prompts": "1.7.0",
     "yaml": "^2.9.0",
     "zod": "^4"
   },

package/src/briefs/orchestrator.md

@@ -381,12 +381,27 @@ did not arrive.
 
 ## Human messages
 
-A human writing to you between ticks is not a tick. Answer with a **single
-`telegram_send` call** — one message, the answer only, from evidence you already
-hold or go and fetch. Never answer as plain end-of-turn text: on this session,
-text you merely write reaches nobody — if you do not call `telegram_send`, the
-person gets silence. While handling any turn, produce no visible commentary
-between tool calls — reasoning stays in thinking, actions stay in tools.
+A human writing to you between ticks is not a tick, and how a reply reaches
+them depends on which of three shapes this turn is — a shape the brief states,
+never something a session infers from a tool's error:
+
+- **A locally injected tick** has no inbound message and no topic to keep:
+  hand anything reportable to the outbox with `omp-conductor report`, and reach
+  the operator directly with `omp-conductor message --text "<the message>"`,
+  declaring the escalation category when you are asking. Your tick prompt names
+  this shape — it carries the delivery rule that says when a tick was injected
+  locally.
+- **A turn that began as an inbound Telegram message** is answered with a
+  **single `telegram_send` call** — one message, the answer only, from evidence
+  you already hold or go and fetch — omitting **both** `chat_id` and `thread_id`
+  so the reply keeps the topic the message came from.
+- **An interactive terminal session**, started by hand, is one the operator is
+  reading live: there, end-of-turn text **is** the delivery, and Telegram is
+  used only when it must demonstrably arrive — `telegram_send` resolves
+  `chat_id` from the last inbound message and refuses without one.
+
+While handling any turn, produce no visible commentary between tool calls —
+reasoning stays in thinking, actions stay in tools.
 
 **Reply where the message arrived.** `thread_id` defaults to the active topic
 *only while `chat_id` is omitted*, so a fleet whose Telegram is a forum topic

package/src/briefs/policy.md

@@ -85,11 +85,19 @@ authoritative. All four scopes, spelled out:
   interrupt when operator availability permits; everything else waits for one
   daily rollup.
 
-**Delivery.** Never rely on end-of-turn text reaching anyone. The provable
-delivery paths are `omp-conductor report` (reports — persisted and retried by
-the daemon) and `telegram_send` (direct messages). `telegram_ask` is the decision
-primitive, not Telegram delivery evidence. Everything else is noise or silence.
-Hand every reportable event to the conductor's outbox:
+**Delivery.** A reply reaches the operator by the shape of the turn it answers.
+A **locally injected tick** delivers through the outbox — `omp-conductor report`
+for anything reportable, `omp-conductor message` to reach the operator directly —
+because a report written as end-of-turn text on a tick reaches nobody. A turn
+that **began as an inbound Telegram message** answers with `telegram_send`,
+omitting `chat_id` and `thread_id` so the reply keeps its topic. An **interactive
+terminal session** is read live by the operator, so end-of-turn text *is* the
+delivery there; `telegram_send` resolves `chat_id` from the last inbound message
+and refuses without one, so it is used only when the message must demonstrably
+arrive. The provable delivery paths are `omp-conductor report` (persisted and
+retried by the daemon) and `telegram_send` (direct messages); `telegram_ask` is
+the decision primitive, not delivery evidence. Hand every reportable event to
+the conductor's outbox:
 
 ```
 omp-conductor report --text "<the whole report>"          # a material event

package/src/clack-ui.ts

@@ -0,0 +1,83 @@
+// @clack/prompts is ESM-only and currently imports node:process in a shape
+// that blocks a future `bun build`; this CLI intentionally executes TS in Bun.
+import * as p from "@clack/prompts";
+import { stdin, stdout } from "node:process";
+import type { Readable, Writable } from "node:stream";
+
+import type { TerminalUi } from "./wizard-ui.ts";
+
+interface ClackIo {
+  input?: Readable;
+  output?: Writable;
+}
+
+/** Interactive WizardUi driver. Callers gate this on TTY input and output. */
+export function clackUi(io: ClackIo = {}): TerminalUi {
+  const input = io.input ?? stdin;
+  const output = io.output ?? stdout;
+  const promptIo = { input, output };
+  let closed = false;
+  let started = false;
+  const start = (): void => {
+    if (started) return;
+    started = true;
+    p.intro("omp-conductor setup", { output });
+  };
+
+  return {
+    close: (message) => {
+      if (closed) return;
+      closed = true;
+      if (started) p.outro(message ?? "Setup finished.", { output });
+    },
+    notify: (message, type = "info") => {
+      start();
+      if (message.includes("\n")) {
+        const title = type === "warning" ? "Warning" : type === "error" ? "Error" : undefined;
+        p.note(message, title, { output });
+        return;
+      }
+      if (type === "warning") p.log.warning(message, { output });
+      else if (type === "error") p.log.error(message, { output });
+      else p.log.info(message, { output });
+    },
+    confirm: async (title, message) => {
+      start();
+      const result = await p.confirm({
+        ...promptIo,
+        message: `${title}\n${message}`,
+        initialValue: false,
+      });
+      return p.isCancel(result) ? undefined : result;
+    },
+    input: async (title, placeholder) => {
+      start();
+      const result = await p.text({
+        ...promptIo,
+        message: title,
+        placeholder,
+        defaultValue: placeholder,
+      });
+      return p.isCancel(result) ? undefined : result;
+    },
+    select: async (title, options, dialogOptions) => {
+      start();
+      const index = Math.max(
+        0,
+        Math.min(dialogOptions?.initialIndex ?? 0, options.length - 1),
+      );
+      const initialValue = options[index]?.label;
+      const result = await p.select({
+        ...promptIo,
+        message: title,
+        options: options.map((option) => ({
+          value: option.label,
+          label: option.label,
+          hint: option.description,
+        })),
+        initialValue,
+      });
+      return p.isCancel(result) ? undefined : result;
+    },
+  };
+}