omp-conductor 0.3.25 → 0.4.0

package/README.md

@@ -568,31 +568,36 @@ Per tick, for the daemon's project:
    its issue but not a slot: its worker is finished, and counting pushed PRs
    would let two completed workers stop the fleet.
    If no slot is free, the tick logs and returns.
-8. **Admit issues** up to the free slots, skipping any issue that already has
+8. **Check the plan allowance.** If `caps.planUsage` names a window, the daemon
+   reads it (cached, see [Caps](#caps)) and holds *every* candidate under
+   `plan-usage-cap` when the window is at or over its threshold. Unlike the
+   spend cap this does **not** pause the daemon: the window resets on the
+   provider's clock, so dispatch resumes by itself.
+9. **Admit issues** up to the free slots, skipping any issue that already has
    an active run — including a pending or green PR, so a second attempt cannot
    land on a live PR. Repeated implementation failures consume
    `maxAttemptsPerIssue`; cap kills, daemon orphans and answered blocks consume
    the independent `maxContinuationsPerIssue`. Exhausting either escalates.
-9. **Ask the tracker whether the work already exists.** For each candidate that
-   survived step 8 — so at most one API call per free slot, never one per queued
-   issue — the daemon asks whether an **open** PR already closes it. An open PR
-   normally holds the issue. One narrow exception permits a routed continuation:
-   the latest run must be terminal, and the open PR must be that run's retained
-   work — either the PR URL it recorded or a PR opened on the branch it retained.
-   The branch half matters because a run can be cap-killed before its worker ever
-   opens a PR, leaving a retained branch and no recorded URL; a PR pushed to that
-   branch afterwards is still the continuation target. Drafts count because their
-   branch can hold the only copy of the work.
-   The tracker also finds work missing from a new, moved, restored, or cleared
-   store. If the check fails, the candidate is **held**, not admitted, and
-   retried next tick: the cost of holding is five minutes, the cost of admitting
-   on an unknown is a burned attempt and a duplicate PR. Only that candidate is
-   held, so a flaky API cannot stall the rest of the queue.
-10. **Record the pass.** Persist ready/routed/admitted counts and group every hold
+10. **Ask the tracker whether the work already exists.** For each candidate that
+    survived step 9 — so at most one API call per free slot, never one per queued
+    issue — the daemon asks whether an **open** PR already closes it. An open PR
+    normally holds the issue. One narrow exception permits a routed continuation:
+    the latest run must be terminal, and the open PR must be that run's retained
+    work — either the PR URL it recorded or a PR opened on the branch it retained.
+    The branch half matters because a run can be cap-killed before its worker ever
+    opens a PR, leaving a retained branch and no recorded URL; a PR pushed to that
+    branch afterwards is still the continuation target. Drafts count because their
+    branch can hold the only copy of the work.
+    The tracker also finds work missing from a new, moved, restored, or cleared
+    store. If the check fails, the candidate is **held**, not admitted, and
+    retried next tick: the cost of holding is five minutes, the cost of admitting
+    on an unknown is a burned attempt and a duplicate PR. Only that candidate is
+    held, so a flaky API cannot stall the rest of the queue.
+11. **Record the pass.** Persist ready/routed/admitted counts and group every hold
     under a stable reason code with at most five sample issue numbers. Tracker
     failures mark the summary `DEGRADED`; capacity, sibling, open-PR and budget
     holds remain normal policy state.
-11. **Dispatch** the admitted issues concurrently.
+12. **Dispatch** the admitted issues concurrently.
 
 Then, per admitted issue:
 
@@ -763,6 +768,54 @@ issues carrying `agent:in-progress`, which eligibility reads as "a worker owns
 this" — with the brief forbidding the orchestrator from editing a state label and
 `unblock` declining to clear that one, neither issue could ever be claimed again.
 
+### The settlement audit
+
+Verifying `state: pushed-green` left two lines of the same report still taken on
+faith. The worker brief asks for them and, until this existed, nothing read them:
+
+```
+gates:   <exact commands run and their results>
+changed: <files touched, one line>
+```
+
+So at settlement the daemon fetches the pull request's diff and checks the report
+against it. What it finds is a **settlement audit flag** — advisory, never a
+gate. A flagged run settles exactly as an unflagged one does; nothing here can
+change a run's state, hold a merge, or spend an attempt.
+
+| Flag | Raised when |
+| --- | --- |
+| `undisclosed-file` | The PR touched a file the `changed:` line never named. Lockfiles are exempt — they are derived from a manifest the report did disclose. |
+| `changed-line-missing` | The report had no usable `changed:` line at all. One flag, not one per file. |
+| `unmatched-claim` | `changed:` named a path the PR never touched. The weaker direction, and reported as such. |
+| `test-file-deleted` | A test file left the tree with no rename to account for it. |
+| `test-disabled` | A `.skip` / `.only` / `xit` / `@pytest.mark.skip` / `t.Skip` marker appears on a line the PR added. |
+| `assertions-removed` | An assertion was commented out, or a test file lost more assertions than it gained. |
+| `test-timeout-raised` | A named timeout in a test file went up — compared against its own previous value, so a brand-new timeout is not a finding. |
+
+A flag on a test file the dispatching issue never names is marked
+`[unattributed]`: that is the "don't weaken tests you didn't write" case, and it
+is the one worth reading first.
+
+Flags reach you three ways: appended to the settlement report, stored on the run
+row and shown under the run in `omp-conductor status` for as long as its PR is
+open, and — once per flagged settlement — as a tier-1 escalation to the
+orchestrator, whose brief says what judgement each flag invites.
+
+**A clean, accurately reported PR produces nothing.** That is a design
+constraint, not an aspiration: an audit that fires on honest work gets muted, and
+a muted audit is worse than none because the fleet still believes it is being
+checked. Every rule resolves ambiguity towards silence, and each accepts a named
+blind spot to stay quiet — a renamed test file is not a deleted one (even when
+git did not detect the rename, matched by basename), a `.skip` inside a string
+literal or a recorded fixture is not a skip, and a rewritten test that keeps its
+coverage is not a weakening.
+
+The analyser is pure: it takes a parsed diff, the report and the issue text, and
+returns flags. Only `Tracker.prDiff` touches the network, and a diff it cannot
+read produces no flags *and says so* — silence about a diff nobody read is not a
+clean bill.
+
 ### Continuation runs
 
 When a worktree is provisioned onto a branch that already exists in the mirror
@@ -852,6 +905,7 @@ rest. `0` is a real value (a hard stop), not "unset".
 | --- | --- | --- |
 | `maxConcurrentWorkers` | `2` (setup may write `1` on &lt;16 GiB hosts) | Parallel in-process omp sessions inside the daemon PID. Two, because **CI runner slots, not model tokens, are the usual throughput ceiling** — a third worker would starve its own PR checks on a small self-hosted runner pool. On hosts under ~16 GiB RAM, prefer `1` so the unit stays out of swap ([host sizing](#host-sizing-and-memory)). Raise it only if you actually have the runners *and* the RAM. |
 | `dailySpendUsd` | `25` | Rolling-day spend ceiling in USD, or `null` for no spend gate. `0` is a hard stop. Metered from assistant `usage.cost.total`. |
+| `planUsage` | `null` (unmetered) | Subscription/plan allowance guard: `{ "windowId": "anthropic:7d", "maxUsedFraction": 0.85 }`, or `null` for no plan gate. Independent of `dailySpendUsd` — see [Plan allowance](#plan-allowance-planusage) below. |
 | `workerMaxTurns` | `120` | Startup ceiling for each new worker. Catches a session looping without converging; use `omp-conductor extend` to raise one live run without changing this default. |
 | `workerWallClockMs` | `5400000` (90 minutes) | Wall-clock ceiling for one worker. A session that is merely stuck spends no turns, so turns alone cannot detect it. |
 | `maxAttemptsPerIssue` | `2` | Failed implementation or CI attempts before escalation. Operational stops do not consume this budget, so salvage can continue without stealing the retry needed for a real failure. |
@@ -875,6 +929,83 @@ effective value is persisted and shown beside that active run in `status`; editi
 flight. A cap that fires aborts the run, records it as `killed`, and names the
 ceiling in the escalation.
 
+### Plan allowance (`planUsage`)
+
+`dailySpendUsd` meters money, which is the only thing an API-billed account can
+run out of. A fixed-price subscription cannot be expressed that way: the real
+ceiling is a **provider allowance** — a weekly token window whose marginal
+dollar cost is zero and whose exhaustion stops every session on the host.
+Pricing that into the dollar meter would mean inventing a number.
+
+`planUsage` is the second, independent guard. It reads `omp usage --json` — the
+structured form of the harness `/usage` view — and holds new claims while the
+named window is at or over its threshold. Running workers finish normally, and
+**the daemon is not paused**: the window resets on the provider's clock, so
+dispatch resumes by itself once a fresh reading is below the threshold. Nothing
+estimates a plan quota from conductor's own transcript token counts.
+
+```json
+"caps": {
+  "planUsage": { "windowId": "anthropic:7d", "maxUsedFraction": 0.85 }
+}
+```
+
+**Naming the window.** `limits` in the payload is a *list*, not a single
+number: one Anthropic account reports `anthropic:5h`, `anthropic:7d` and the
+tier-scoped `anthropic:7d:fable` at the same time, and other providers add
+their own. So the cap names its window rather than taking whichever entry came
+first. Run this on the fleet host and copy an `id`:
+
+```bash
+omp usage --json | jq -r '.reports[].limits[] | "\(.id)  \(.amount.usedFraction)  \(.amount.unit)"'
+```
+
+A bare window key (`"7d"`) also works, but **only** when exactly one reported
+allowance carries it. On an Anthropic account `7d` matches two, and the guard
+refuses to guess.
+
+**`maxUsedFraction` is a fraction, not a percentage.** `0.85` holds at 85%.
+A value outside `0`–`1` is rejected at config load, because `85` would mean
+"hold at 8500% consumed" — a guard that reads as configured and can never fire.
+Comparison always goes through the provider's `usedFraction`, never a raw
+count: `unit` is `percent` for Anthropic and `unknown` with raw counts for
+`xai-oauth`, so a threshold compared against `used` misreads any non-percent
+provider by orders of magnitude.
+
+**Availability policy.** The guard never displays a number it did not read, and
+never shows a fabricated `0% used`. What each situation does:
+
+| Situation | `status` / `board` | New claims |
+| --- | --- | --- |
+| `planUsage: null` | `unmetered` | admitted |
+| Window below threshold | `5% / 85% of anthropic:7d used · resets in 6d 2h` | admitted |
+| Window at or over threshold | same, plus `holding new claims` | **held** (`plan-usage-cap`, Tier 1) |
+| No provider reports a readable allowance, or `omp usage --json` fails | `unavailable — <reason>` | admitted for up to 30 minutes, then **held** and paged at Tier 2 |
+| `windowId` names a window the reading does not contain | `window "<id>" is not in this reading — Reported: …` | **held**, Tier 2 |
+| `windowId` matches more than one allowance | `window "<id>" matches …` | **held**, Tier 2 |
+| The window reports nothing a fraction can be derived from | `window "<id>" reports no comparable fraction …` | **held**, Tier 2 |
+
+The split is deliberate. A *read error* is transient — a token refresh, a
+provider 502, `omp` briefly absent mid-upgrade — and stalling a fleet on one
+would cost more than admitting through it, since spend, turns, wall clock and
+concurrency are all still enforced. Half an hour of continuous failure is not
+an outage, it is a broken meter, and a plan-capped fleet running on a broken
+meter is how the allowance gets spent to zero unnoticed. A *successful* read
+that does not contain the configured window is not a read error at all: the
+source answered, and it says the config names something that is not there. That
+fails closed immediately, like every other config fault in this package, and
+recovers by itself as soon as a reading contains the window again.
+
+Readings are cached for 60 seconds (15 for a failure) so one tick costs one
+provider call rather than one per candidate, and a cached reading is dropped
+the moment its own `resetsAt` passes — that is what makes admission resume at
+the rollover instead of a TTL later. `omp usage invalidate` clears omp's own
+cache; conductor picks the change up at its next read.
+
+Both controls are shown separately, never folded together — `status` prints a
+`spend today` row and a `plan usage` row, and the board's admission line ends
+with `spend $2.40/$25.00  |  plan 5%/85%`.
+
 ## Worker model
 
 `workerModel` on a project pins the model its workers run on, as a pattern in
@@ -1054,6 +1185,123 @@ If `fallbackToIssueComment` is off and no Telegram transport is configured,
 delivery throws instead of dropping silently. The failure is logged and retried,
 because a swallowed escalation looks exactly like a healthy fleet.
 
+## Report delivery (the outbox)
+
+Escalations are the daemon's. **Reports** — the material events and the daily
+digest your [`reporting.scope`](#your-workflow-vs-the-package) asks for — are
+written by the orchestrator, and until v0.3.26 they were also *delivered* by it:
+a report reached you only if the model remembered to call `telegram_send`. On
+2026-08-06 a suite release and two tier-2 escalations were written that way and
+none of the three arrived, and nothing anywhere recorded that fact — an undelivered
+report and a quiet tick look identical.
+
+Authorship still needs judgement the daemon does not have, so it stays with the
+model. Delivery does not, so it moved:
+
+```bash
+omp-conductor report --text "<the whole report>"                 # one material event
+omp-conductor report --text "<the whole digest>" --kind digest   # the daily digest
+```
+
+The command writes the text into a `reports` table in the store and prints a
+report id. Nothing has been sent at that point, and that is the guarantee: the
+report survives the session being compacted, interrupted or restarted, and it
+survives the daemon being restarted under it. The daemon then delivers it over
+the same bot token tier 2 uses, with bounded retries, and `omp-conductor status`
+lists anything that has not landed.
+
+### Delivery is at-least-once, and the docs will not pretend otherwise
+
+The Telegram Bot API accepts no client-supplied idempotency key and offers the
+bot no readable record of what it has already sent. There is nothing to replay a
+request against and nothing to reconcile with, so **exactly-once delivery cannot
+be built on this transport** and this package does not claim it. `delivered` is
+proof that Telegram accepted *an* attempt, never proof that exactly one message
+exists.
+
+What it does instead is make the ambiguity explicit and always resolve it in the
+direction of the duplicate:
+
+| State | Meaning | What you do |
+| --- | --- | --- |
+| `pending` | Nothing is in flight. Never attempted, or the last attempt failed **definitively** — see below. Nobody has this report. | Nothing. It retries on a bounded backoff (30s doubling to a 15-minute floor) and `status` shows the error. |
+| `sending` | A request left this host and its outcome was never learned: the daemon died, or the request was cut off after the bytes went out. Telegram may be holding the message. | Nothing, but expect a possible duplicate. Check the chat if you want to know now. |
+| `delivered` | Telegram answered `ok: true`. The row records the message id from the response **body**, not the HTTP status. | Nothing. |
+| `failed` | The retry budget ran out — six attempts, roughly half an hour. | Fix the transport. This state pages tier 2 in its own right — see below. |
+
+The row is written `sending`, with the id of the attempt about to run, **before**
+the request is made. A crash in that window therefore leaves an explicitly
+ambiguous row rather than a silently lost one. The next daemon start sweeps every
+`sending` row, retries it, and the retried message carries the report id and a
+plain-English line saying it may already be in the chat. A duplicate you can spot
+by its report id is much the cheaper of the two mistakes; a silently dropped
+report is the entire reason this exists.
+
+#### Two kinds of failure, and only one of them is quiet
+
+A failed send is classified where the socket is watched, not by the caller, and
+the two classes are treated differently on purpose:
+
+| Outcome | What happened | Row | Retry says |
+| --- | --- | --- | --- |
+| **Definitive** — nobody has it | Telegram answered and refused it (`{"ok":false}` under any status, or a non-2xx status), or the connection never opened at all (refused, DNS failure) so the request provably never left. | back to `pending`, backoff, attempt counted | nothing special — it *is* a first attempt |
+| **Outcome unknown** — Telegram might have it | The request was cut off after it left: timeout, abort, socket reset, `EPIPE`. Or the POST came back `200` and the **response body could not be read** — Telegram had already decided and the answer was lost coming back. | stays `sending`, flagged as a possible repeat | `POSSIBLE REPEAT`, with the report id to compare against |
+
+Anything that cannot be classified confidently is treated as **outcome unknown**.
+That default is deliberate and is the safe direction: the worst case is a
+duplicate you were warned about, against a delivered report re-posted as though
+it were new, with nothing anywhere saying it might be a second copy.
+
+The half of "never double-post" that *is* achievable is enforced: a report cannot
+be **concurrently** in flight twice. Claiming a report is a conditional update,
+so only one attempt can move a `pending` row, and every terminal transition names
+the attempt it is settling — a request that answers after its row was reclaimed
+is discarded rather than allowed to overwrite a newer attempt's outcome. That is
+what stops a retry storm.
+
+### A report nobody can deliver is itself news
+
+A report that exhausts its retries is marked `failed` **and escalates as tier 2**.
+This rides the transport that just failed, which is deliberate and accepted: the
+common failure is a wrong chat id or a bot kicked from the chat, not a global
+Telegram outage, and in both of those the page reaches an operator who is
+otherwise being told nothing at all. If the whole channel is down the page
+degrades to a line in `daemon.log` and the `reports` block in `status`, which is
+then the only surface — a report has no tracker issue, so there is no issue
+comment to fall back to. The page goes through the ordinary escalation ledger and
+carries the report id, so one undeliverable report pages exactly once.
+
+### The daily digest is deduplicated from the ledger
+
+`--kind digest` is accepted at most once per **local** day, per project. The
+second hand-over on the same day is refused and told which report already holds
+the slot, including when that report has already been delivered. This is decided
+from the `reports` table, not from the model's memory of the last tick — a
+restarted or compacted session cannot send a second digest by forgetting the
+first. Material reports carry no such key: two events in a day are two events.
+
+### What `status` shows
+
+```text
+reports   1 pending · 1 sending · 0 failed (delivery is at-least-once — a retry may duplicate)
+  9f2c1ab0d3e4  pending    material  12m old  attempt 2/6, retry in 1m  (telegram sendMessage rejected: {"ok":false,…)
+  4b7c1ad9e001  SENDING    digest    3m old   attempt 1, outcome unknown — the process that sent it never said; a daemon start retries it and the message will say it may be a repeat
+```
+
+`pending` and `sending` are printed differently because they ask different things
+of you, and every row carries its age — "1 report pending since 08:15Z" is the
+signal that was missing when the reports went nowhere. Delivered reports leave
+the block: it is a list of what you are still owed, not a log.
+
+Delivery keeps running while the fleet is **paused**. Pause stops claiming, not
+your right to hear about work that already happened. It runs on its own
+thirty-second timer rather than the five-minute dispatch tick, so a report does
+not sit in the outbox for the length of a poll interval.
+
+The tier-2 escalation ledger (`notifications`) is untouched by all of this. It is
+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.
+
 ## Configuration
 
 The config lives at `$OMP_CONDUCTOR_HOME/config.json`, or
@@ -1097,6 +1345,7 @@ A complete, valid config for one project with two target repos:
   "defaults": {
     "maxConcurrentWorkers": 2,
     "dailySpendUsd": 25,
+    "planUsage": { "windowId": "anthropic:7d", "maxUsedFraction": 0.85 },
     "workerMaxTurns": 120,
     "workerWallClockMs": 5400000,
     "maxAttemptsPerIssue": 2,
@@ -1150,7 +1399,30 @@ A complete, valid config for one project with two target repos:
         "merge": "human",
         "release": "human"
       },
-      "releasePolicy": "none",
+      "releasePolicy": {
+        "git-tag": "human",
+        "git-push-tags": "human",
+        "package-publish": "human",
+        "github-release": "human",
+        "deploy": "human"
+      },
+      "credentials": {
+        "isolation": "per-run"
+      },
+      "policy": {
+        "merge": {
+          "requiredChecks": ["build", "lint"],
+          "baseFreshness": "up-to-date",
+          "drafts": "block",
+          "whenBehindBase": "update-branch"
+        },
+        "release": {
+          "requires": ["runs-settled", "no-open-prs"],
+          "requiredChecks": ["release"],
+          "artefacts": ["@acme/sdk"],
+          "environments": ["staging"]
+        }
+      },
       "reporting": {
         "scope": "material"
       },
@@ -1180,12 +1452,69 @@ Field notes:
 | `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. |
+| `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. |
 
 Prefer an SSH `cloneUrl`, or an https URL backed by a credential helper. A clone URL
 with credentials embedded is persisted into the mirror's git config, exactly as it
 would be for a hand-run clone.
 
+### Merge and release preconditions (`policy`)
+
+These used to be sentences in your `POLICY.md`: when a PR may be merged, what
+must be green, what a release requires. Prose cannot be checked, so every tick
+re-decided them by reading and interpreting them again. They are configuration
+now, `POLICY.md` keeps only judgement, and the rendered brief *describes* the
+policy instead of restating it — no threshold lives in two places.
+
+`policy.merge`:
+
+| Field | Values | Default | Means |
+| --- | --- | --- | --- |
+| `requiredChecks` | any check names | `[]` | Checks that must have concluded successfully. **Empty is the strict answer** — it means every check the PR reports, not "no checks". |
+| `baseFreshness` | `up-to-date`, `any` | `up-to-date` | Whether the head must be level with the base branch. `any` accepts a verdict produced against an older base. |
+| `drafts` | `block`, `allow` | `block` | Whether a draft PR can be merged at all. |
+| `whenBehindBase` | `update-branch`, `hold`, `escalate` | `update-branch` | What to do with a green PR that fell behind. `update-branch` runs `gh pr update-branch` and waits for the fresh run. Closing it and an admin bypass are not spellable. |
+
+`policy.release`:
+
+| Field | Values | Default | Means |
+| --- | --- | --- | --- |
+| `requires` | `runs-settled`, `no-open-prs`, `queue-drained`, `epic-children-closed` | `["runs-settled"]` | What must already have landed. Order and duplicates do not matter; the loader canonicalises. |
+| `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. |
+
+A project with no `policy` block loads as the whole default above, which is the
+strictest reading of the prose it replaced. `/conductor setup` asks for all of
+it under the **merge & release preconditions** area, so changing one condition
+costs eight prompts rather than a hand-edit — see
+[Changing one setting](#changing-one-setting).
+
+This key grants nothing. Who *may* merge or release is
+[`authority`](#configuration), and which release tool calls are mechanically
+permitted is [`releasePolicy`](#configuration). `policy` says what must be true
+before the act, whoever is doing it.
+
+#### Reasons are a closed vocabulary
+
+Where an automated verb takes a `reason`, the argument is one value out of a
+fixed set, not free text — a reason a rule matches on is a reason that decides,
+and a decision made out of a model's own wording is one no two runs spell the
+same way. A reason outside its set is refused, and the refusal names every
+accepted value.
+
+| Verb | Accepted reasons |
+| --- | --- |
+| merge | `preconditions-met`, `behind-base-refreshed`, `operator-instructed`, `release-blocking` |
+| release | `batch-complete`, `epic-closed`, `hotfix`, `operator-instructed` |
+| label change | `promoted-to-queue`, `re-briefed`, `needs-human`, `duplicate`, `superseded`, `out-of-scope` |
+
+Free-form rationale still has a home: it rides alongside as a separate
+`rationale` field, is written into the audit trail verbatim, and is never
+parsed or matched by anything.
+
 ## Orchestrator tick
 
 The escalation path above assumes an orchestrator session that is actually
@@ -1407,6 +1736,7 @@ omp-conductor stop
 omp-conductor restart [--port N] [--project NAME]
 omp-conductor upgrade [--to VERSION] [--project NAME]
 omp-conductor status [--project NAME]
+omp-conductor ledger [--issue N] [--limit N] [--project NAME]
 omp-conductor board [--project NAME]
 omp-conductor hold [--project NAME]
 omp-conductor halt [--pane] [--project NAME]
@@ -1417,6 +1747,7 @@ omp-conductor tail <issue> [--project NAME]
 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 daemon [--once] [--port N] [--project NAME]
 omp-conductor pause
 omp-conductor resume
@@ -1431,7 +1762,8 @@ 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. 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` / 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. |
+| `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). |
 | `halt [--pane] [--project NAME]` | `hold`, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `halt --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. |
@@ -1442,6 +1774,7 @@ omp-conductor help
 | `extend <issue> --turns N [--project NAME]` | Monotonically raise that live worker's effective turn ceiling through its owning daemon. The current omp session keeps running; no restart or continuation is created. The daemon persists the new ceiling for `status` and rejects missing, settled, cap-killed, equal, or lower requests instead of implying that an immutable session changed. |
 | `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. |
 | `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. |
@@ -1534,9 +1867,9 @@ dispatcher. The brief is explicit about the boundary:
 | Edit code inside its own worktree. | Weaken, skip, delete or loosen **any test it did not write** — that is a design question to escalate, and it is checked by diff review before the push. |
 | Add or update tests for behaviour it introduced. | Suppress a warning, delete an assertion, or special-case an input to make a check pass. |
 | Run the repo's configured cheap gates, each from its listed `cwd`, over the whole tree. | Run docker or image builds, production builds, browser/e2e suites, or the full test suite on the shared host — CI owns the heavy gates. |
-| Review its whole diff, then commit and **push once**. One corrective push if CI is red. | Force-push, `git add -f`, or add AI/co-author attribution. Red twice means stop and report, not push a third time. |
-| Open a PR that links the issue, and watch CI to a verdict with `gh pr checks --watch`. | Run `gh pr merge`. **A worker never merges** — that one is absolute, whoever else holds the authority — so PRs land one at a time with a freshness re-check; two workers merging concurrently is how agent PRs clobber each other. Who *may* merge is the [`authority`](#configuration) answer, and it is never the worker. |
-| Escalate: ambiguity, a cross-repo contract, a needed credential, a product or data-migration decision, a blocking existing test, CI red twice, or most of the wall-clock budget burned. | **Under the default `releasePolicy: "none"`:** cut a release, push a tag, publish to npm, edit a deployment pin, deploy, or touch infrastructure or secrets. The harness blocks recognised release/deploy tool calls before they run and audits the attempt. A project may deliberately set `operator-brief` only after its operator-owned brief contains the exact release procedure; that opens the tool gate but does not change `authority.release`. |
+| Review its whole diff, then commit and publish once with `conductor_push`. One corrective push if CI is red. | Force-push, `git add -f`, or add AI/co-author attribution. There is no force path to reach: `conductor_push` publishes that run's branch fast-forward only and takes no other ref. Red twice means stop and report, not push a third time. |
+| Open a PR with `conductor_pr_create`, and poll CI to a verdict with `conductor_pr_status`. | Run `gh pr merge` — or reach `conductor_pr_merge`, which refuses a worker session mechanically. **A worker never merges** — absolute, whoever else holds the authority — so PRs land one at a time with a freshness re-check; two workers merging concurrently is how agent PRs clobber each other. Who *may* merge is the [`authority`](#configuration) answer, and it is never the worker. |
+| Escalate: ambiguity, a cross-repo contract, a needed credential, a product or data-migration decision, a blocking existing test, CI red twice, or most of the wall-clock budget burned. | Cut a release, push a tag, publish to npm, edit a deployment pin, deploy, or touch infrastructure or secrets. `conductor_release` and `conductor_label` refuse a worker whatever `releasePolicy` says, because the check compares the caller against the configured holder rather than ruling one value out. The in-session tripwire still blocks recognised release/deploy tool calls early and audits the attempt, but it is [defence in depth](#the-mediated-verbs-126), not the gate. |
 
 The worker ends with a seven-line evidence report (issue, PR, observed head SHA,
 state, gates, changed, next). A textual `pushed-green` claim is not success: the
@@ -1545,7 +1878,7 @@ daemon repeats the PR/head/check verification before it records that state.
 ### Worker confinement and the integrity tripwire
 
 A worker session is rooted at its worktree `cwd`. **Structured file tools are
-gated mechanically:** `runWorker` asks `createSession({ confineToCwd: true })`,
+gated mechanically:** `runWorker` asks `createSession({ role: "worker" })`,
 which installs an inline harness extension that blocks `write` / `edit` /
 `read` / `grep` / `glob` when the tool's path resolves outside that worktree
 (symlink-aware). Target selection was already mechanical — only a repo in
@@ -1602,6 +1935,353 @@ 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 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.
+
+| | 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 mediated verbs (#126)
+
+With the credential boundary in place a session can no longer mutate GitHub by
+accident or by malice — and can no longer do its job either. These verbs are the
+only sanctioned way back, and the point of them is *where the checks run*: in
+the daemon, across a process boundary, not in a prompt the model can rewrite.
+
+### The verbs
+
+| Verb | Allowed caller | What the daemon checks before acting |
+| --- | --- | --- |
+| `conductor_push` | the worker owning the run | The ref is exactly `refs/heads/<that run's branch>`. Fast-forward only; there is no force argument to reject because none is declared. |
+| `conductor_pr_create` | the worker owning the run | The run has no open PR (the same guard admission uses); head is the run branch; base is the repo's configured `defaultBranch`. |
+| `conductor_pr_status` | worker or orchestrator | Read-only. A worker reads only its own run's PR. |
+| `conductor_pr_update_branch` | orchestrator, or the worker owning the run | The PR belongs to this run and project, and is open. |
+| `conductor_pr_merge` | **orchestrator only** | `authority.merge` equals the caller; `headSha` equals the live head *at execution time*; checks green at that same SHA; the project's single merge slot is free. |
+| `conductor_label` | **orchestrator only** | The label is in the project's own vocabulary. Lifecycle labels stay the daemon's. |
+| `conductor_release` | **orchestrator only** | `authority.release` equals the caller; the per-shape grant permits it; the artefact or environment was declared; the release preconditions hold; the `reason` is in the closed enum. |
+
+Merge and release are the same rule written twice on purpose: **the caller's
+role must equal the configured holder.** `authority` has exactly two values, so
+a `!== "human"` test would have let a *worker* release. A worker is refused
+every release shape under the most permissive config there is.
+
+### The transport
+
+Identity is never an argument. `project`, `run`, `issue` and the caller's role
+come from **which socket the call arrived on** plus the verified peer uid, and a
+request carrying any of those field names is refused outright, named. A worker
+on run X asking to merge run Y's PR is not merely wrong, it is unexpressible.
+
+```
+<state dir>/verbs/                 daemon-owned, mode 0711
+  run-7-9a783d877d422b9e.sock      0600, owned by run 7's principal
+  run-9-1c40e2a5b6d3f018.sock      0600, owned by run 9's principal
+  orchestrator-4b1f...c2.sock      0600, a third, distinct one
+```
+
+`0711` is load-bearing and the obvious `0700` does not work: *connecting* needs
+**search** (`+x`) on every path component, not read. Searchable by run
+principals, listable by none, and writable by none but the daemon — that last
+one is what stops a run unlinking a sibling's socket or binding an impostor in
+its place. A per-run *directory* owned by the run principal would hand exactly
+that power back, and is deliberately not used.
+
+Before binding, the daemon verifies every component of the path is owned by
+itself (or root), free of symlinks, and unwritable by anyone else; a failed
+check **refuses dispatch** rather than degrading. Where the run has its own
+principal it also verifies the chain is traversable, and says which directory to
+`chmod o+x` when it is not. Paths are unguessably suffixed, and only the daemon
+ever unlinks one.
+
+Peer credentials are asserted server-side — `getpeereid` on macOS, `SO_PEERCRED`
+on Linux — against the uid allocated for that run. A mismatch closes the
+connection with no reply and logs an impersonation attempt. Where the host has
+no per-run principals there is no distinct uid to compare, and the daemon says
+so at startup rather than implying a guarantee it is not making:
+
+```
+verb transport: verb sockets in ~/.omp/conductor/verbs (mode 711); each socket
+0600 under the daemon's own uid (no per-run principals on this host); peer uid
+asserted with getpeereid
+```
+
+**No mutation route exists on the HTTP port**, and none may be added. That
+surface is unauthenticated loopback TCP reachable by any local user; a `PUT` or
+`POST` at any verb path answers 404, pinned by a test.
+
+The child-side tool handler is a thin client only. It forwards arguments and
+renders the answer — no policy branch, no credential, no local fallback. With no
+socket it fails closed and says so, rather than reaching for `git push`.
+
+### The ledger
+
+Every mutating call is recorded with its arguments, the decision, the named
+refusal reason and any resulting SHA. Reads are not: a status poll every thirty
+seconds would bury the refusals the record exists to surface.
+
+```console
+$ omp-conductor ledger --issue 7
+acme — 3 verb call(s), 1 refused (newest first)
+  2026-08-09 11:04:12  REFUSE  conductor_pr_merge         worker #7  [role-not-allowed]
+      prUrl=https://github.com/acme/api/pull/7 headSha=9a783d8… reason=preconditions-met
+      refused: merge authority is the orchestrator's, never a worker session's.
+  2026-08-09 10:58:03  ALLOW   conductor_pr_create        worker #7
+      title=fix: settle the head check body=Closes acme/tracker#7
+      opened https://github.com/acme/api/pull/7 (conductor/issue-7 → main).
+  2026-08-09 10:57:41  ALLOW   conductor_push             worker #7  9a783d877d42
+      (no arguments)
+      pushed refs/heads/conductor/issue-7 at 9a783d877d42….
+```
+
+The newest few also appear in `omp-conductor status`, because a refused merge is
+news: it means a session tried to do something the config does not permit.
+
+`release-policy.ts` stays installed as defence in depth — it refuses early, in
+the session, with an explanation the model can act on in the same turn, and it
+leaves a durable record that something tried. It is no longer what *stops* a
+release. Treat a block there as evidence about a session's intentions; the
+daemon is what prevented it.
+
+## The credential boundary (`credentials`)
+
+Every prose rule about what a worker "may not" do reduces to one fact: until
+this existed, **model-executed code held the operator's own GitHub write
+credential.** Sessions ran inside the daemon process, as the same OS user, with
+the same `$HOME` and the same filesystem view — and the daemon authenticates by
+shelling out to the logged-in `gh`, so a worker's `bash` reached the same
+credential by running the same binary.
+
+Scrubbing `GH_TOKEN` does not fix that, and this package will not describe it as
+if it did. Code running as the same uid defeats an environment variable in one
+line (`GH_CONFIG_DIR=$HOME/.config/gh gh pr merge …`), and the login keychain,
+`~/.ssh` and `~/.git-credentials` need no environment at all. **The boundary is
+an OS principal.** The environment scrubbing that ships alongside it is
+accident-prevention: it makes the common mistakes fail immediately and legibly,
+and it stops nothing that is trying.
+
+### What actually changed
+
+- Worker and orchestrator sessions are **child processes**, launched under a
+  principal scoped to one run. They are still supervised exactly as before —
+  turn caps, wall-clock caps, spend accounting, salvage, transcript paths — and
+  a session that outlives its daemon is not possible: the child exits when its
+  control socket closes.
+- A run's checkout is **its own git repository**, borrowing objects read-only
+  from the shared mirror through git alternates. It used to be a linked worktree
+  of that mirror, which needs write access to the mirror's refs and therefore
+  handed every run write access to every other run's.
+- **Publishing is the daemon's.** The worker commits locally; the daemon fetches
+  the run branch out of the run's repository into the mirror and pushes it to
+  GitHub, fast-forward only. There is no force path anywhere in this package. A
+  rejected push settles the run `failed` with git's stderr verbatim.
+- One function, `credentialedEnv()`, is the only construction site of credential
+  material in the daemon. `gh`, the mirror's clone and fetch, the daemon-side
+  push and the mediated verbs all go through it, so "what can reach the
+  credential" is answered by its call sites rather than by an audit.
+
+### `credentials.isolation`
+
+| Value | Meaning |
+|---|---|
+| `"per-run"` | Every session runs as its own OS principal. The daemon refuses to dispatch if this host cannot provide one. |
+| `"none"` | Sessions run as the daemon's user. `status` reports the fleet as **unprotected**, every time. |
+
+There is deliberately no third value. The degraded `group-mode` mechanism below
+is something the *host probe* can report, never something a config can ask for,
+so an operator cannot believe they configured the full boundary and get the
+weaker one.
+
+**A config written before this key existed is migrated, not rejected.** On the
+first start it resolves to `"none"`, the key is written into the file
+explicitly, and the daemon logs the migration once by project name. The answer
+then lives on disk rather than being inherited from a default nobody chose — and
+no running fleet stops dispatching on upgrade. A fleet that upgrades and does
+nothing else is unprotected and says so in `status`; turning that into a refusal
+would have been an outage caused by a security feature.
+
+### `credentials.readToken`
+
+Optional, and absent by default. The boundary removes GitHub *reads* too, so a
+worker with no token works from its dispatch brief — which already carries the
+issue body and the acceptance criteria — and from the mediated verbs. Set this
+to a **read-scoped** token to give sessions `gh` reads back.
+
+This package cannot verify the scope. A write-scoped token here re-opens exactly
+the hole the rest of this section closes.
+
+### Mechanisms, and what each one does not protect
+
+The daemon probes the host at startup, states the mechanism, and proves it by
+running the composed launcher against a trivial child before reporting it
+available. A mechanism whose argv the host rejects resolves *down* at probe time
+rather than failing every dispatch at run time.
+
+| Mechanism | Where | Contains a determined escape? |
+|---|---|---|
+| `uid-pool` | Linux, with the capabilities and accounts below | **Yes** |
+| `sandbox-exec` | macOS | **Yes**, within a deprecated Apple interface |
+| `group-mode` | Linux, groups but no capabilities | **No** — cross-run separation only |
+| `none` | anywhere else | **No** |
+
+`group-mode` exists so an operator who cannot grant capabilities still gets
+cross-run checkout separation. It runs sessions as the daemon's own uid, so it
+bounds accidents and does not stop a determined same-uid escape. `status` says
+which one is live, and lists what it does not close.
+
+### Deploying `per-run` on a Linux fleet host
+
+See `systemd/omp-conductor.service.example` for the copy-pasteable version. In
+summary:
+
+1. **Capabilities on the existing unprivileged account.** The unit grants
+   `CAP_SETUID CAP_SETGID CAP_CHOWN CAP_SETPCAP`. They exist to be *dropped
+   into* run children, never inherited by them. A capability grant on the
+   `fleet` account is a narrower blast radius than running as root or shipping a
+   setuid binary.
+
+   `CAP_SETPCAP` is there solely so the launcher can empty the child's
+   capability **bounding** set, which `PR_CAPBSET_DROP` requires. A host that
+   withholds it takes a documented fallback: the launcher omits
+   `--bounding-set=-all`, the child still ends with every other set empty behind
+   `NoNewPrivs`, the leftover `CapBnd` is inert, and `status` reports it as a
+   named residual.
+
+2. **`setpriv` (util-linux) must be on `PATH`.** Every run child is launched
+   through it: group list, then gid, then uid, then empty the
+   permitted/effective/inheritable/ambient sets, drop the bounding set, set
+   `PR_SET_NO_NEW_PRIVS`, then `exec`. Without `setpriv` the probe reports
+   `none`. There is deliberately no `spawn({uid,gid})` fallback — ambient
+   capabilities survive `execve` for ordinary binaries, so a child launched that
+   way holds `CAP_SETUID` itself and can `setuid()` back to a sibling run or to
+   the daemon, voiding the boundary while appearing to work.
+
+3. **Provision with the shipped command, not by hand.**
+   `omp-conductor boundary-setup --slots <n>` prints the exact idempotent root
+   commands, generated from the same constants the startup probe checks, so the
+   instructions cannot drift from what the daemon then demands.
+
+   ```bash
+   omp-conductor boundary-setup --slots 2              # read it first
+   omp-conductor boundary-setup --slots 2 | sudo bash
+   sudo systemctl restart omp-conductor.service
+   ```
+
+   It needs no config and must run **before** `setup`: setup writes worktree and
+   mirror paths into the shared root this creates. What it establishes:
+
+4. **One account per run slot**, `conductor-agent-<n>` for each concurrent
+   worker plus `conductor-agent-orch` for the orchestrator. `maxConcurrentWorkers`
+   is 2 by default, so the pool is small. The orchestrator's account is distinct
+   precisely so it has no read or write access to any run checkout, and it is
+   launched with no supplementary group at all.
+
+5. **Two groups**, and the split between them is the whole filesystem model:
+
+   | Group | Members | Purpose |
+   |---|---|---|
+   | `conductor-daemon` | the daemon account **only** | lets it reach every run repo — fetch the branch, salvage, reclaim the tree |
+   | `conductor-runs` | every slot principal | read-only access to the shared mirror |
+
+   A slot principal must **never** be in `conductor-daemon`. That membership is
+   the only thing keeping sibling runs out of each other's checkouts, and its
+   absence is asserted from a live session by the probe suite.
+
+   Supplementary group membership is fixed when a process starts, so this
+   **requires a service restart**. Without it the daemon's live credentials lack
+   the group even though `getent` shows it, and it would chown every run repo to
+   a group it cannot itself use — the probe checks the running process's own
+   credentials for exactly this reason, and every run additionally write-tests
+   its tree after the ownership handoff.
+
+6. **Layout.** Run repos are `conductor-agent-<slot>:conductor-daemon`,
+   directories `2770` (setgid, so what the worker creates inherits the group)
+   and files `0660` with execute bits preserved. The shared mirror is
+   daemon-owned, group `conductor-runs`, `0750`/`0640`.
+
+   Everything a slot must reach lives under **`/var/lib/omp-conductor`** (mode
+   `0711`): worktrees, mirrors, per-run session transcripts and per-run boundary
+   homes. It is deliberately outside the state directory, which stays `0700`
+   because it holds `conductor.db` and the WAL files SQLite recreates at
+   runtime — making that searchable would publish fleet history to every local
+   account. Override with `$OMP_CONDUCTOR_SHARED`. Uninstall is therefore two
+   paths, not one.
+
+7. **The daemon's home is `0711`, with its credential leaves closed**
+   (`.ssh`, `.config/gh` at `0700`; `.npmrc`, `.git-credentials` at `0600`).
+   Searchable because the runtime and the installed package live in it — a
+   `0700` home kills every worker before it connects, and no shell-based probe
+   notices — and closed at the leaves because that is where the boundary
+   actually rests. The daemon re-checks this empirically at dispatch, asking the
+   slot principal itself whether it can read any credential path, and refuses
+   the run if it can.
+
+Verify with `omp-conductor status`: the `boundary` row names the live mechanism
+and lists its residuals.
+
+### macOS dev hosts
+
+`sandbox-exec` is Apple-deprecated and is still the only thing on a stock host
+that denies a *read*, which is what this needs. The generated profile makes the
+run's checkout the only writable path and denies `~/.ssh`, `~/.config/gh`,
+`~/.git-credentials`, `~/.npmrc`, the other run checkouts, and mach lookups of
+the keychain services. Verified on darwin 25.5.0 against the full probe list.
+
+A dev host may also simply run `credentials.isolation: "none"`, in which case
+`status` reports it unprotected. That is a legitimate choice for a machine that
+is not a fleet host; it is not a default.
+
+### The residual, stated plainly
+
+A run can **read** another run's git objects out of the shared mirror. That is
+the price of not cloning the repository per run, and it is bounded: same source,
+no write path, no credential. It is asserted as *permitted* by the probe suite,
+so nobody can quietly "fix" it by weakening the mirror's modes.
+
+### MCP servers are inside the blast radius
+
+A GitHub MCP server carrying its own PAT re-opens the hole. Sessions discover
+MCP configuration from the **agent principal's** config root — the redirected
+`$HOME` this package creates per session, not the operator's — and dispatch
+**refuses with a named error** when a credential-bearing GitHub server is found
+there or in the run's checkout. Put servers you want sessions to have in the
+agent principal's root, without credentials.
+
+
 ## Limitations
 
 Known and deliberate in this version:
@@ -1628,6 +2308,18 @@ Known and deliberate in this version:
 - **No cross-process lock on the mirrors.** Two dispatch loops fetching the same
   repo at the same instant can collide on git's ref locks; the run fails and is
   retried rather than corrupted.
+- **A run can read another run's git objects.** The shared mirror is one object
+  store, so the isolation is on writes and credentials, not reads. See
+  [The residual, stated plainly](#the-residual-stated-plainly).
+- **`group-mode` does not contain a determined escape.** It separates run
+  checkouts by group and mode while sessions still run as the daemon's uid. Only
+  `uid-pool` and `sandbox-exec` make the stronger claim, and `status` says which
+  one is live.
+- **A fleet that upgrades and changes nothing is unprotected.** The
+  `credentials` migration resolves to `"none"` and writes it down rather than
+  refusing to dispatch, because an outage caused by a security feature is worse
+  than the day before it shipped. `status` reports it every tick until an
+  operator provisions the host and sets `"per-run"`.
 - **Uniquely local mirror branches are retained.** Terminal runs are reaped
   automatically only after every commit exists on a remote ref. A failed salvage
   push deliberately leaves its branch and tree for an operator rather than
@@ -1654,15 +2346,26 @@ Known and deliberate in this version:
   `slots = maxConcurrentWorkers - live workers`, admits at most that many issues
   per tick, and dispatches them together. To see them, read `omp-conductor
   status`, which lists every occupied issue, or follow `daemon.log`.
+- **Report delivery is at-least-once, never exactly-once.** The Telegram Bot API
+  takes no client-supplied idempotency key, so the window between "Telegram
+  accepted it" and "SQLite recorded that" is irreducible. The daemon resolves it
+  toward a duplicate — the report is retried and the retry says it may be a
+  repeat — because a duplicate you can recognise by its report id is cheaper
+  than a silently dropped page. `delivered` means Telegram accepted an attempt,
+  not that exactly one message exists. See
+  [Report delivery](#report-delivery-the-outbox).
 - **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.
-- **Worker confinement is partial.** Structured `write` / `edit` / `read` /
-  `grep` / `glob` calls are blocked outside the worktree by an inline harness
-  extension (`confineToCwd`). `bash` is not: a shell one-liner can still leave
-  the tree. 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.
+- **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
+  [integrity tripwire](#integrity-tripwire-package-self-hash) still pages if the
+  installed package itself changes under a live daemon.
 
 
 ## License