omp-conductor 0.3.13 → 0.3.16

package/README.md

@@ -7,17 +7,16 @@ tiers: first to an orchestrator session that can re-brief the worker, then to yo
 ## What it is
 
 You label an issue. Within one tick the conductor claims it on the tracker, cuts a
-worktree, hands one omp session a self-contained brief, watches it to a green PR —
-and then stops. Merging is a human act; the conductor never performs it.
+worktree, hands one omp worker a self-contained brief, and watches it to a green
+PR. The worker then stops: it never merges, tags, publishes or deploys.
 
 ### Scope
 
-One issue, one green PR. That is the whole remit.
-
-Merging is a human act, and so is releasing. Releases are **batched**: cut from a
-coherent group of merged work by a human-supervised decision, never one per PR. So
-nothing in this package tags, pins, deploys or publishes, and no worker is ever
-asked to. A worker whose change needs releasing reports that and stops.
+One issue, one green PR. That is the worker's whole remit. A change that needs a
+merge or release is reported to the orchestrator, whose `merge` and `release`
+authority are chosen during setup and default to `human`. Granting either action
+to the orchestrator never grants it to a worker or the dispatch daemon. Releases
+remain batched from coherent groups of merged work, never cut one per worker PR.
 
 Code counts every limit that decides whether work starts: concurrency, dollars per
 day, turns and wall clock per worker, attempts per issue. None of it is left to the
@@ -29,21 +28,23 @@ When a run does get stuck, the first responder is not you. A tier-1 escalation i
 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 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.
+may merge or release is a setup answer (`authority`), and both default to no. Only
+tier 2 pages you directly.
 
-The package ships three deployables, plus one skill:
+The package ships three deployables, plus two skills:
 
 | Deployable | Entry | What it is for |
 | --- | --- | --- |
-| omp plugin | `/conductor` slash command | Inspect and arm the conductor from inside an omp session: dry-run the queue, read status, pause, resume. |
+| omp plugin | `/conductor` slash command | Inspect and control the fleet from inside an omp session: status, hold/halt, arm/disarm, pause/resume, setup. |
 | 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, and marks the session stalled when its prompts stop being consumed. Inert in every other session — including a second session opened in the fleet's own directory. 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). |
