omp-conductor 0.2.1 → 0.3.1

package/README.md

@@ -28,8 +28,9 @@ the line.
 When a run does get stuck, the first responder is not you. A tier-1 escalation is
 injected into a long-lived **orchestrator session** that can read the issue and the
 run's transcript and then either re-brief the worker or decide the problem genuinely
-needs a human. It never edits product code, pushes or merges. Only tier 2 pages you
-directly.
+needs a human. It never edits product code and never pushes a branch; whether it
+may *merge* is a setup answer (`authority`), and it defaults to no. Only tier 2
+pages you directly.
 
 The package ships three deployables, plus one skill:
 
@@ -37,7 +38,7 @@ The package ships three deployables, plus one skill:
 | --- | --- | --- |
 | omp plugin | `/conductor` slash command | Inspect and arm the conductor from inside an omp session: dry-run the queue, read status, pause, resume. |
 | Standalone daemon | `omp-conductor` binary | The dispatch loop, managed as a background process (`start` / `stop` / `restart`) with a `/healthz` endpoint for a supervisor. |
-| Orchestrator heartbeat | omp extension, activated by `.conductor-tick.json` | Prompts a 24/7 orchestrator session on a fixed interval so its standing loop actually runs. Inert in every other session. See [Orchestrator tick](#orchestrator-tick). |
+| Orchestrator heartbeat | omp extension, activated by `.conductor-tick.json` | Prompts a 24/7 orchestrator session on a fixed interval so its standing loop actually runs, and marks the session stalled when its prompts stop being consumed. Inert in every other session. See [Orchestrator tick](#orchestrator-tick). |
 | Onboarding skill | `skill://conductor-onboarding` | Directs an omp session to interview you, read your repos for real CI gates, and tailor `ORCHESTRATOR.md` — then finish through the wizard. Discovered automatically once the plugin is installed. See [Onboarding](#onboarding). |
 
 The first two are thin wrappers over the same `daemon.ts`, so the plugin and the
@@ -66,7 +67,7 @@ second, explicit confirmation. It is a starting point rather than a contract:
 | Section | Whose |
 | --- | --- |
 | Duties (drain, groom, report), escalation tiers, hard boundaries | **Fixed** — they describe how this package already behaves. |
-| Releases | **Yours.** Ships defaulting to "humans release; the conductor and its workers never tag, pin, deploy, or publish". Replace it only if you are deliberately delegating releases to that session — and then be specific about what, when, on what proof, and what stays permanently forbidden. |
+| Releases | **Yours.** Its opening paragraph is rendered from the `authority` you answered in setup — by default "humans release, and you do not merge". Everything under it is the procedure, and a delegated session is told not to cut a release until you have written one: what, when, on what proof, and what stays permanently forbidden. |
 | Reporting | **Yours**, seeded from the scope you chose in setup. |
 
 Reporting is the one half of that the config also knows about, because the wizard
@@ -95,7 +96,7 @@ session that ignores its constraint line still reaches you. Scope is a
 constraint the model is handed each turn. It is not a gate the model is held to.
 The enforcement roadmap (a tool-call tripwire, and config-versus-behaviour drift
 in the daily digest) is
-[issue #4](https://github.com/TerrifiedBug/conductor/issues/4).
+[issue #11](https://github.com/TerrifiedBug/conductor/issues/11).
 
 Changing the key later does not rewrite an `ORCHESTRATOR.md` you already have:
 the tick line changes, the brief does not. Edit its Reporting section too, or the
@@ -119,7 +120,7 @@ and create any missing labels):
 | Key | Meaning |
 | --- | --- |
 | `tracker.repo` | The **one** `owner/repo` whose issue list is the queue. This is your planning repo — it does not have to contain any code. |
-| `queueLabel` | Open issues in `tracker.repo` carrying this label (default `ready-for-agent`) are the work queue. Nothing else is ever read. |
+| `queueLabel` | Open issues in `tracker.repo` carrying this label are the work queue. Nothing else is ever read. Required: the wizard pre-fills `ready-for-agent`, but a config that omits the key is rejected, not defaulted. |
 | `routing.repos` + `repo:<name>` labels | Each queued issue must also carry exactly one routing label naming which code repo the work lands in. The conductor cuts the worktree and PR there, from `routing.repos[name].cloneUrl`. An issue with zero or two routing labels is reported as unroutable and skipped — never guessed. |
 
 So: one tracker repo supplies the queue, routing labels fan issues out to any
@@ -182,7 +183,9 @@ So the skill does the part a dialog cannot:
 - **Interviews you** on release policy — humans release (the default), the agent
   releases to a named boundary, or the agent releases fully — pressing on the one
   question that makes a delegated release safe: *where does the agent's leg end?*
-  Plus escalation taste, and which of the two [`reporting.scope`](#your-workflow-vs-the-package)
+  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)
   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*
@@ -317,12 +320,27 @@ Per tick, for the daemon's project:
    the configured repo names. These are never dispatched.
 5. **Check spend.** If spend since local midnight has reached `dailySpendUsd`, the
    daemon **pauses itself**, pages at Tier 2, and returns.
-6. **Check capacity.** `maxConcurrentWorkers` minus active runs gives the free
-   slots. If none are free, the tick logs and returns.
+6. **Check capacity.** `maxConcurrentWorkers` minus *live* workers (runs in
+   `claimed` or `running`) gives the free slots. A green PR awaiting a human
+   merge occupies its issue but not a slot: its worker is finished, and counting
+   it would let two green PRs stop the fleet. If no slot is free, the tick logs
+   and returns.
 7. **Admit issues** up to the free slots, skipping any issue that already has
-   an active run. An issue that has used `maxAttemptsPerIssue` escalates at Tier 1
+   an active run — including a green PR, so a second attempt can never land on a
+   live PR. An issue that has used `maxAttemptsPerIssue` escalates at Tier 1
    instead of being admitted.
-8. **Dispatch** the admitted issues concurrently.
+8. **Ask the tracker whether the work already exists.** For each candidate that
+   survived step 7 — so at most one API call per free slot, never one per queued
+   issue — the daemon asks whether an **open** PR already closes the issue. If one
+   does, the issue is skipped with its PR named in the log. Drafts count: a draft
+   PR's branch still holds the only copy of the work. This is the guard the store
+   cannot provide, because a store younger than the PRs (a migration, a wiped or
+   relocated state directory, a restore onto a new host) has no row to object
+   with. If the check itself 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.
+9. **Dispatch** the admitted issues concurrently.
 
 Then, per admitted issue:
 
@@ -330,9 +348,9 @@ Then, per admitted issue:
    This ordering is the whole crash-safety story: the label, not the local
    database, is the guard against dispatching the same issue twice. If the process
    dies at any later point, the next daemon sees the label, eligibility filters the
-   issue out, and a human decides what to do with the orphan. A store that is lost
-   can be rebuilt from the tracker; a label that was written too late cannot undo a
-   duplicate PR.
+   issue out, and the orchestrator's drain duty triages the orphan (see below). A
+   store that is lost can be rebuilt from the tracker; a label that was written too
+   late cannot undo a duplicate PR.
 2. Create the run row (`claimed`).
 3. Clear any stale tree for this issue, then add a fresh worktree at
    `<workspaceRoot>/<issue>` cut from the bare mirror at `<mirrorRoot>/<repo>.git`,
@@ -347,13 +365,46 @@ Then, per admitted issue:
    | --- | --- | --- | --- |
    | `pushed-green` | `agent:in-progress` stays until the merge closes the issue | removed | none |
    | `blocked` | swapped to `agent:blocked` | removed | Tier 1 |
-   | `failed` / `killed` | swapped to `agent:failed` | **kept** as evidence | Tier 1 |
-   | unexpected error | swapped to `agent:failed` | kept | Tier 1 |
+   | `failed` / `killed` | swapped to `agent:failed` | dirty tree committed to the branch, then **kept** as evidence | Tier 1 |
+   | unexpected error | swapped to `agent:failed` | same | Tier 1 |
 
    Label swaps add the new label before removing the old one: the reverse order
    leaves a window in which the issue carries no state label at all, which is
    exactly the shape eligibility reads as fresh work.
 
+   **A non-graceful end salvages the tree first.** A turns-cap kill, a
+   wall-clock kill and a crash are all external and unannounced: they land
+   mid-edit, and only the run's *branch* is preserved across attempts — the tree
+   is removed `--force` by the next one. So before the escalation is written,
+   a dirty tree is committed to the run's own branch as
+   `wip(#<issue>): attempt <n> killed by <reason> — auto-salvaged` (everything,
+   including files git has never seen) and pushed, and the escalation says where
+   it went: `WIP committed to <branch> @ <sha>`. A push that is refused leaves
+   the commit in this host's mirror and says so; a salvage that fails outright
+   says that, loudly, naming the tree that now holds the only copy. A `blocked`
+   run is deliberately *not* salvaged — it stopped on purpose, with turns still
+   in hand to commit for itself.
+
+### What a restart does to runs that were in flight
+
+A `claimed` or `running` row is a promise that a worker process exists, and a
+daemon that just started knows that promise is broken: its workers died with the
+previous process. At startup — unless another daemon is alive, so a foreground
+`daemon --once` cannot orphan a running daemon's real workers — every such row is
+moved to `orphaned`, with a log line naming the issue, the attempt and the
+worktree. That frees the slots immediately; a fleet must never resume as
+deadlocked as it crashed.
+
+Only the rows change. The issue keeps `agent:in-progress` — the label is the
+crash guard against double-dispatch — and deciding what the dead worker's remains
+are worth is the orchestrator's drain-duty judgement, spelled out in its brief:
+an open green PR goes to the merge path, a dirty tree is reported before anything
+destroys it (uncommitted edits have no other copy; unpushed *commits* are safe on
+the run's branch in the mirror, which a retry deliberately reattaches), and a
+clean orphan has its label released so the next tick re-claims it. Orphaned
+attempts still count toward `maxAttemptsPerIssue`, so a crash loop escalates
+instead of redispatching forever.
+
 ### Branch names
 
 `<type>/<slug>`, where the type is `fix` when any label's last segment (after `:`
@@ -440,7 +491,7 @@ otherwise looks like a run that was merely unlucky.
 | Tier | Meaning | Raised by | Delivered to |
 | --- | --- | --- | --- |
 | 1 | "Not a human's problem yet" — the run is parked and safe. | Unroutable issue, blocked run, failed or killed run, dispatch error, attempts exhausted. | The orchestrator session, as an injected prompt. Falls back to an issue comment when no orchestrator is running, or when it will not accept the injection. |
-| 2 | "The fleet is stopped until you look." | Daily spend cap reached; the project is already paused. | Telegram, when `escalation.telegramChatId` is set and a bot token is readable; otherwise it falls back to the issue comment. |
+| 2 | "The fleet is stopped until you look." | Daily spend cap reached; the installed package changed under the running daemon. Either way the project is already paused. | Telegram, when `escalation.telegramChatId` is set and a bot token is readable; otherwise it falls back to the issue comment. |
 
 **The orchestrator** is one persistent, file-backed session per daemon run, resumed
 across restarts so it remembers what it has already handled. Its `cwd` is the state
@@ -448,9 +499,27 @@ directory, deliberately not a checkout. Delivery resolves when the harness *acce
 the prompt, not when the model answers it, so a tick never parks behind a model; an
 injection arriving mid-thought queues as a follow-up instead of interrupting the
 turn in flight. Its standing orders are explicit: re-brief the worker, file or
-comment on issues, or promote to tier 2, and never edit product code, push a branch
-or merge a PR. If it fails to start, the daemon logs a warning and runs on, with
-tier-1 escalations degraded to issue comments.
+comment on issues, or promote to tier 2, and never edit product code or push a
+branch. Merging is the one line worded from config — see [`authority`](#configuration).
+If it fails to start, the daemon logs a warning and runs on, with tier-1
+escalations degraded to issue comments.
+
+**Or no orchestrator at all.** Set `escalation.orchestrator` to `"external"` when
+you already run your own supervising session — a visible TUI session in a pane,
+typically. The daemon then starts none of its own and every tier-1 escalation
+posts as an issue comment, which is what that session drains. One brain, and it
+is the one you can watch.
+
+**Answering a tier 1 is only half of it.** A blocked or failed run leaves its state
+label on the issue, and eligibility reads any state label as disqualifying, so an
+answered issue that keeps one is never re-claimed and the answer is inert — nothing
+fails, the issue just stops existing as far as dispatch is concerned.
+[`omp-conductor unblock <issue>`](#cli-reference) is the way back: it clears the
+label through the same tracker the dispatcher writes with. The brief tells the
+orchestrator to run that verb rather than edit the label itself, and that is not a
+formality — orphan detection works by comparing `agent:in-progress` labels against
+live runs, and it is only trustworthy while every state label on the tracker was
+written by this package.
 
 Tier 2 borrows the bot token that `omp-telegram` already owns, at
 `~/.omp/agent/telegram/.env` (or `$OMP_TELEGRAM_STATE_DIR/.env`). If you run that
@@ -464,8 +533,8 @@ issue on every poll, so a ledger in the store — keyed by project, issue, tier
 summary — makes a recurring condition page **once** and suppresses the five-minute
 repeats. The marker is recorded only on successful delivery, so a page that could
 not be delivered is retried on the next tick instead of being written off as sent.
-The spend-cap summary carries the date, so the same cap pages again tomorrow but
-only once per day.
+The spend-cap and integrity-tripwire summaries carry the date, so the same
+condition pages again tomorrow but only once per day.
 
 If `fallbackToIssueComment` is off and no Telegram transport is configured,
 delivery throws instead of dropping silently. The failure is logged and retried,
@@ -484,7 +553,10 @@ Runtime state lives elsewhere, under `$OMP_CONDUCTOR_RUNTIME_DIR` (default
 atomically, and `daemon.log`, appended across every boot so the previous failure is
 still there when you go looking. It is kept apart from the config directory because
 it is meaningless after a reboot, and the pidfile's liveness is probed on every
-read — a stale one never blocks a `start`.
+read — a stale one never blocks a `start`. Both `start` and a bare `daemon` write
+the pidfile, so a daemon run in the foreground under systemd is as visible to
+`status` as a backgrounded one; `daemon --once` writes nothing, because that drill
+is exactly what the orphan-reconciliation guard reads the pidfile to protect.
 
 The file is validated on every read. A malformed config produces one readable error
 listing every fault, and the daemon refuses to start rather than running with half
@@ -548,7 +620,12 @@ A complete, valid config for one project with two target repos:
       "workerModel": "smol",
       "escalation": {
         "telegramChatId": "123456789",
-        "fallbackToIssueComment": true
+        "fallbackToIssueComment": true,
+        "orchestrator": "embedded"
+      },
+      "authority": {
+        "merge": "human",
+        "release": "human"
       },
       "reporting": {
         "scope": "material"
@@ -574,6 +651,8 @@ Field notes:
 | `gates` | The exact cheap commands CI also runs, each with the `cwd` it runs from (`cwd` defaults to `.`). Running the real gate locally is what makes an unattended push safe — a subset lets an error outside the source dir reach the runners. |
 | `caps` | Per-project overrides; omit it or pin only the fields you want to change. |
 | `escalation.fallbackToIssueComment` | Defaults to `true`. Absent means "yes, still tell me". |
+| `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. |
 | `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. |
 | `workspaceRoot` / `mirrorRoot` | Optional; default to `worktrees/` and `mirrors/` under the state directory. `~` is expanded. |
 
@@ -590,13 +669,13 @@ it never gets prompted, so it never runs anything. Installing
 
 The heartbeat is **inert unless the session's cwd contains
 `.conductor-tick.json`**, so it costs an ordinary session nothing. Drop the file
-in the orchestrator's working directory (on the fleet host, `/root/fleet`):
+in the orchestrator's working directory:
 
 ```json
 {
   "intervalSeconds": 900,
   "armedFile": "state/armed",
-  "accessFile": "/root/.omp/agent/telegram/access.json",
+  "accessFile": "/home/fleet/.omp/agent/telegram/access.json",
   "message": "Run your standing loop from ORCHESTRATOR.md now."
 }
 ```
@@ -606,13 +685,18 @@ in the orchestrator's working directory (on the fleet host, `/root/fleet`):
 | `intervalSeconds` | yes | — | Whole seconds between ticks, minimum `60`. A tick costs a full turn of a frontier model, so a sub-minute period is refused rather than obeyed. |
 | `armedFile` | no | none — the gate passes | Path to the arm marker. A tick does nothing while the file is missing. Relative paths resolve against the session cwd, so `state/armed` means `<cwd>/state/armed`. |
 | `accessFile` | no | none — the gate passes | Path to the Telegram bridge's `access.json`. Every tick re-reads it and requires `enabled: true` with exactly one entry in `allowFrom`. Relative paths resolve against the session cwd. **Configure this on any fleet deploy** — see below. |
-| `message` | no | `Tick <ISO timestamp>: run your standing loop from ORCHESTRATOR.md now.` followed by the `reporting.scope` line | Sent verbatim when set — and then it owns the whole contract: no scope line is appended to a prompt you wrote yourself. The default carries the timestamp, which is what makes two consecutive ticks distinguishable in the session log. |
+| `message` | no | `Tick <ISO timestamp>: re-read <workspaceRoot>/ORCHESTRATOR.md from disk, then run your standing loop from it.`, then the `reporting.scope` line, then the delivery rule | Sent verbatim when set — and then it owns the whole contract: neither the scope line nor the delivery rule is appended to a prompt you wrote yourself. Re-read from disk on **every** tick, so rewording it binds the next heartbeat instead of waiting for a session restart; a re-read that fails — caught mid-edit, removed, or invalid — keeps the value read at session start rather than stopping the heartbeat. `intervalSeconds` is *not* re-read: rescheduling a live timer still needs a restart. The default *orders* the session to re-read its brief, naming the path resolved from the conductor config — a 24/7 session otherwise acts on the copy loaded at its start (resume included), and an amendment added between ticks never binds — and carries the timestamp, which makes two consecutive ticks distinguishable in the session log. |
 
 A tick sends one message (`customType` `omp-conductor.tick`, attributed to the
-user): the standing-loop prompt, plus the one constraint line the project's
+user): the standing-loop prompt, the one constraint line the project's
 [`reporting.scope`](#your-workflow-vs-the-package) resolves to, re-read from the
-conductor config on every tick. It starts a turn if the session is idle; while a
-turn is streaming it is queued as a follow-up and consumed when that turn ends.
+conductor config on every tick, and a delivery rule. That last line is there
+because end-of-turn text reaches the operator's Telegram only on a turn that
+*began* as an inbound Telegram message: a tick is injected locally, so anything
+the session merely writes at the end of one is read by nobody, and a reportable
+event has to be delivered by an explicit `telegram_send` call the session
+watched succeed. The tick starts a turn if the session is idle; while a turn is
+streaming it is queued as a follow-up and consumed when that turn ends.
 It sends **nothing** when:
 
 - `/conductor pause` (or `omp-conductor pause`) holds the pause flag, the same
@@ -620,7 +704,9 @@ It sends **nothing** when:
 - `armedFile` is configured and missing;
 - `accessFile` is configured and the escalation channel is not verifiably up;
 - an earlier tick is still queued. Ticks coalesce rather than stack, so a slow
-  turn cannot leave a backlog of heartbeats behind it.
+  turn cannot leave a backlog of heartbeats behind it — and two coalesced ticks
+  in a row are the signal that the session is not slow but wedged, which is
+  what the [stall marker](#a-wedged-session-and-the-marker-that-notices) is for.
 
 ### The escalation channel is a gate, and it fails closed
 
@@ -642,16 +728,84 @@ Leaving `accessFile` unset passes the gate, because an ordinary developer sessio
 that happens to have a `.conductor-tick.json` has no bridge to check. It is not an
 off switch for the check: **a fleet deploy always sets it.**
 
-Every tick — sent or skipped — is logged with its reason (`paused`, `not armed`,
-`escalation channel down`, `tick already pending`) to the omp log. Skips are
-deliberately silent in the UI: a paused fleet would otherwise raise a notification
-every interval, forever. The one exception is a malformed `.conductor-tick.json`,
+Every tick — sent or skipped — is logged with its reason (`not armed`,
+`escalation channel down`, `tick already pending`) to the omp log. `/conductor
+pause` is deliberately **not** one of the gates: pause stops the *dispatcher*
+claiming work, and the tick drives a different session — one whose duties
+(grooming the queue, draining escalations, reporting) are exactly what stays
+useful while dispatch is stopped. Its own off switch is the arm marker. Skips
+are deliberately silent in the UI: a disarmed fleet would otherwise raise a
+notification every interval, forever. The one exception is a malformed
+`.conductor-tick.json`,
 which notifies once at session start and leaves the heartbeat off; silent failure
 there is the failure mode the heartbeat exists to prevent. A conductor config that
 cannot supply a reporting scope logs `tick reporting scope: using material` once
 per session. The interval does not re-log it, because the file is unlikely to fix
 itself between two ticks.
 
+### A wedged session, and the marker that notices
+
+Coalescing is also the only wedge detector this package has. On 2026-08-07 the
+dogfood fleet's orchestrator finished a turn, logged `ui.loop-blocked` right
+after an auto-compaction threshold decision, and never started another. The
+process stayed alive, so herdr's recovery — agent listed AND a non-shell
+foreground process — read healthy. The dispatch daemon is a separate process and
+kept working, so `/healthz` was green all night, while the one brain holding
+merge authority sat on a green PR it never merged. A tick injected two minutes
+into the wedge and an operator's Telegram message five minutes later both went
+unconsumed for 23 minutes, until a manual `SIGTERM`. The heartbeat logged `tick
+skipped: tick already pending` throughout, which is exactly what a merely slow
+turn looks like.
+
+So the heartbeat counts them. Two consecutive coalesced ticks — a full hour at
+the reference 1800-second interval, generous by construction — mean the last
+prompt was never consumed, and the extension:
+
+- writes `<session cwd>/.conductor-stalled`, one line of `<ISO timestamp>
+  <diagnosis>`.
+- logs at **error** level: `orchestrator stalled: 2 ticks queued unconsumed —
+  the agent loop is not draining; see .conductor-stalled`.
+
+Both escapes deliberately leave the session, because a loop that cannot drain
+its queue cannot report on itself — that is the whole failure.
+
+**Two things read it.** A marker nobody consumes is an artifact, not an alert:
+
+- **The daemon**, on its own five-minute tick, and *before* its pause check. The
+  orchestrator is a different process and can be wedged while the fleet is
+  deliberately paused — precisely the state the dogfood fleet was in when this
+  happened. One tier-2 page per stall, dated, re-armed when the marker clears,
+  and latched only once the page is confirmed delivered, so an escalation
+  channel that fails on the one tick that noticed does not buy permanent
+  silence. It restarts nothing: a wedge lands mid-turn, and this process cannot
+  tell a half-applied edit from an idle loop.
+- **herdr-conductor's recovery**, which treats marker-present as *not live*. Its
+  liveness test — agent listed AND a non-shell foreground process — passes
+  straight through a wedge, so without this a recovery run certifies a stuck
+  session as healthy and returns "nothing to do".
+
+The daemon is what covers a wedge beginning *between* herdr's lifecycle events,
+since a session that stays alive and stops working emits none of them.
+
+The first tick that actually sends clears the counter and deletes the marker,
+and it deletes one it did not write: recovery normally arrives as a fresh
+process resuming the same transcript, so the session doing the clearing is not
+the session that stalled. Nothing else removes the file. Neither the write nor
+the delete can take the heartbeat down — a filesystem error is logged and the
+tick carries on.
+
+`omp-conductor status` reads the same marker from the **state directory** and
+prints one more line under the daemon block:
+
+```text
+orchestrator   STALLED since 2026-08-07T06:27:55.123Z — 2 ticks queued unconsumed — the agent loop is not draining
+```
+
+That reading is the reference deploy's convention — the orchestrator session
+runs from `~/.omp/conductor`, which is the state directory — and it is
+one-directional: a line there proves a wedge, and its absence proves nothing,
+least of all on a fleet whose session lives somewhere else.
+
 ## CLI reference
 
 ```bash
@@ -659,6 +813,8 @@ omp-conductor start [--port N] [--project NAME]
 omp-conductor stop
 omp-conductor restart [--port N] [--project NAME]
 omp-conductor status [--project NAME]
+omp-conductor tail <issue> [--project NAME]
+omp-conductor unblock <issue> [--project NAME]
 omp-conductor daemon [--once] [--port N] [--project NAME]
 omp-conductor pause
 omp-conductor resume
@@ -671,12 +827,14 @@ omp-conductor help
 | `start` | Spawn the loop in the background, detached, and wait until it answers `GET /healthz` on `:8787`. Refuses if one is already live, naming its pid. If the process dies or never serves, `start` cleans up after it and quotes the tail of `daemon.log`. |
 | `stop` | `SIGTERM`, then `SIGKILL` after a 10-second grace period. Prints `not running` when there is nothing to stop. |
 | `restart` | `stop` then `start`, inheriting the running daemon's port and project unless a flag overrides them — a restart that quietly moved to the default port would leave every existing health check pointing at nothing. |
-| `status [--project NAME]` | Pause state, config and state paths, resolved caps, active runs and today's usage, plus a `daemon` block: pid, uptime, port, project, `/healthz` result and log path. Reads while a daemon in another process writes. |
-| `daemon` | Run the loop in the **foreground**, ticking every 5 minutes and serving `/healthz`. This is what `start` launches. |
-| `daemon --once` | Run a single tick and exit. No HTTP server. |
+| `status [--project NAME]` | Pause state, config and state paths, resolved caps, active runs and today's usage, plus a `daemon` block: pid, uptime, port, project, `/healthz` result and log path. A `.conductor-stalled` marker in the state directory adds an `orchestrator   STALLED since …` line — see [the stall marker](#a-wedged-session-and-the-marker-that-notices). Reads while a daemon in another process writes. |
+| `tail <issue>` | Follow the newest run for that issue: the worker's assistant text as `assistant: …` and each tool it calls as `tool: <name>`, printed as they land. Workers are omp sessions inside the daemon rather than terminals, so this is the only way to watch one live — a herdr pane running it becomes an observation window. Starts from the top of the transcript, not the end, so attaching to a run that is already ten turns in shows those ten turns. Exits `1` with `no run recorded for #N` when the issue has never been dispatched, or `no transcript yet (state: …)` when the attempt has not opened one. Otherwise it runs until `Ctrl-C`, or until the run has finished and its transcript has been silent for five seconds, and prints `run ended: <state>`. |
+| `unblock <issue>` | Remove that issue's `blocked` and `failed` state labels through the tracker, so the next tick can claim it again. This is the supported way back for an escalation you answered: eligibility disqualifies any issue carrying a state label, so an answered issue that keeps one is never re-claimed and the answer is inert. Removing a label the issue does not carry is a no-op, so both are always cleared and neither has to be looked up first. `agent:in-progress` is deliberately not touched — it means a worker process exists, which is not something an answer changes. The run history is left exactly as it is: an answered block still spent a worker, so it still counts toward `maxAttemptsPerIssue`, and the output says how many attempts remain — or warns that the next tick will escalate instead of dispatching, when none do. Exits `2` with `unblock needs an issue number` on a missing or malformed positional. |
+| `daemon` | Run the loop in the **foreground**, ticking every 5 minutes and serving `/healthz`. This is what `start` launches, and what a systemd unit should call. Writes the pidfile itself, and refuses with `another daemon is alive (pid N); stop it first` rather than becoming a second dispatcher. |
+| `daemon --once` | Run a single tick and exit. No HTTP server, and no 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. |
 | `--project NAME` | Pick the project to service. One daemon process serves exactly one project; with several configured projects the name is required. |
-| `pause` | Stop claiming new work. The running daemon notices on its next tick; runs already in flight finish. |
+| `pause` | Stop claiming new work. The running daemon notices on its next tick; runs already in flight finish. The orchestrator heartbeat keeps ticking — its gate is the arm marker, not this flag. |
 | `resume` | Allow claiming again. |
 | `brief-upgrade` | Compare a project's `ORCHESTRATOR.md` against the brief this version of the package ships. Reports by default; see [Keeping a brief current](#keeping-a-brief-current). |
 | `--apply` | Only for `brief-upgrade`. Replaces the half above the `YOURS TO EDIT` banner and keeps everything below it, backing the previous file up first. Ignored when the brief cannot be split or the template is unrendered. |
@@ -717,13 +875,42 @@ dispatcher. The brief is explicit about the boundary:
 | 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`. **Merge authority is a human's alone**, so PRs land one at a time with a freshness re-check — two workers merging concurrently is how agent PRs clobber each other. |
+| 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. | **Cut a release**, push a tag, publish to npm, edit a deployment pin, deploy, or touch infrastructure or secrets — permanently out of scope. Releases are batched and decided outside this loop, so "this needs releasing" is a thing to report, never a task to take on. |
 
 The worker ends with a six-line evidence report (issue, pr, state, gates, changed,
 next). `pushed-green` means it watched the checks go green rather than expecting
 them to.
 
+### The boundary is prompt text — and one tripwire
+
+A worker session gets a `cwd` and nothing else: the harness applies no filesystem
+or network restriction, so "touch any path outside its worktree" is a rule the
+session is asked to keep, not one the process cannot break. Target selection *is*
+mechanical — only a repo in `routing.repos` is ever checked out — and so are the
+caps, but between them they bound where work starts and how much of it happens,
+not how far a wandering or prompt-injected session can reach.
+
+The one path that is checked mechanically is the conductor itself. At startup the
+daemon sha256s every `.ts` and `.md` file of its own installed `src/` — the
+dispatcher and the briefs both, since rewriting a brief buys more than rewriting
+the loop — and re-walks that tree on every tick (about 0.6 ms). Any difference at
+all, changed or added or removed, is read as the package having been modified
+underneath a running daemon: the tick claims nothing, the fleet is paused, and a
+tier-2 escalation naming the first few differing paths pages you **once**, not
+every five minutes.
+
+**A normal deploy never trips it.** The baseline is recorded per daemon process,
+so installing a new build and restarting the unit re-records it from the new
+files; only a change that lands *while* a daemon is holding the package open can
+diverge from it. That also means `omp-conductor resume` on its own will not hold
+— the next tick re-walks, still differs, and pauses again. Put the files back, or
+restart onto the build you meant to be running.
+
+This is detection, not prevention. It catches the worker that wandered, and it
+catches the human who edited the live install "just to test something", which in
+practice is the commoner of the two.
+
 ## Limitations
 
 Known and deliberate in this version:
@@ -766,12 +953,19 @@ Known and deliberate in this version:
   (the orchestrator's) no matter how many workers are running, and no amount of
   `maxConcurrentWorkers` changes that.
 
-  The cap does work. The admission loop (`src/daemon.ts:405-445`) computes
-  `slots = maxConcurrentWorkers - active runs`, admits at most that many issues per
-  tick, and dispatches them together. To see them, read `omp-conductor status`,
-  which lists every active run, or follow `daemon.log`.
+  The cap does work. The admission loop (`admitCandidates` in `src/daemon.ts`) computes
+  `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`.
 - **Merges, releases and deploys are human-only, by design.** The conductor
   produces green PRs and stops.
+- **Worker confinement is behavioural.** `runWorker` hands the session a `cwd` and
+  a brief; nothing stops it reading or writing elsewhere on the host, and on a
+  single-user deploy that includes the state directory and the host's `gh`
+  credentials. The [integrity tripwire](#the-boundary-is-prompt-text--and-one-tripwire)
+  turns one case of this into a paused, paged fleet after the fact; the prevention
+  half is a deployment concern — run workers as a least-privileged uid whose write
+  access ends at its worktree and mirror.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/skills/conductor-onboarding/SKILL.md

@@ -119,16 +119,25 @@ are the orchestrator and a human.** The orchestrator is the right agent for it i
 any agent is: it is long-lived, it can see everything that merged since the last
 release, and batching is exactly the judgement a per-issue session cannot make.
 
-So frame it as **three** options, in this order, and name the default:
+So frame it as **three** options, in this order, and name the default. Each one
+maps to an `authority` answer the wizard asks for directly — the interview
+decides *which answer to give*, and `/conductor setup` is what records it. Never
+write authority into the brief by hand: the config is what words the brief, and
+a hand-edit is a second source that outlives the operator's memory of making it.
 
 1. **Humans release.** *(default, and what the package ships)* Work ends at a
    green PR. Merging is a separate human action; releasing is a separate human
    action after that. Neither a worker nor the orchestrator ever tags, pins,
    publishes, or deploys. "This needs releasing" becomes something the
-   orchestrator *reports*.
+   orchestrator *reports*. → `authority: merge=human, release=human`; answer
+   **no** to both wizard confirms.
 2. **The orchestrator releases up to a named boundary.** Delegating part of the
    release to the supervising session, with the stopping line written down.
-3. **The orchestrator releases fully.**
+   → usually `merge=orchestrator, release=orchestrator`, with the boundary in
+   the procedure rather than in the grant; `merge=orchestrator, release=human`
+   when the line falls before the tag.
+3. **The orchestrator releases fully.** → `merge=orchestrator,
+   release=orchestrator`.
 
 Then ask the question that makes option 2 real:
 
@@ -138,8 +147,8 @@ Not "can it release" — *where does its leg stop*. A boundary you cannot state
 one sentence is not a boundary, and an orchestrator with a vague release mandate
 is one that eventually publishes something at 03:00.
 
-Give them a worked answer so they can calibrate. The Veltro deployment's answer:
-**the agent's leg ends at the merged suite pin.** It may open and land the PR that
+Give them a worked answer so they can calibrate. One real deployment's answer:
+**the agent's leg ends at the merged version pin.** It may open and land the PR that
 bumps the module image tags, because that artefact is reviewable, reversible by a
 revert, and its correctness is checkable by a named CI check. Deploying that pin
 to prod is **operator territory** — it needs a person who can watch it, and who
@@ -344,7 +353,8 @@ about gates: an operator describes the release they *remember*, and a release is
 the one procedure where being approximately right is worst.
 
 Skip this step only for option 1 (humans release). There is nothing to scaffold:
-the shipped paragraph is already correct and the brief keeps it verbatim.
+the rendered paragraph already says humans hold both, and there is no procedure
+under it to write.
 
 ### Find the release authority
 
@@ -423,7 +433,8 @@ has a safe fleet. Your job is to raise it to *this* fleet.
 The file has a hard line in it — an HTML comment banner reading
 `YOURS TO EDIT`. Respect it in both directions:
 
-**Above the banner — leave it alone.** Duties (drain, groom, report), the
+**Above the banner — leave it alone.** The three duties — drain (unstick what is
+stuck), groom (keep the queue worth draining), report — the
 escalation-tier table, and the hard boundaries describe how the package already
 behaves. Rewriting them makes the brief disagree with the code, and the code wins.
 The evidence rule in particular is not negotiable: *every claim cites evidence — a
@@ -432,24 +443,24 @@ PR URL, an issue number, or a named check actually read.* "Should be fine",
 
 Know what is *not* up there, though, because operators expect it to be: the
 orchestrator's own merge and release authority is **not** a hard boundary. It is
-policy, it lives in Releases, and it defaults to none. What is fixed above the
-banner is that a *worker* never merges or releases, and that PRs land one at a time
-with a freshness re-check. Delegating a release to the orchestrator does not touch
-either of those, so it needs no negotiation with the shipped half.
+config — the two `authority` answers — and it defaults to none. What is fixed
+above the banner is that a *worker* never merges or releases, and that PRs land
+one at a time with a freshness re-check. Delegating a release to the
+orchestrator does not touch either of those, so it needs no negotiation with the
+shipped half.
 
 **Below the banner — rewrite from the interview.**
 
-- **Releases.** Replace the section with the procedure you scaffolded in Step 4. If
-  humans-release, say so in one short paragraph and stop; do not leave the "replace
-  this paragraph if you are delegating" instructions in a finished brief, because
-  a standing prompt full of alternatives it did not choose is a standing prompt
-  the session has to guess its way through. If they chose a boundary, write the
-  boundary as a sentence with an end — *"your leg ends at the merged pin PR; you
-  never deploy it"* — then the scaffolded steps, then the forbidden list with its
-  citations. State the merge authority explicitly either way: a brief that
-  prescribes landing a release PR without ever saying the orchestrator may merge is
-  a brief the session has to infer permission from, and it will infer wrong in one
-  direction or the other.
+- **Releases.** The section's opening paragraph is rendered from the `authority`
+  answers, and Duty 1's "the PR is green" branch is rendered from the same
+  place. Leave both alone: they are the config speaking, and re-running
+  `/conductor setup` is how they change. What you write is everything under that
+  paragraph — the procedure you scaffolded in Step 4. If humans-release, there is
+  nothing to scaffold and you stop. If they chose a boundary, write the boundary
+  as a sentence with an end — *"your leg ends at the merged pin PR; you never
+  deploy it"* — then the scaffolded steps, then the forbidden list with its
+  citations. Do not restate the merge grant in your own words: a second spelling
+  of it is exactly the disagreement the rendered paragraph exists to prevent.
 - **Reporting.** Rewrite it as the one scope they chose, in the second person,
   concretely. Delete the description of the scope they did not choose: it is
   useful in a template and noise in a live prompt. Keep the closing constraint