omp-conductor 0.3.13 → 0.3.15

package/README.md

@@ -36,14 +36,15 @@ The package ships three deployables, plus one skill:
 
 | 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). |
 
 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
@@ -274,7 +276,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. |
@@ -346,7 +348,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` / `pane` / `recovery` / `herdr` / `daemon`) so a paused fleet cannot hide an armed orchestrator still spending turns.
+
+`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 +611,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 +653,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. |
@@ -1082,6 +1167,11 @@ omp-conductor start [--port N] [--project NAME]
 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]
@@ -1097,15 +1187,20 @@ 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` | 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` / `pane` / `recovery` / `herdr` / `daemon`, then the project body (caps, active runs, today's usage). The `daemon` block includes `rss` from `/healthz` when the process is up (workers share that PID — see [host sizing](#host-sizing-and-memory)). 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. |
+| `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. |
 | `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 +1211,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 +1259,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 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.
 
-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.
+**`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).
 
-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.
+#### 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 +1291,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
 
@@ -1243,13 +1370,13 @@ Known and deliberate in this version:
   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.
+- **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.15",
   "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.",
@@ -23,6 +23,7 @@
     "src",
     "!src/**/*.test.ts",
     "skills",
+    "systemd",
     "README.md",
     "LICENSE"
   ],

package/src/brief-upgrade.ts

@@ -573,7 +573,7 @@ export function formatBriefStatus(path: string, status: BriefStatus): string {
       `  floor        package template → recomposed into ${status.orchestratorPath} each tick`,
       `  policy       ${status.policyPath} (Learning loop / operator edits)`,
       "",
-      "Protocol updates: npm install omp-conductor@… and restart — no brief-upgrade --apply.",
+      "Protocol updates: upgrade omp-conductor in this host's existing install root (same package manager), then restart the daemon — no brief-upgrade --apply.",
       "Legacy migrate:   omp-conductor brief-upgrade --migrate",
     ].join("\n");
   }

package/src/briefs/orchestrator.md

@@ -3,8 +3,9 @@
 This file is the **package floor**: duties, tiers, hard boundaries, and the
 Learning loop. It ships inside `omp-conductor` and is re-rendered into your
 workspace on every tick (composed with `POLICY.md` as `ORCHESTRATOR.md` for the
-session). Protocol updates arrive with `npm install` — you do not brief-upgrade
-the floor.
+session). Protocol updates arrive when you upgrade the installed `omp-conductor`
+package (same package manager / install root) and restart — you do not
+brief-upgrade the floor.
 
 Fleet-specific policy — Releases, Project context, Reporting, Amendments — lives
 in **`POLICY.md`** beside this composed brief. The Learning loop edits

package/src/briefs/worker.md

@@ -15,7 +15,7 @@ inside your own worktree.
 - **Code repo:** {{REPO}}
 - **Your worktree (cwd):** `{{WORKTREE}}`
 - **Your branch:** `{{BRANCH}}` — already created for you off the repo's default
-  branch. Never switch branches and never touch a path outside the worktree.
+  branch. Never switch branches and never touch a path outside the worktree (write/edit/read/grep/glob are also blocked mechanically outside this checkout; `bash` is still a must-not — do not use it to escape).
 
 Read the issue first — it carries the acceptance criteria and any discussion the
 dispatcher did not copy down:

package/src/cli.ts

@@ -21,12 +21,21 @@ import {
   writeMergedBrief,
 } from "./brief-upgrade.ts";
 import { findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
-import { dbPath, formatStatus, runDaemon, setPaused, statusSnapshot } from "./daemon.ts";
+import { dbPath, runDaemon, setPaused } from "./daemon.ts";
+import {
+  armTicks,
+  clearPaneHalt,
+  disarmTicks,
+  halt,
+  haltWithPane,
+  hold,
+  releaseHold,
+  renderStatus,
+} from "./fleet.ts";
 import { formatGraphSetup, graphRepos, writeGraphSetup, type GraphSetupWrite } from "./graph.ts";
 import {
   clearRecord,
   DEFAULT_PORT,
-  healthCheck,
   livingDaemon,
   restartDaemon,
   startDaemon,
@@ -53,6 +62,11 @@ usage:
   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]
@@ -73,8 +87,22 @@ usage:
            dirty live worktrees before orphaning those rows — see README
            "Deploying a new package onto a busy fleet". Goes through systemctl
            when the unit owns the live pid.
-  status   show pause state, caps, active runs, today's usage, and whether a
-           daemon is alive.
+  status   layered fleet report: dispatch (running|paused|stopped), ticks
+           (armed|disarmed|…), pane, herdr, daemon — then caps and active runs.
+  hold     soft stop: pause claiming AND disarm ticks. Daemon and pane stay up.
+           This is "stop the conductor overnight" without killing processes.
+  halt     hold, then stop the dispatch daemon (systemctl-aware). Pane stays up
+           unless --pane is passed.
+  halt --pane
+           halt, then pin herdr-conductor recovery off for the conductor agent
+           only — does NOT stop herdr-fleet.service or any other herdr session.
+           Clear the pin with release-pane when you want recovery again.
+  arm      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   remove the arm marker so ticks skip. Processes untouched.
+  release-pane
+           clear the halt --pane recovery pin so herdr-conductor may resume again.
   tail     follow the newest run for <issue>: the worker's assistant text and
            the tools it calls, printed as they land. Workers are sessions inside
            the daemon rather than terminals, so this is the only way to watch
@@ -87,8 +115,8 @@ usage:
            cost a worker.
   daemon   run the dispatch loop in the foreground; --once runs a single tick
            and exits. This is what \`start\` launches.
-  pause    stop claiming new work. The running daemon notices on its next tick.
-  resume   allow claiming again.
+  pause    stop claiming new work only (ticks keep firing if armed). Prefer hold.
+  resume   clear pause only — does NOT re-arm. Prefer hold's inverse: resume + arm.
   graph-setup
            print how to set up the code-graph indexes workers query instead of
            grepping: the clone commands for any missing index-only clone, the
@@ -107,10 +135,18 @@ usage:
   help     print this text (also --help, -h).
 
 Pause is a flag file under the state directory, so it applies to every project
-and survives a daemon restart. A running daemon is tracked by a pidfile under
-$OMP_CONDUCTOR_RUNTIME_DIR (default ~/.omp/run/daemons/omp-conductor), written
-whether it was started in the background or in the foreground, and probed for
-liveness on every read — a stale one never blocks a start.`;
+and survives a daemon restart. Hold also removes the arm marker the heartbeat
+reads, so both brains go quiet without killing processes. A running daemon is
+tracked by a pidfile under $OMP_CONDUCTOR_RUNTIME_DIR (default
+~/.omp/run/daemons/omp-conductor), written whether it was started in the
+background or in the foreground, and probed for liveness on every read — a
+stale one never blocks a start.
+
+Stop the conductor:
+  hold              no claims, no tick sends (inspectable)
+  halt              hold + stop dispatch daemon
+  halt --pane       halt + pin conductor-pane recovery off
+  resume && arm     clear pause, then prove inbound Telegram before ticks resume`;
 
 /** Accepts both `--port 9000` and `--port=9000`; returns undefined when absent. */
 function flag(argv: string[], name: string): string | undefined {
@@ -146,26 +182,6 @@ function humanDuration(ms: number): string {
   return `${Math.floor(h / 24)}d ${String(h % 24).padStart(2, "0")}h`;
 }
 
-/**
- * The daemon half of `status`. Kept separate from `formatStatus` because the
- * pidfile and the endpoint are the CLI's business, not the dispatcher's, and
- * because a pid without a `/healthz` answer is a distinct — and interesting —
- * state: the process is up but the loop is not serving.
- */
-async function daemonSection(): Promise<string> {
-  const rec = livingDaemon();
-  if (rec === undefined) return "daemon    not running";
-  const health = await healthCheck(rec.port);
-  return [
-    "daemon",
-    `  pid       ${rec.pid}`,
-    `  uptime    ${humanDuration(Date.now() - rec.startedAt)}`,
-    `  port      ${rec.port}`,
-    ...(rec.project === undefined ? [] : [`  project   ${rec.project}`]),
-    `  healthz   ${health.ok ? `ok  ${health.body ?? ""}`.trimEnd() : "unreachable — the process is up but not serving"}`,
-    `  log       ${rec.logFile}`,
-  ].join("\n");
-}
 
 /**
  * The orchestrator half, and the one thing `status` has ever known about the
@@ -456,9 +472,84 @@ try {
     }
 
     case "status": {
-      const snapshot = formatStatus(statusSnapshot(flag(argv, "project")));
+      const project = flag(argv, "project");
+      const text = await renderStatus(project);
       const stalled = stallLine();
-      process.stdout.write(`${snapshot}\n\n${await daemonSection()}\n${stalled === undefined ? "" : `\n${stalled}\n`}`);
+      process.stdout.write(`${text}${stalled === undefined ? "\n" : `\n\n${stalled}\n`}`);
+      break;
+    }
+
+    case "hold": {
+      const r = hold(flag(argv, "project"));
+      process.stdout.write(
+        `held — claiming paused` +
+          `${r.wasPaused ? " (already paused)" : ""}` +
+          `; ticks disarmed at ${r.disarmed.path}` +
+          `${r.disarmed.wasArmed ? "" : " (was already disarmed)"}\n` +
+          `daemon and pane left running; halt to stop the daemon\n`,
+      );
+      break;
+    }
+
+    case "halt": {
+      const project = flag(argv, "project");
+      const withPane = argv.includes("--pane");
+      if (withPane) {
+        const r = await haltWithPane(project);
+        const stopLine =
+          r.stop.kind === "not-running"
+            ? "daemon was not running"
+            : `daemon stopped — pid ${r.stop.pid}${r.stop.via === "systemctl" ? " (via systemctl)" : ""}`;
+        process.stdout.write(
+          `halted — claiming paused; ticks disarmed at ${r.hold.disarmed.path}\n` +
+            `${stopLine}\n` +
+            `pane recovery pinned at ${r.pane.pinPath}\n` +
+            `pane stop: ${r.pane.stopped} — ${r.pane.detail}\n` +
+            `  (conductor agent "${r.pane.agentName}" only — herdr-fleet.service was NOT stopped;\n` +
+            `   release-pane clears the pin when you want recovery again)\n`,
+        );
+      } else {
+        const r = await halt(project);
+        const stopLine =
+          r.stop.kind === "not-running"
+            ? "daemon was not running"
+            : `daemon stopped — pid ${r.stop.pid}${r.stop.via === "systemctl" ? " (via systemctl)" : ""}`;
+        process.stdout.write(
+          `halted — claiming paused; ticks disarmed at ${r.hold.disarmed.path}\n` +
+            `${stopLine}\n` +
+            `pane left running (pass --pane to stop the conductor agent and pin recovery)\n`,
+        );
+      }
+      break;
+    }
+
+    case "arm": {
+      process.stdout.write("arm: sending inbound Telegram challenge…\n");
+      const r = await armTicks(flag(argv, "project"));
+      process.stdout.write(
+        `ARMED — inbound round-trip proved with owner ${r.owner}; ticks are now live.\n` +
+          `marker ${r.path}${r.alreadyArmed ? " (replaced previous marker)" : ""}\n`,
+      );
+      break;
+    }
+
+    case "disarm": {
+      const r = disarmTicks(flag(argv, "project"));
+      process.stdout.write(
+        `disarmed — ticks will be skipped` +
+          `${r.wasArmed ? "" : " (was already disarmed)"}\n` +
+          `marker ${r.path}\n`,
+      );
+      break;
+    }
+
+    case "release-pane": {
+      const r = clearPaneHalt(flag(argv, "project"));
+      process.stdout.write(
+        r.wasHalted
+          ? `pane recovery pin cleared — ${r.path}\nherdr-conductor may resume the fleet agent again\n`
+          : `no pane recovery pin at ${r.path}\n`,
+      );
       break;
     }
 
@@ -484,12 +575,18 @@ try {
 
     case "pause":
       setPaused(true);
-      process.stdout.write("paused — no new work will be claimed\n");
+      process.stdout.write(
+        "paused — no new work will be claimed\n" +
+          "note: ticks keep firing if armed; use hold to silence both\n",
+      );
       break;
 
     case "resume":
-      setPaused(false);
-      process.stdout.write("resumed — work will be claimed on the next tick\n");
+      releaseHold();
+      process.stdout.write(
+        "resumed — claiming allowed on the next tick\n" +
+          "note: did NOT re-arm; run arm after an inbound Telegram proof to resume ticks\n",
+      );
       break;
 
     case "graph-setup": {