+| Update skill | `skill://conductor-update` | Treats the npm and Herdr plugins as one maintenance operation: drain, halt, replace both halves, restart, re-arm through Telegram proof, and verify twice. See [Updating](#updating). |
 
 The first two are thin wrappers over the same `daemon.ts`, so the plugin and the
-CLI cannot disagree about what a cap means or where the state lives. The heartbeat
-reads the same pause flag both of them write.
+CLI cannot disagree about what a cap means or where the state lives. Claiming is
+gated by the pause flag; tick sends are gated by the arm marker — they are not
+the same switch. Prefer `hold` when you want both quiet.
 
 ## Your workflow vs. the package
 
@@ -108,9 +109,10 @@ session is carrying two versions of your policy.
 exactly one value, `"github"`, and every tracker operation shells out to your
 already-authenticated `gh` CLI — the conductor never stores a token of its own.
 Gitea, Jira, and file-based trackers are not supported yet; the seam for them is
-`src/tracker/github.ts`, which implements the whole six-method `Tracker`
+`src/tracker/github.ts`, which implements the whole nine-method `Tracker`
 interface in `src/types.ts` (`listReady`, `addLabel`, `removeLabel`, `comment`,
-`close`, `linkParent`) that a future backend would swap in.
+`close`, `linkParent`, `parentOf`, `openCloserFor`, `prState`) that a future
+backend would swap in.
 
 You tell the conductor where to look with three keys, all in
 `~/.omp/conductor/config.json` (the [Configuration](#configuration) section has
@@ -164,6 +166,23 @@ Also required on the host:
   With neither, tier 2 degrades to a comment on the issue. Nothing is broken in
   that configuration: it is supported, just slower to reach you.
 
+## Updating
+
+Say “update conductor” from an operator shell or maintenance omp session outside
+the target `herdr-fleet.service`. The bundled `skill://conductor-update` discovers
+the installed and registry versions, drains active work, pins exact-pane recovery,
+replaces both independently installed plugins, restarts through
+`omp-conductor start`, re-arms through the existing Telegram proof, and verifies
+the layered status twice.
+
+The skill deliberately does not publish npm or edit an install root. It also
+refuses to run from the fleet pane it must replace: an updater that kills itself
+cannot verify the result. With skill commands enabled, invoke it directly with:
+
+```text
+/skill:conductor-update
+```
+
 ## Onboarding
 
 Onboarding this package has two layers, and installing it gives you both.
@@ -223,7 +242,7 @@ the file behind instead. So a re-run against a project that is already configure
 opens with one question:
 
 ```text
-"veltro" is already configured — what would you like to do?
+"platform" is already configured — what would you like to do?
 > Change one area
     asks one area's questions; every other answer is carried through from the saved config
   Walk every question again
@@ -235,14 +254,14 @@ says right now, so the row you want is the row you can see:
 
 ```text
 Which area? Each row shows what it says now
-  tracker & repos — veltrosecurity/veltro, queue "ready-for-agent", "repo:" → veltro, chad, warden, vectorflow
-  gates — veltro: none; chad: ruff check . @ backend, pnpm lint @ frontend; warden: ruff check . @ backen…
+  tracker & repos — acme/platform, queue "ready-for-agent", "repo:" → platform, api, web, worker
+  gates — platform: bun run check; api: ruff check . @ backend; web: pnpm lint…
   caps & worker model — 2 workers, 120 turns, 90m, $25/day, 2 attempts (all defaults) — harness default model
   code graph — not configured — workers grep
   authority — merge=orchestrator, release=orchestrator
-  escalation & triage — tier 2 pages Telegram 8236653927, comments too, triage external
+  escalation & triage — tier 2 pages Telegram 123456789, comments too, triage external
   reporting scope — material — escalations, plus green PRs, second failures, and anything that stops the fleet
-  orchestrator brief — none at /root/.omp/conductor/worktrees/ORCHESTRATOR.md
+  orchestrator brief — none at ~/.omp/conductor/worktrees/ORCHESTRATOR.md
 ```
 
 Only that area's questions are asked. Every other answer is read back out of
@@ -252,11 +271,11 @@ writes a config, and it still writes nothing before you agree. The consent scree
 leads with the delta and then shows the whole project as it would be written:
 
 ```text
-amending       code graph  —  project veltro
+amending       code graph  —  project platform
   was            not configured — workers grep
-  now            /root/.cache/conductor-graph/veltrosecurity — 4 clone(s): veltro, chad, warden, vectorflow
+  now            ~/.cache/conductor-graph/acme — 4 clone(s): platform, api, web, worker
   carried over   tracker & repos, gates, caps & worker model, authority, escalation & triage, reporting scope, orchestrator brief
-                 read back from /root/.omp/conductor/config.json and rewritten unchanged
+                 read back from ~/.omp/conductor/config.json and rewritten unchanged
 ```
 
 A first run, or a project name this config has never seen, never sees either
@@ -274,7 +293,7 @@ The standing prompt is two layers:
 
 | Layer | File | Updates how? |
 | --- | --- | --- |
-| Package floor | `src/briefs/orchestrator.md` | Every tick recomposes it into `ORCHESTRATOR.md` from the installed package. `npm install` + restart is enough. |
+| Package floor | `src/briefs/orchestrator.md` | Every tick recomposes it into `ORCHESTRATOR.md` from the installed package. Upgrade the package in this host's existing install root + restart is enough. |
 | Fleet policy | `POLICY.md` | Yours. Setup writes the scaffold once; the Learning loop edits only this file. |
 | Composed view | `ORCHESTRATOR.md` | Regenerated from floor + `POLICY.md` on each tick (and at setup). Do not hand-amend it for durable policy. |
 | Worker brief | `src/briefs/worker.md` | Read per run from the package. |
@@ -329,12 +348,22 @@ The **Learning loop** proposes diffs against `POLICY.md` for you to approve over
    omp-conductor start
    ```
 
-   `start` does not report success until the daemon actually answers
-   `GET /healthz`. Spawning is not starting: a daemon whose config is broken, whose
-   port is taken or whose database is locked exits within a second, and a `start`
-   that printed "started" for it would hand you a lie you discover only when work
-   silently fails to be picked up. On failure the error quotes the tail of
-   `daemon.log`. It refuses to start a second daemon, naming the pid of the live one.
+   `start` first starts `herdr-fleet.service` when that optional unit is installed,
+   clearing a previous `halt --pane` recovery pin so Herdr can resume the exact
+   conductor pane. Hosts without systemd or without that unit keep the standalone
+   daemon behaviour. It then waits until the daemon actually answers
+   `GET /healthz`; spawning is not starting. A daemon whose config is broken,
+   whose port is taken or whose database is locked exits within a second, and the
+   command fails with the tail of `daemon.log` instead of printing a false
+   success. It refuses to start a second daemon, naming the live pid. Starting
+   processes does not clear `pause` or arm ticks; those remain explicit operator
+   decisions.
+
+   Pane recovery spans two separately installed plugins: npm ships the omp
+   heartbeat/status half, while `herdr-conductor` supplies `recover.sh`. After an
+   npm upgrade, refresh the Herdr plugin from `TerrifiedBug/conductor/herdr` as
+   well; publishing or installing npm alone cannot add the recovery-side tick
+   request.
 
    For a first run, take a single tick in the foreground and watch it:
 
@@ -346,7 +375,56 @@ The loop ticks every 5 minutes. `omp-conductor stop` shuts the loop down after
 the current tick rather than mid-run. When the live process is the MainPID of
 `omp-conductor.service`, stop goes through `systemctl stop` so a unit with
 `Restart=on-failure` cannot bring it straight back; otherwise it is a raw
-`SIGTERM` (then `SIGKILL` after 10 seconds).
+`SIGTERM` (then `SIGKILL` after 10 seconds). An example unit (with
+`SuccessExitStatus=0 143` and `MemoryMax=5G`) ships as
+[`systemd/omp-conductor.service.example`](systemd/omp-conductor.service.example).
+
+
+### Stop the conductor (hold / halt)
+
+Four control planes used to answer "stop" differently. The package verbs:
+
+| Verb | Claiming | Tick sends | Dispatch daemon | Conductor pane |
+| --- | --- | --- | --- | --- |
+| `hold` | paused | disarmed | left running | left running |
+| `halt` | paused | disarmed | stopped (systemctl-aware) | left running |
+| `halt --pane` | paused | disarmed | stopped | stopped + recovery pinned off |
+| `pause` | paused | **still armed** | left running | left running |
+
+`resume` clears pause only and **never re-arms**. `arm` is proof-gated: it sends a Telegram challenge and writes the arm marker only after your reply appears as a *user* turn in the orchestrator transcript. `halt --pane` targets the configured conductor agent only — it does **not** run `systemctl stop herdr-fleet`.
+
+`status` prints a layered header (`dispatch` / `ticks` / next tick time / `pane` / `recovery` / `herdr` / `telegram` / `daemon`) so a paused fleet cannot hide an armed orchestrator still spending turns. The Telegram line calls the official `getMe` endpoint to prove the token and API are usable without sending a message, then separately reports whether the inbound bridge is configured.
+
+`halt --pane` is **fail-closed**: it exits `0` only when the conductor agent is
+*proven* gone. It writes the recovery pin first, so a failed stop still cannot be
+undone by `herdr-conductor` respawning the agent, and then refuses (nonzero exit,
+message on stderr) on every uncertainty:
+
+- no tick config exists at all — `recover.sh` reads only
+  `$FLEET_CWD/.conductor-pane-halted`, and without that file the pane's own
+  directory is unknown, so the pin would land somewhere recovery never looks and
+  the agent would be respawned seconds later. `release-pane` refuses for the
+  same reason, and `status` shows `recovery unpinnable` rather than `clear`
+- the tick config does not parse — the agent name would be a guess
+- `herdr agent list` is unreachable, prints nothing, or prints output with no
+  explicit `agents` array; only a real `agents: []` means "no agents"
+- an agent row is unreadable — a missing `name`/`pane_id`, or an `agent` field
+  present with a non-string value. An *absent* or `null` `agent` is the sticky
+  claim herdr reports after the agent exits, and stays a normal answer
+- the configured agent name is not unique, or the claimed pane runs some other agent
+- `pane process-info` fails, or the claim is live `omp` but names no recognizable
+  omp foreground PID — "cannot see it" is never reported as "it is stopped"
+- a signal cannot be delivered, or liveness cannot be probed — only `ESRCH`
+  ("no such process") proves death, so `EPERM` reads as "exists, not ours",
+  never as "stopped"
+- the process is still alive after `SIGTERM` then `SIGKILL`
+
+The pin is written to the pane's own directory (the one holding
+`.conductor-tick.json`, which is `FLEET_CWD` — the only place `recover.sh` looks),
+including when that tick config is the thing that failed to parse.
+
+Clear the pin with `omp-conductor release-pane` when you want recovery again.
+
 
 ## How one tick works
 
@@ -560,6 +638,40 @@ multi-repo request is a human decision about contracts; it is not something to
 infer from a label. Sending the issue back costs a label edit; guessing costs a
 bad merge.
 
+## Host sizing and memory
+
+Workers are **in-process** omp sessions inside the daemon's single PID (plus one
+long-lived orchestrator session). systemd's Memory peak for `omp-conductor.service`
+is therefore daemon + every live worker + the orchestrator + any MCP stdio
+children those sessions mount — not a separate worker process list.
+
+On the reference deploy that produced [issue #51](https://github.com/TerrifiedBug/conductor/issues/51):
+
+| Shape | Observed |
+| --- | --- |
+| Idle / workers restarting | ~430 MB RSS for the daemon alone |
+| Two workers + orchestrator, busy | **3.2–4.2 GB** Memory peak for the unit; up to ~800 MB swap |
+
+That peak is **expected for concurrent SDK sessions**, not evidence of a
+conductor-side leak: the SQLite store is disk-backed, admission state is
+per-tick, and worker sessions are disposed when a run ends. What grows is the
+session heap (conversation + tool output); a single graph-assisted run has been
+measured in the hundreds of thousands of characters of tool output.
+
+**Practical guidance**
+
+- Prefer **≥16 GiB RAM** for the default `maxConcurrentWorkers: 2`, and do **not**
+  co-locate ClickHouse / other multi-GB services beside that fleet on an ≤8 GiB
+  box.
+- On hosts under ~16 GiB, set `maxConcurrentWorkers` to **1**. `/conductor setup`
+  does this automatically when it can read host RAM.
+- Supervise the daemon with a unit that sets `SuccessExitStatus=0 143` and a
+  `MemoryMax=` just above your expected peak. A ready-to-edit example ships as
+  [`systemd/omp-conductor.service.example`](systemd/omp-conductor.service.example)
+  (`MemoryMax=5G` for the two-worker shape).
+- `omp-conductor status` prints daemon `rss` from `/healthz` when the process is
+  up, so you can see pressure without scraping journald.
+
 ## Caps
 
 Caps resolve per project: the global `defaults` block, then the project's own
@@ -568,7 +680,7 @@ rest. `0` is a real value (a hard stop), not "unset".
 
 | Cap | Default | What it protects |
 | --- | --- | --- |
-| `maxConcurrentWorkers` | `2` | Parallel omp sessions. 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. Raise it only if you actually have the runners. |
+| `maxConcurrentWorkers` | `2` (setup may write `1` on <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`. |
 | `workerMaxTurns` | `120` | Turn ceiling for one worker. Catches a session looping without converging. |
 | `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. |
@@ -958,7 +1070,7 @@ indistinguishable from the first:
 ```text
 [omp-conductor] orchestrator tick inactive: pane w1:p1 (agent "fleet") owns the fleet tick here — this session will not tick
 [omp-conductor] orchestrator tick inactive: this pane is agent "scratch", not the fleet agent "fleet" — this session will not tick
-[omp-conductor] orchestrator tick inactive: pid 4147344 (claimed 2026-08-07T07:55:36.001Z, session …/fleet.jsonl) owns the fleet tick in /root/.omp/conductor — this session will not tick
+[omp-conductor] orchestrator tick inactive: pid 12345 (claimed 2026-01-02T03:04:05.000Z, session …/fleet.jsonl) owns the fleet tick in /home/conductor/.omp/conductor — this session will not tick
 ```
 
 A `herdr agent list` that does not answer also declines, for the same reason the
@@ -1079,9 +1191,15 @@ least of all on a fleet whose session lives somewhere else.
 
 ```bash
 omp-conductor start [--port N] [--project NAME]
+omp-conductor --version
 omp-conductor stop
 omp-conductor restart [--port N] [--project NAME]
 omp-conductor status [--project NAME]
+omp-conductor hold [--project NAME]
+omp-conductor halt [--pane] [--project NAME]
+omp-conductor arm [--project NAME]
+omp-conductor disarm [--project NAME]
+omp-conductor release-pane [--project NAME]
 omp-conductor tail <issue> [--project NAME]
 omp-conductor unblock <issue> [--project NAME]
 omp-conductor daemon [--once] [--port N] [--project NAME]
@@ -1094,18 +1212,24 @@ omp-conductor help
 
 | Command | Behaviour |
 | --- | --- |
-| `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`. |
+| `start` | Start `herdr-fleet.service` when that optional unit is installed, clearing a previous pane-recovery pin, then spawn the dispatch loop in the background and wait until it answers `GET /healthz` on `:8787`. Without systemd or that unit it keeps the standalone daemon behaviour. It never clears pause or arms ticks. Refuses if a daemon is already live, naming its pid; if the process dies or never serves, it cleans up and quotes the tail of `daemon.log`. |
 | `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). |
-| `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. While live workers > 0, prints a `deploy` line naming the count so a busy restart is visible before you take it. 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. |
+| `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `daemon`, then the project body. The next time 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. The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
+| `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. |
+| `arm [--project NAME]` | Proof-gated: send a Telegram challenge and write the arm marker only after your reply appears as a user turn in the orchestrator transcript. Never auto-armed by `resume` / `hold`. |
+| `disarm [--project NAME]` | Remove the arm marker so ticks skip. Processes untouched. |
+| `release-pane [--project NAME]` | Clear the `halt --pane` recovery pin so herdr-conductor may resume the fleet agent again. |
 | `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. The orchestrator heartbeat keeps ticking — its gate is the arm marker, not this flag. |
-| `resume` | Allow claiming again. |
+| `pause` | Stop claiming new work only. The running daemon notices on its next tick; runs already in flight finish. The orchestrator heartbeat keeps ticking if armed — its gate is the arm marker, not this flag. Prefer `hold` to silence both. |
+| `resume` | Clear pause only — does **not** re-arm. Run `arm` after an inbound Telegram proof to resume ticks. |
+| `--version`, `-V`, `version` | Print the installed `omp-conductor` package version and exit `0`. Works from the global binary and npm/plugin install because it reads the package metadata beside the shipped CLI. |
 | `graph-setup` | Print how to set up the code-graph indexes workers query instead of grepping: a `git clone` for every index-only clone that does not exist yet, the one-shot index command per repo, and a `cbm-reindex.service` + `cbm-reindex.timer` pair generated from the project's own repos and branches. Reads only, so it is safe on a host where you are not root. Exits `1` when no repo in the project has [`graphProject`](#configuration) set, because the fix is a wizard answer rather than a flag. See [Code-graph discovery](#code-graph-discovery). |
 | `--write` | Only for `graph-setup`. Writes the refresh script into the state directory and the two units into `/etc/systemd/system`, then prints the exact `systemctl daemon-reload && systemctl enable --now cbm-reindex.timer` to run. It never runs `systemctl` itself and never enables anything: that needs root, and a package that enables system timers behind your back is one you cannot audit by reading its output. |
 | `brief-upgrade` | Inspect the package-floor + `POLICY.md` overlay. Reports by default; see [Keeping a brief current](#keeping-a-brief-current). |
@@ -1116,12 +1240,14 @@ omp-conductor help
 | `help`, `--help`, `-h` | Print usage. An unknown or missing verb prints it too, and exits `2`. |
 
 Pause is a flag file under the state directory, so it applies to every project and
-survives a daemon restart.
+survives a daemon restart. Hold also removes the arm marker the heartbeat reads,
+so both brains go quiet without killing processes.
 
-Four of these are available in-session as `/conductor setup`, `/conductor status`,
-`/conductor pause` and `/conductor resume`, each taking an optional project name as
-a second word. Background-process management is CLI-only: the plugin does not
-start, stop or restart the daemon.
+These are available in-session as `/conductor setup`, `/conductor status`,
+`/conductor hold`, `/conductor halt [--pane]`, `/conductor arm`, `/conductor disarm`,
+`/conductor release-pane`, `/conductor pause` and `/conductor resume`, each taking
+an optional project name. Background-process management (`start` / `stop` /
+`restart`) is CLI-only: the plugin does not start, stop or restart the daemon.
 
 ### Health endpoint
 
@@ -1162,23 +1288,30 @@ The worker ends with a six-line evidence report (issue, pr, state, gates, change
 next). `pushed-green` means it watched the checks go green rather than expecting
 them to.
 
-### The boundary is prompt text — and one tripwire
+### Worker confinement and the integrity 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.
+A worker session is rooted at its worktree `cwd`. **Structured file tools are
+gated mechanically:** `runWorker` asks `createSession({ confineToCwd: true })`,
+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
+`routing.repos` is ever checked out — and the caps still bound *how much* work
+happens.
 
-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.
+**`bash` is not gated.** Its argument is an opaque shell string; pretending to
+parse it would be a false sense of security. The brief still forbids escaping
+via the shell, and the deploy-level answer is a least-privilege worker uid
+(below).
+
+#### Integrity tripwire (package self-hash)
+
+Separately, the conductor watches *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
@@ -1187,9 +1320,32 @@ 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.
+This catches a worker (or human) that still managed to edit the live install —
+including via `bash` — after the fact. It is detection for the package boundary,
+not a substitute for the worktree gate or a dedicated uid.
+
+#### Least-privilege worker uid (deploy)
+
+The largest remaining win is OS-level: run the daemon (or at least worker
+sessions, when the harness supports a uid switch) as a user that can write only
+its worktrees and mirrors. A sketch that matches the reference single-host
+deploy:
+
+1. Create a system user, e.g. `conductor-worker`, with home under
+   `/var/lib/conductor-worker` (or similar).
+2. `chown` the project's `workspaceRoot` and `mirrorRoot` to that user; leave
+   `~/.omp/conductor/config.json` readable only by the operator/daemon account
+   (`0600` as shipped).
+3. Do **not** put the worker uid in `docker` / `sudoers`, and do not give it the
+   operator's `gh` auth if a narrower deploy token can open PRs in the routed
+   repos alone.
+4. Point the [example systemd unit](systemd/omp-conductor.service.example)
+   `User=` / `Group=` at that account once the daemon itself should run
+   unprivileged end-to-end.
+
+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.
 
 ## Limitations
 
@@ -1241,15 +1397,16 @@ 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`.
-- **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.
+- **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.
+
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.13",
+  "version": "0.3.16",
   "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.",
@@ -17,12 +17,13 @@
     ]
   },
   "bin": {
-    "omp-conductor": "./src/cli.ts"
+    "omp-conductor": "src/cli.ts"
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
     "skills",
+    "systemd",
     "README.md",
     "LICENSE"
   ],