omp-conductor 0.4.2 → 0.4.3

package/README.md

@@ -79,6 +79,7 @@ runtime acts on:
 | --- | --- | --- |
 | `material` (default) | Escalations, plus every material event: a run reaching a green PR, a run that failed twice, an issue pulled off the queue, a cap that stopped the fleet. | `Report material events per your brief.` |
 | `escalations` | Escalations when they happen, plus one daily digest. Silent otherwise. | `Report NOTHING this turn except a Tier 1 or Tier 2 escalation; everything else -- releases included -- waits for the daily digest.` |
+| `decisions` | Tier-2 decisions and fleet-stopping conditions immediately; every other material event is held and ships with the next tick report, as one message. | `Reporting scope decisions: interrupt only for a decision you need (tier-2) or a condition that stops the fleet. Every other material event accumulates and ships as ONE message with this tick's report via omp-conductor report -- a merge, a green PR, a pulled issue wait for the tick; nothing between ticks.` |
 
 **What the scope does:** the [orchestrator heartbeat](#orchestrator-tick) appends
 that line to every tick it sends, so the reporting contract arrives with the
@@ -247,7 +248,7 @@ So the skill does the part a dialog cannot:
   question that makes a delegated release safe: *where does the agent's leg end?*
   The answer becomes the [`authority`](#configuration) pair `/conductor setup`
   records, and the brief is worded from it. Plus escalation taste, and which of
-  the two [`reporting.scope`](#your-workflow-vs-the-package)
+  the three [`reporting.scope`](#your-workflow-vs-the-package)
   values your answer actually maps to.
 - **Reads your repos instead of asking about them.** It opens each routing repo's
   CI workflows, `package.json` scripts and `Makefile`/`justfile`, then *proposes*
@@ -357,7 +358,13 @@ omp-conductor brief-upgrade --retrofit --apply
   `~/.omp/conductor/backups/briefs/`), named with their source filename and
   timestamp.
 - **Hand-written brief** (no banner): `--retrofit` inserts the banner before the first Releases / Project context / Reporting / Amendments heading; then `--migrate`.
-- **Legacy `--apply`**: still merges a bannered single-file brief when you need the old path.
+- **The legacy single-file merge is gone** (0.4.3). A bare `--apply` exits `2`
+  naming the two paths that remain, rather than rewriting a brief nobody asked
+  it to. `--migrate` is the cross-version ABI: an upgrade keeps calling it, and
+  an overlay fleet tolerates its absence because the floor recomposes each tick.
+- **`status` names the layout**, so a fleet still on a legacy brief is visible
+  where an operator already looks: `brief     overlay (package floor + POLICY.md)`,
+  or `brief     legacy-bannered — run omp-conductor brief-upgrade`.
 - **Existing sidecars**: a composed refresh relocates conductor-generated
   `ORCHESTRATOR.md.bak-<timestamp>` and `POLICY.md.bak-<timestamp>` files into
   that backup directory. Other `.bak` files stay untouched.
@@ -1302,6 +1309,129 @@ The tier-2 escalation ledger (`notifications`) is untouched by all of this. It i
 a bare dedupe key by design — its primary key *is* the key — which is exactly why
 reports needed a separate table rather than an extension of that one.
 
+## The decision ledger (#136)
+
+The outbox above fixed reports the orchestrator sends. This fixes the ones it is
+**waiting on**. A question put to you — an amendment, a tier-2 decision, "do I
+ship this tonight?" — lived in exactly one place: the model's context. A
+compaction, a restart, or a tick that ran long lost the question *and* the fact
+that one was owed, after which the session either asked again (you answer twice)
+or dropped it silently (the decision never lands, and nothing anywhere says one
+is outstanding).
+
+So questions are written down, and every tick's prompt carries what is still
+open — read from the store, never from what the session remembers asking:
+
+```bash
+omp-conductor decision open --question "ship 0.4.3 tonight?" \
+  --blocks "the release" --resolves-when issue-closed:132
+omp-conductor decision list
+omp-conductor decision resolve <id> --answer "yes, after #132 lands"
+omp-conductor decision withdraw <id> --reason "the release slipped a week"
+```
+
+**`--resolves-when` is the part that makes a parked question wake up.** Three
+conditions, each one something this package can check without asking you:
+
+| Condition | Met when |
+| --- | --- |
+| `pr-merged:<https url>` | `gh` reports that pull request merged. |
+| `issue-closed:<number>` | That issue is closed on the tracker. |
+| `npm-version:<pkg>@<version>` | `npm view <pkg>@<version> version` succeeds — the version is published. |
+
+The daemon evaluates them beside each tick, fire-and-forget: a hanging registry
+costs one unevaluated condition, never the tick. A met row is flagged in the next
+digest as `[CONDITION MET — act on this now]`, so the session acts on the answer
+at the moment it becomes actionable rather than when it happens to remember.
+
+Anything else exits `2` and lists the three forms. An unparseable condition on an
+existing row is *listed and never treated as met*: a grammar a future release
+adds must not make an old row unloadable, and a question must never be hidden by
+a condition nobody can check.
+
+**Expiry is enforced, not remembered.** An unanswered question closes itself
+after seven days — the deadline the floor's parked-amendment protocol already
+promised — so the digest stays a list of live questions instead of a graveyard.
+Answering or withdrawing is explicit, and a second resolution of the same id is
+refused rather than overwriting the first answer.
+
+`omp-conductor status` carries one row, `decisions`, reported whether or not
+anything is open: `decisions 2 open (oldest 26h)`, or `decisions none open`. A
+row that appeared only when something was outstanding would leave "it forgot to
+record the question" and "there genuinely is none" looking identical, which is
+the ambiguity this table exists to remove.
+
+## Failure classes and recovery by class (#132)
+
+Every run that did not reach a merged PR used to end at a human. The
+orchestrator re-derived the same triage on each tick — read the row, read the
+PR's checks, decide whether to requeue, re-run, settle or escalate — and then
+threw the conclusion away. Measured on this fleet's own history: **half the
+spend produced no merged PR**, and a large share of it was not implementation
+failure at all but daemon restarts, cancelled runners and a base branch moving
+under a green PR.
+
+So the daemon classifies each terminal non-success before the next dispatch,
+persists the class on the row, and performs the one recovery that class names.
+
+| Class | Signals | Recovery | Budget |
+| --- | --- | --- | --- |
+| `settlement-stuck` | a row carrying a PR that has since merged | settle: release the label, mark the row merged | none |
+| `merge-conflict` | `pushed-green`, PR open, GitHub reports conflicting | requeue for a rebase continuation | continuation |
+| `question` | the worker stopped to ask something (`blocked`) | escalate, carrying the worker's own report as evidence | none |
+| `orphan-dirty` | orphaned with a failed salvage and no operator ack | hold — recorded only; the tree is the only copy | none |
+| `orphan-clean` | orphaned with nothing uncommitted | requeue | continuation |
+| `turn-cap-progress` | at the turn ceiling **with** a PR, head or salvage commit | continue from the branch | continuation |
+| `turn-cap-spinning` | at the ceiling with no PR and no commits | escalate with the last tool calls the transcript recorded | none |
+| `admin-kill` | killed *below* its own ceiling — a restart or a drain | requeue | none |
+| `ci-infra` | PR open, every unresolved check cancelled / timed out / stale | re-run the failed jobs | none |
+| `ci-deterministic` | PR open, a check genuinely reports `FAILURE` | escalate with the failing check names and links | failed attempt |
+| `unknown` | anything unrecognised | escalate | as recorded |
+
+**Unknown escalates; it never silently retries.** A shape this table does not
+recognise is a gap in the table, and a quiet requeue would spend a budget on a
+cause nobody has named — the behaviour this exists to end.
+
+### The budgets follow the cause
+
+`failuresFor` (implementation attempts) excludes `ci-infra` and
+`settlement-stuck`; `continuationsFor` excludes `admin-kill` and
+`settlement-stuck`. A merge conflict *is* charged as a continuation, because a
+rebase is real work — just never as a failed implementation attempt.
+
+An **unclassified** row (every row written before 0.4.3) counts exactly as it
+did before classification existed. Upgrading therefore changes no existing
+budget: the columns are additive and nullable, and a pre-0.4.3 `conductor.db`
+opens unchanged.
+
+### Stale labels are reconciled
+
+On 2026-08-09 four issues carried `agent:failed` while every one of them was
+already complete — residue of a turns-cap kill two days earlier that nothing in
+the loop ever revisited. The board counted four phantom failures while the
+genuinely stuck issues were invisible.
+
+Each tick now reconciles the three state labels against the tracker:
+
+- A **closed** issue never keeps an `agent:*` label.
+- An **open** issue carrying `failed` whose sub-issues have *all* closed loses
+  the label and gets one comment naming them, deduplicated through the same
+  notifications ledger escalations use.
+
+Positive evidence only: a tracker that cannot list answers empty, and an empty
+answer removes nothing — the label is the interlock that keeps two workers off
+one issue.
+
+### Where you see it
+
+- `omp-conductor status` grows a `failure classes (unrecovered)` block, counting
+  only rows whose recovery has *not* run. Classes rather than row states,
+  because a row state is not an issue state.
+- The board appends `[<class>]` to a card whose newest run carries one.
+- The tick prompt carries one line — `Auto-recovered since last tick: 3
+  (merge-conflict #365, admin-kill #82, …) — already handled, do not re-triage
+  these.` — so the orchestrator stops writing that paragraph by re-deriving it.
+
 ## Configuration
 
 The config lives at `$OMP_CONDUCTOR_HOME/config.json`, or
@@ -1451,8 +1581,8 @@ Field notes:
 | `escalation.orchestrator` | Optional; `"embedded"` (default) or `"external"`. `external` means an orchestrator session already runs elsewhere: the daemon starts none, and tier-1 escalations post as issue comments for that session to drain. Any other value is an error. |
 | `authority` | Optional; `{ "merge": …, "release": … }`, each `"human"` (default) or `"orchestrator"`. It grants nothing to the daemon — it words the orchestrator's standing orders and the Releases paragraph of the rendered brief, so the config and the prompt cannot disagree about who holds the merge button. Unknown keys and any other value are errors, never folded to the default. |
 | `releasePolicy` | Optional; `"none"` (default) or `"operator-brief"`. `none` installs a pre-tool-call tripwire in worker, embedded-orchestrator and external-orchestrator sessions. It blocks `git tag`, tag pushes, package publishing, GitHub release creation and recognised deploy commands before execution. `operator-brief` opens that gate only for the procedure in the operator-owned brief. Unknown values are errors. Every rejection is written to `release-policy-blocks.jsonl`; the heartbeat carries that day's count into the daily digest so configured intent and observed behaviour cannot drift silently. This is the mechanical gate; `authority.release` still says who owns the decision. |
-| `reporting.scope` | Optional; `"material"` (default) or `"escalations"`. Every orchestrator tick appends the matching constraint line to its prompt, re-read from this file each tick — see [Your workflow vs. the package](#your-workflow-vs-the-package). It constrains what the session is told to report; it is not an outbound filter. A config written without the key keeps reporting material events. Any other value is an error, never folded to the default. |
-| `orchestratorReadPaths` | Optional; an array of absolute (or `~`-prefixed) paths the orchestrator session may additionally **read**. The orchestrator's structured file tools are default-refusal — see [Orchestrator confinement](#orchestrator-confinement-default-refusal) — and this is the only way to widen that allowlist. It grants reads, never writes, and it cannot re-open a denied root: an entry pointing at `workspaceRoot`, `mirrorRoot` or the installed package is still refused. A relative entry is an error rather than something resolved against whichever cwd happened to read the file. |
+| `reporting.scope` | Optional; `"material"` (default), `"decisions"` or `"escalations"`. Every orchestrator tick appends the matching constraint line to its prompt, re-read from this file each tick — see [Your workflow vs. the package](#your-workflow-vs-the-package). It constrains what the session is told to report; it is not an outbound filter. A config written without the key keeps reporting material events — a release never turns an existing fleet's volume down on its own. Any other value is an error, never folded to the default. |
+| `orchestratorReadPaths` | **Retired in 0.4.3.** Still accepted in a config and ignored, so a fleet carrying it upgrades without an edit. It widened the orchestrator's file-tool allowlist; there is no allowlist any more — the orchestrator is [unconfined by design](#the-orchestrator-is-unconfined-deliberately). |
 | `policy` | Optional; the gating conditions a merge or a release must satisfy, in two sections — `policy.merge` and `policy.release`. Any member may be omitted and the loader fills it from the strict default; an unknown key in either section, or a value outside its vocabulary, is an error naming the field, never a silent downgrade. See [Merge and release preconditions](#merge-and-release-preconditions-policy). |
 | `workspaceRoot` / `mirrorRoot` | Optional; default to `worktrees/` and `mirrors/` under the state directory. `~` is expanded. |
 
@@ -1748,6 +1878,10 @@ omp-conductor extend <issue> --turns N [--project NAME]
 omp-conductor unblock <issue> [--force] [--project NAME]
 omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
 omp-conductor report --text TEXT [--kind material|digest] [--project NAME]
+omp-conductor decision open --question TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
+omp-conductor decision resolve <id> --answer TEXT [--project NAME]
+omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
+omp-conductor decision list [--project NAME]
 omp-conductor daemon [--once] [--port N] [--project NAME]
 omp-conductor pause
 omp-conductor resume
@@ -1762,7 +1896,7 @@ omp-conductor help
 | `stop` | 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` | Prefer `systemctl restart` when the unit owns the live pid so the replacement stays supervised; otherwise `stop` then `start`, inheriting the running daemon's port and project unless a flag overrides them. 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]` | 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. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. |
-| `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / optional `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, and bounded hold groups; API failures are marked `DEGRADED` so queue starvation cannot look idle. 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. |
+| `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `boundary` / `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, and bounded hold groups; API failures are marked `DEGRADED` so queue starvation cannot look idle. 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]` | Every [mediated-verb](#the-mediated-verbs-126) call and how the daemon decided it: the verb, the arguments it was given, allow or refuse, the named refusal reason, and any resulting SHA. Sessions cannot push, open a PR, merge, label or release except through those verbs, so this is the record of what they *tried* as well as what they did — the thing an escalation cites. Reads (`conductor_pr_status`) are deliberately absent: a poll every thirty seconds would bury the refusals. `--issue` narrows to one issue's run; `--limit` defaults to 50. The newest few also appear in `status`. |
 | `board [--project NAME]` | 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, and the last 24 hours of Merged and History. 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 [--project NAME]` | Soft stop: pause claiming **and** disarm ticks. Daemon and pane stay up. Prefer this over `pause` when the intent is "stop the conductor" without killing processes. See [Stop the conductor](#stop-the-conductor-hold--halt). |
@@ -1775,6 +1909,10 @@ omp-conductor help
 | `unblock <issue> [--force]` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again. `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 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. **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. |
 | `friction <kind> --detail TEXT [--issue N]` | 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]` | Hand a rendered report to the daemon's durable outbox. The text is persisted **before** anything is sent and the command prints a report id; the daemon then owns delivery, retries on a bounded backoff, and records the Telegram message id it actually got back. Delivery is [at-least-once](#report-delivery-the-outbox) — a crash mid-send is retried and the retry says it may be a repeat — so `delivered` is never proof of exactly one message. `--kind digest` is accepted at most once per local day, decided from the ledger rather than from what the session remembers sending; an unknown `--kind` exits `2` rather than quietly becoming a material report. Anything undelivered shows in `status` with its age. |
+| `decision open --question TEXT [--blocks TEXT] [--resolves-when COND]` | 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>`, `issue-closed:<n>`, or `npm-version:<pkg>@<version>`; anything else exits `2` listing the three forms. See [The decision ledger](#the-decision-ledger-136). |
+| `decision resolve <id> --answer TEXT` | 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]` | Close a question the session stopped needing, with why. Same guard as `resolve`. |
+| `decision list` | Open questions, oldest first: id, age, what each blocks, whether its condition is met, and the question. Prints `no open decisions` when there are none. |
 | `daemon` | 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` | 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. |
@@ -1787,7 +1925,7 @@ omp-conductor help
 | `brief-upgrade` | Inspect the package-floor + `POLICY.md` overlay. Reports by default; see [Keeping a brief current](#keeping-a-brief-current). |
 | `--migrate` | Only for `brief-upgrade`. Lift a bannered `ORCHESTRATOR.md` owned half into `POLICY.md` and recompose. Dry-run unless `--apply`. |
 | `--retrofit` | Only for `brief-upgrade`. Propose (or with `--apply`, write) a `YOURS TO EDIT` banner before the first owned-topic heading on a hand-written brief. |
-| `--apply` | Only for `brief-upgrade`. Confirms `--migrate` / `--retrofit`, or legacy single-file merge above the banner. |
+| `--apply` | Only for `brief-upgrade`. Confirms `--migrate` / `--retrofit`. On its own it exits `2`: the legacy single-file merge was removed in 0.4.3. |
 | `--file PATH` | Only for `brief-upgrade`. Check a brief that is not where the wizard would have put it, on a host that may have no config at all. |
 | `help`, `--help`, `-h` | Print usage. An unknown or missing verb prints it too, and exits `2`. |
 
@@ -1935,46 +2073,47 @@ Until that uid exists, a root-or-operator daemon still has a mechanical
 worktree gate on structured tools and an integrity tripwire on its own package —
 but `bash` plus host credentials remain a prompt-and-deploy problem.
 
-### Orchestrator confinement (default refusal)
+### The orchestrator is unconfined, deliberately
+
+There is **no mechanical file gate on the orchestrator session**, and that is an
+operator decision rather than an omission (#143).
+
+A previous release jailed it to an allowlist. That gate could only ever be
+installed by `createLocalSession`, so it existed exactly in the sessions this
+daemon spawns — and the supported shape for a heartbeat orchestrator is an
+`omp` session the operator starts themselves, which never had it. A boundary
+present in one deployment out of two is not a boundary, and the brief asserting
+it was absolute was the worse half of the bug: a session that believes it is
+gated stops checking itself.
 
-The orchestrator cannot be jailed to its `cwd` the way a worker is: it has to
-read the state directory, the composed `ORCHESTRATOR.md`, `POLICY.md` and the
-config. So it gets the other shape — **an allowlist, for reads as well as
-writes, where anything unmatched is refused.** A deny-list would only stop the
-paths somebody thought to name and would leave the structured tools pointed at
-the rest of the filesystem.
+What holds the orchestrator instead:
 
-| | Paths |
+| | |
 | --- | --- |
-| **Readable** | The state directory (store, logs, claim files, session transcripts), the composed brief, `POLICY.md`, the config, and the heartbeat's own `.conductor-tick*.json` files beside the briefs — plus every root in [`orchestratorReadPaths`](#configuration). |
-| **Writable** | The state directory, and `POLICY.md` (the Learning loop amends it after you say yes). The composed `ORCHESTRATOR.md` is regenerated from the package floor each tick, so it is deliberately not writable. |
-| **Denied, outranking every allow entry** | `workspaceRoot/**` — every worker checkout — the mirror cache, the installed `omp-conductor` package, and *writes* to `config.json` itself: the config declares the session's own jail, grants and authority, so it is readable but only an operator changes it. |
-
-Denial is checked *after* the allowlist is consulted and *wins over it*, which
-is the point: an `orchestratorReadPaths` entry pointing at `workspaceRoot` or at
-the package buys nothing. Reading another run's tree is denied rather than
-merely un-writable on purpose — it is how the orchestrator ends up reasoning
-about uncommitted work whose provenance it cannot see, and it has the PR for
-the parts that matter.
-
-Every root is computed from your config, never hardcoded: move the state
-directory with `$OMP_CONDUCTOR_HOME`, or point `workspaceRoot` somewhere else,
-and the jail moves with it. A refusal names the path and the roots that *are*
-allowed — a worktree refusal names the individual run's checkout — so a session
-can correct itself in one turn instead of probing. Refusals are appended to
-`orchestrator-confinement-refusals.jsonl` in the state directory and today's
-count appears in `omp-conductor status` as a `confine` line; an orchestrator
-being refused repeatedly is misbriefed, and that should be visible rather than
-silent.
-
-**This is defence in depth, not the boundary.** `bash` is deliberately not
-parsed here — matching shell strings is false security — so this gate does not
-contain a determined session, and nothing in this package claims it does. The
-boundary is an OS principal for the orchestrator with no filesystem access to
-any run checkout; until that exists, what this buys is real but narrower:
-accidents are prevented, refusals are legible, and it holds on hosts where no
-uid split will ever be deployed. Package-source edits that get around it
-(through `bash`) remain covered by the integrity tripwire above, one tick late.
+| **The brief** | `ORCHESTRATOR.md`'s hard boundaries — never read or edit a worker's checkout or the mirror cache; when you need a run's code, read its PR. |
+| **The verb ledger** | Every `conductor_*` call records what was asked for and what the dispatcher decided, refusals included. `omp-conductor ledger` is the audit. |
+| **The dispatcher** | Merge, label and release authority are checked in the daemon against the operator's grant, across a process boundary, never in the prompt. |
+
+Unconfined means auditable, not licensed. `orchestratorReadPaths` is retired: it
+is still accepted in a config and ignored, so a fleet carrying it upgrades
+without editing anything.
+
+**One conditional exception, and it is a credential boundary rather than a tool
+gate.** When the *daemon* starts the orchestrator (`escalation.orchestrator:
+"embedded"`) on a fleet whose `credentials.isolation` resolves to an isolating
+mechanism, that session also runs as its own OS principal with
+`workspaceRoot`, `mirrorRoot` and the host credential denied — a syscall-level
+refusal `bash` cannot talk its way around, which is why it is worth keeping
+where it applies. It does not apply to an external orchestrator, and it does not
+apply on a host `status` reports as `unprotected`. The installed package is
+readable either way: reading your own dispatcher's source to file an accurate
+bug is exactly what should never be refused (#143).
+
+The workers are the sessions that are gated — a mechanical worktree confinement
+on structured tools, plus their own OS principal under
+`credentials.isolation: "per-run"`. That asymmetry is the design: a worker is
+dispatched code it did not write and runs unattended, while the orchestrator is
+the session the operator is reading.
 
 ## The mediated verbs (#126)
 
@@ -2357,13 +2496,13 @@ Known and deliberate in this version:
 - **Workers stop at green PRs.** They never merge, release or deploy. Those
   actions default to a human, but setup may grant either to the orchestrator;
   `authority` never grants them to a worker or the dispatch daemon.
-- **Both confinement gates are partial.** Structured `write` / `edit` / `read` /
-  `grep` / `glob` calls are gated by an inline harness extension — a worker to
-  its worktree, [the orchestrator to an allowlist](#orchestrator-confinement-default-refusal).
-  `bash` is gated in neither: a shell one-liner can still leave the tree, and no
-  claim in this README says otherwise. Prefer a
-  [least-privilege worker uid](#least-privilege-worker-uid-deploy) and a separate
-  OS principal for the orchestrator; the
+- **The worker gate is partial, and the orchestrator has none.** A worker's
+  structured `write` / `edit` / `read` / `grep` / `glob` calls are gated to its
+  worktree by an inline harness extension; `bash` is not, so a shell one-liner
+  can still leave the tree, and no claim in this README says otherwise. The
+  orchestrator is [unconfined on purpose](#the-orchestrator-is-unconfined-deliberately)
+  — its boundaries are its brief and the verb ledger. Prefer a
+  [least-privilege worker uid](#least-privilege-worker-uid-deploy); the
   [integrity tripwire](#integrity-tripwire-package-self-hash) still pages if the
   installed package itself changes under a live daemon.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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.",

package/src/board.ts

@@ -415,7 +415,12 @@ function runCardLines(run: RunRecord, snapshot: BoardSnapshot): string[] {
   const endedAt = run.endedAt ?? snapshot.now;
   const duration = humanDuration(endedAt - run.startedAt);
   const lines = [
-    `#${run.issue} · ${run.repo}`,
+    // The class, when the sweep has attached one and nothing has recovered it
+    // yet (#132): a row state says "failed", which four completed issues on this
+    // fleet also said. The class says which of the two this is.
+    run.failureClass === undefined || run.recoveredAt !== undefined
+      ? `#${run.issue} · ${run.repo}`
+      : `#${run.issue} · ${run.repo} [${run.failureClass}]`,
     `attempt ${run.attempt} · ${run.turns}/${run.maxTurns}t`,
     `$${run.spendUsd.toFixed(2)} · ${duration}`,
   ];

package/src/brief-upgrade.ts

@@ -103,13 +103,6 @@ export function isPhraseChromeLine(line: string): boolean {
   return BANNER_CHROME_MARKERS.some((marker) => lower.includes(marker.toLowerCase()));
 }
 
-/**
- * @deprecated Prefer {@link isPhraseChromeLine}. Separators alone are not chrome.
- */
-export function isKnownBannerChromeLine(line: string): boolean {
-  return isPhraseChromeLine(line);
-}
-
 /**
  * Drop a leading **known package footer fragment** from an owned half / POLICY.md.
  *
@@ -156,9 +149,6 @@ export function stripLeadingBannerCrumbs(text: string): string {
   return lines.slice(i).join("\n");
 }
 
-/** @deprecated Use {@link stripLeadingBannerCrumbs}. Kept for call-site stability. */
-export const stripLeadingHtmlComments = stripLeadingBannerCrumbs;
-
 /**
  * Splits on the banner, or returns `undefined` when there is none.
  *
@@ -253,53 +243,6 @@ export function renderBriefTemplate(template: string, vars: Record<string, strin
   });
 }
 
-/** What a check found, and what a caller may do about it. */
-export type BriefStatus =
-  | { kind: "current" }
-  /** Banner present and the shipped half differs: a merge is exact. */
-  | { kind: "mergeable"; merged: string; liveShipped: string; freshShipped: string }
-  /** No banner, so the boundary is unknown and only reporting is honest. */
-  | { kind: "unsplittable"; missing: string[] }
-  /** Template never rendered, so merging it would write `{{PROJECT}}` into a brief. */
-  | { kind: "unrendered"; missing: string[] }
-  /** Overlay already active: floor refreshes from package; policy is POLICY.md. */
-  | { kind: "overlay"; policyPath: string; orchestratorPath: string };
-
-/**
- * Compares a live brief against the freshly rendered template.
- *
- * Prefer {@link inspectBriefLayout} once a fleet has `POLICY.md`. This path
- * remains for pre-overlay single-file briefs.
- */
-export function checkBrief(live: string, rendered: string): BriefStatus {
-  const liveHalves = splitBrief(live);
-  const freshHalves = splitBrief(rendered);
-
-  // A template without the banner is expected in the overlay world (floor-only).
-  // When the *live* brief still has a banner, compare using composed rendered text
-  // that includes the compose banner so migrate remains available.
-  if (liveHalves === undefined) {
-    return { kind: "unsplittable", missing: missingSections(live, rendered) };
-  }
-  if (freshHalves === undefined) {
-    // Floor-only rendered template: live bannered brief wants migrate, not merge.
-    return { kind: "unsplittable", missing: missingSections(live, rendered) };
-  }
-
-  if (PLACEHOLDER_PATTERN.test(freshHalves.shipped)) {
-    return { kind: "unrendered", missing: missingSections(live, rendered) };
-  }
-
-  if (liveHalves.shipped === freshHalves.shipped) return { kind: "current" };
-
-  return {
-    kind: "mergeable",
-    merged: freshHalves.shipped + liveHalves.owned,
-    liveShipped: liveHalves.shipped,
-    freshShipped: freshHalves.shipped,
-  };
-}
-
 /** Layout of brief files under a workspace root. */
 export type BriefLayout =
   | { kind: "overlay"; policyPath: string; orchestratorPath: string }
@@ -437,17 +380,6 @@ export function writeWithBackup(
   return backup;
 }
 
-/**
- * Writes the merged brief, storing the previous one under conductor state.
- *
- * @deprecated Prefer {@link migrateToPolicy} / overlay refresh. Kept for
- * pre-overlay `--apply` on bannered single-file briefs.
- */
-export function writeMergedBrief(path: string, merged: string, backupRoot?: string): string {
-  const backup = writeWithBackup(path, merged, backupRoot);
-  return backup ?? `${path}.bak-missing`;
-}
-
 /** Result of migrating a bannered ORCHESTRATOR.md into POLICY.md. */
 export interface MigrateResult {
   policyPath: string;
@@ -647,67 +579,72 @@ export function applyRetrofit(path: string, proposal: RetrofitProposal, backupRo
   return backup ?? `${path}.bak-missing`;
 }
 
-/** The check rendered for a terminal, including what to do next. */
-export function formatBriefStatus(path: string, status: BriefStatus): string {
-  if (status.kind === "overlay") {
+/**
+ * The layout rendered for a terminal, including what to do next.
+ *
+ * One report for the four layouts `inspectBriefLayout` can return, because that
+ * is now the only classifier. The pre-overlay pair it replaced described two
+ * further states ("mergeable", "current") that only the deleted single-file
+ * merge could act on (#131).
+ */
+export function formatBriefReport(path: string, layout: BriefLayout, missing: readonly string[]): string {
+  if (layout.kind === "overlay") {
     return [
       `brief overlay active`,
       "",
-      `  floor        package template → recomposed into ${status.orchestratorPath} each tick`,
-      `  policy       ${status.policyPath} (Learning loop / operator edits)`,
+      `  floor        package template → recomposed into ${layout.orchestratorPath} each tick`,
+      `  policy       ${layout.policyPath} (Learning loop / operator edits)`,
       "",
       "Protocol updates: upgrade omp-conductor in this host's existing install root (same package manager), then restart the daemon — no brief-upgrade --apply.",
       "Legacy migrate:   omp-conductor brief-upgrade --migrate",
     ].join("\n");
   }
 
-  if (status.kind === "current") {
-    return [`brief ${path}`, "", "up to date — its shipped half matches this version of the template."].join("\n");
+  if (layout.kind === "missing") {
+    return [
+      `brief ${path}`,
+      "",
+      "No brief here yet. Run /conductor setup and say yes to writing ORCHESTRATOR.md;",
+      "it writes POLICY.md beside it, which is the half you then own.",
+    ].join("\n");
   }
 
-  if (status.kind === "mergeable") {
+  if (layout.kind === "legacy-bannered") {
     return [
       `brief ${path}`,
       "",
-      "Legacy single-file brief: this version ships a different half above the YOURS TO EDIT",
-      "banner. Prefer migrating to the POLICY.md overlay:",
+      "Legacy single-file brief: one file with a YOURS TO EDIT banner, from before the",
+      "floor and the policy were separate files.",
       "",
-      shippedDiff(status.liveShipped, status.freshShipped),
+      "Migrate:  omp-conductor brief-upgrade --migrate --apply",
       "",
-      "Migrate:  omp-conductor brief-upgrade --migrate",
-      "Or apply the old single-file merge:  omp-conductor brief-upgrade --apply",
-      "The previous file is kept beside it as ORCHESTRATOR.md.bak-<timestamp>.",
+      "That lifts everything below the banner into POLICY.md and recomposes",
+      "ORCHESTRATOR.md from the package floor plus that policy — after which the floor",
+      "tracks the installed package on its own. The previous file is kept under",
+      `${briefBackupDir()}.`,
     ].join("\n");
   }
 
-  const lines = [`brief ${path}`, ""];
-  lines.push(
-    ...(status.kind === "unrendered"
-      ? [
-          "The shipped template still carries its {{PLACEHOLDER}} coordinates, because no",
-          "project config resolved on this host. Merging it would write those literals",
-          "into a live standing prompt, so this can only be reported on. Run it with",
-          "--project on a host that has the config to apply an upgrade.",
-        ]
-      : [
-          "This brief has no YOURS TO EDIT banner, so it was written by hand or predates",
-          "the template split. There is no way to tell which lines are yours, so nothing",
-          "will be rewritten automatically.",
-          "",
-          "Retrofit a banner at the first Releases/Project context/Reporting/Amendments",
-          "heading, then migrate:",
-          "  omp-conductor brief-upgrade --retrofit",
-          "  omp-conductor brief-upgrade --migrate",
-        ]),
-  );
-  if (status.missing.length === 0) {
+  const lines = [
+    `brief ${path}`,
+    "",
+    "This brief has no YOURS TO EDIT banner, so it was written by hand or predates",
+    "the template split. There is no way to tell which lines are yours, so nothing",
+    "will be rewritten automatically.",
+    "",
+    "Retrofit a banner at the first Releases/Project context/Reporting/Amendments",
+    "heading, then migrate:",
+    "  omp-conductor brief-upgrade --retrofit --apply",
+    "  omp-conductor brief-upgrade --migrate --apply",
+  ];
+  if (missing.length === 0) {
     lines.push("", "It already has a heading for every section the template ships.");
     return lines.join("\n");
   }
   lines.push(
     "",
-    `Sections the shipped template has and this brief does not (${status.missing.length}):`,
-    ...status.missing.map((h) => `  - ${h}`),
+    `Sections the shipped template has and this brief does not (${missing.length}):`,
+    ...missing.map((h) => `  - ${h}`),
     "",
     "Merge the ones you want by hand, or ask the session running from this brief to",
     "propose them through its own amendment protocol.",