omp-conductor 0.3.4 → 0.3.6

package/README.md

@@ -38,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, and marks the session stalled when its prompts stop being consumed. 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 — 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
@@ -170,7 +170,7 @@ Onboarding this package has two layers, and installing it gives you both.
 
 | Layer | What it is | What it owns |
 | --- | --- | --- |
-| **`/conductor setup`** | The deterministic wizard. Closed questions, a label plan, a dry run, one confirm. | **Mechanical config.** It is the only thing that writes `config.json`, and it mutates nothing before you confirm. |
+| **`/conductor setup`** | The deterministic wizard. Closed questions, a label plan, a dry run, one confirm. On a project it already knows, it offers to amend one area instead of re-asking everything — see [Changing one setting](#changing-one-setting). | **Mechanical config.** It is the only thing that writes `config.json`, and it mutates nothing before you confirm. |
 | **`skill://conductor-onboarding`** | A skill bundled in this package (`skills/conductor-onboarding/SKILL.md`), discovered automatically by any omp session once the plugin is installed. | **Brief authoring.** The judgement the wizard cannot prompt for. |
 
 The split exists because the two halves fail differently. A wrong config value is
@@ -215,6 +215,59 @@ turned on you can also invoke it directly:
 Nothing about the wizard changes: `/conductor setup` on its own remains a
 complete, supported path, and the brief it renders is safe unedited.
 
+### Changing one setting
+
+`config.json` is wizard-written, so changing a value means running the wizard —
+and a wizard that re-asks twenty questions to add one key is a wizard people edit
+the file behind instead. So a re-run against a project that is already configured
+opens with one question:
+
+```text
+"veltro" 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
+    the full interview, every prompt pre-filled with what is configured now
+```
+
+Amending is the default. Pick it and the eight areas are listed with what each one
+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…
+  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
+  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
+```
+
+Only that area's questions are asked. Every other answer is read back out of
+`config.json` and written again unchanged — the same answers, the same builder,
+the same single confirm, so there is still exactly one thing in this package that
+writes a config, and it still writes nothing before you agree. The consent screen
+leads with the delta and then shows the whole project as it would be written:
+
+```text
+amending       code graph  —  project veltro
+  was            not configured — workers grep
+  now            /root/.cache/conductor-graph/veltrosecurity — 4 clone(s): veltro, chad, warden, vectorflow
+  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
+```
+
+A first run, or a project name this config has never seen, never sees either
+question: there is nothing to amend, so it is the full interview exactly as
+before. Choosing *Walk every question again* is also unchanged — every prompt
+pre-filled with what is configured, Enter to keep it — with one wrinkle worth
+knowing: the two authority confirms and the orchestrator-session confirm cannot
+start on "yes", so Entering through the full interview **revokes** a delegation
+rather than renewing it. Amending the `authority` area names the current grant in
+the question, which is the safer way to leave one alone.
+
 ### Keeping a brief current
 
 Upgrading the package does not upgrade a brief you are already running, and it is
@@ -524,6 +577,95 @@ honour the pattern it says so, and the daemon logs that per run:
 Worth reading the log for. A run that quietly used a weaker model than you chose
 otherwise looks like a run that was merely unlucky.
 
+## Code-graph discovery
+
+Optional, off unless you answer yes in the wizard, and worth answering yes to for
+one measured reason: **workers spend most of a run finding code, not changing it.**
+On the dogfood fleet a single run typically spends 30–62 `read` calls and 32–69
+`bash` calls against 9–24 edits — 215–390k characters of tool output, roughly four
+fifths of a 120-turn budget — and the runs that died at the turns cap died with
+the work unfinished. A code graph answers "who calls this" and "where is this
+defined" in one call instead of twenty greps.
+
+### Two things this package does not do for you
+
+`omp-conductor` never installs, spawns, imports or depends on the indexer — with
+`graphProject` unset, nothing about dispatch, caps or escalation changes. That
+means a fresh host needs both of these before an index is worth anything, and
+`graph-setup` reports them as step 0:
+
+1. **`codebase-memory-mcp` on PATH** — a separate project,
+   [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp).
+2. **Mounted as an MCP server** in `~/.omp/agent/mcp.json`, on the account the
+   daemon runs as. Miss this and the failure is silent: every index builds
+   correctly, no worker session can read any of them, so workers fall back to
+   grepping and the feature looks like a no-op. `graph-setup` prints the entry.
+
+Say yes and the wizard asks for one root, then derives one clone per routed repo
+underneath it (default `~/.cache/conductor-graph/<org>/<repo>`) and writes it to
+each repo's [`graphProject`](#configuration). Nothing else changes: this package
+never runs an indexer, never imports one, and behaves identically with the graph
+server absent — dispatch, caps and escalation do not know it exists. On a fleet
+that was configured before this key existed, `/conductor setup` and the `code
+graph` area add it in two prompts — see
+[Changing one setting](#changing-one-setting).
+
+### Why the clone, and not your checkout or the worktree
+
+This is the part that decides whether the feature helps or hurts, so it is worth
+being blunt about all three candidates.
+
+| Directory | Why not |
+| --- | --- |
+| **The worker's worktree** | An index is keyed by the realpath of the directory it was built from, and has no git-worktree awareness. A run's `worktrees/<issue>` path is therefore *always* an empty project — a worker that queried its own cwd would get silence, conclude there is no graph, and spend the run grepping. This is why `graphProject` is an absolute path in the config and not something derived at run time. |
+| **Your own checkout** | Refreshing an index means resetting the clone to its default branch. In a directory you work in, that either destroys uncommitted work or — if it is made safe instead — indexes whatever feature branch you left checked out, so the fleet orients against your WIP. |
+| **A conductor mirror** | The daemon's mirrors are bare. There is no working tree to index. |
+
+So `graphProject` names a fourth thing: a clone that exists only to be indexed,
+that nothing human ever edits, and that is therefore safe to `git reset --hard`
+every night. The worker brief names that path, tells the session to match it
+against `list_projects`' `root_path` and query by the `name` beside it, and says
+plainly that the graph is a snapshot which does **not** contain the worker's own
+edits — orient with it, then read the real file before changing it.
+
+### Creating and refreshing them
+
+```bash
+omp-conductor graph-setup            # print the plan: clones, index commands, units
+omp-conductor graph-setup --write        # stage the script and the two units (no root)
+```
+
+`graph-setup` prints a `git clone` for every clone that does not exist yet, the
+one-shot index command per repo, and a `cbm-reindex.service` + `cbm-reindex.timer`
+pair built from the project's own repos and branches. `--write` stages all three
+in the state directory and prints the two `sudo` lines that install and enable
+them; it never runs `systemctl`.
+
+**Run it as the account the fleet runs as, never under `sudo`** — it refuses if
+you try. Everything it derives resolves per-account: the config it loads, the
+state directory it stages into, and the `HOME`/`User=` it bakes into the unit.
+Under root you get a timer that goes green while writing indexes into
+`/root/.cache`, where no worker session looks — silent, and indistinguishable
+from the feature simply not helping. Only installing the units needs root, which
+is why that is two separate printed commands.
+
+Two properties of the generated unit are deliberate:
+
+- **It is a timer, not the server's own watcher.** That watcher lives inside a
+  connected MCP session and dies with it, so an ephemeral worker session keeps
+  nothing fresh. The refresh has to come from outside the fleet.
+- **It fails loudly.** The refresh is `set -euo pipefail`, then per repo
+  `git fetch --prune origin` and `git reset --hard origin/<its own defaultBranch>`
+  before indexing. Nothing is `|| true`-ed, so a fetch that has been broken for a
+  week turns the unit red instead of quietly re-indexing a stale tree and exiting
+  `0` — a green timer serving a month-old graph is worse than no graph at all.
+
+The unit spells out `HOME` and an explicit `PATH`, because systemd supplies
+neither usefully: the indexer resolves its store from `HOME`, systemd's default
+`PATH` has no `~/.local/bin`, and the indexer shells out to `git`. Both are the
+user that ran `graph-setup`; the unit sets no `User=`, so check them if that is
+not the account the timer runs as.
+
 ## Escalation tiers
 
 | Tier | Meaning | Raised by | Delivered to |
@@ -600,6 +742,10 @@ The file is validated on every read. A malformed config produces one readable er
 listing every fault, and the daemon refuses to start rather than running with half
 a project.
 
+`/conductor setup` is the only thing here that writes this file, and on a project
+it already knows it can rewrite one area of it without re-asking the rest — see
+[Changing one setting](#changing-one-setting).
+
 `version` is `2`. A `version: 1` file still loads: caps it names that this build no
 longer enforces are dropped rather than treated as typos, and the next save writes
 it back as `2`. In a `version: 2` file an unrecognised cap key **is** an error,
@@ -638,7 +784,8 @@ A complete, valid config for one project with two target repos:
             "gates": [
               { "cmd": "bun run lint", "cwd": "." },
               { "cmd": "bun test", "cwd": "." }
-            ]
+            ],
+            "graphProject": "~/.cache/conductor-graph/acme/api"
           },
           "worker": {
             "name": "worker",
@@ -687,6 +834,7 @@ Field notes:
 | `routing.labelPrefix` | Optional; defaults to `repo:`. |
 | `routing.repos` | At least one entry, or nothing can be routed. `name` defaults to the map key, `defaultBranch` to `main`. |
 | `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. |
+| `graphProject` | Optional, per repo. Absolute path of the **index-only clone** whose code graph this repo's workers query — conductor's own disposable clone, pinned to the repo's default branch, never a checkout you work in and never a worker's worktree. Written by the wizard; `~` is expanded, and a relative path is an error rather than something resolved against whichever cwd happened to read the file. Absent means this repo has no graph and its briefs say nothing about one. See [Code-graph discovery](#code-graph-discovery). |
 | `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. |
@@ -723,7 +871,8 @@ in the orchestrator's working directory:
 | `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>: 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. |
+| `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 project's `workspaceRoot`, because a standing prompt drifts out of a long-lived session's context while the file on disk does not. |
+| `agentName` | no | `fleet` | The herdr agent name the orchestrator's pane is registered under. Under herdr this is the whole of the identity check below, and the default matches `AGENT_NAME=${AGENT_NAME:-fleet}` in the recovery plugin's `recover.sh`, so both halves key on one name. Rename the agent and set this to match. |
 
 A tick sends one message (`customType` `omp-conductor.tick`, attributed to the
 user): the standing-loop prompt, the one constraint line the project's
@@ -737,8 +886,6 @@ 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
-  flag the dispatch loop reads, so pausing the fleet pauses its heartbeat;
 - `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
@@ -746,6 +893,53 @@ It sends **nothing** when:
   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.
 
+### One session per directory ticks, and it says which
+
+Activation is a property of the *directory*, so before it arms anything the
+heartbeat asks whether this session is the orchestrator or merely a session
+standing in its directory. It has to: opening a second omp session in the fleet's
+cwd — a shell to read state, say — used to arm a second heartbeat that prompted
+*that* session with the standing loop, and with
+[`authority`](#configuration) delegated it would consider itself entitled to
+merge PRs and cut releases. Two brains, one queue, and nothing in the log to tell
+them apart.
+
+**Under herdr** (`HERDR_ENV=1` with a `HERDR_PANE_ID`), the answer is the pane's
+registered agent name: the heartbeat asks `herdr agent list` for the entry whose
+`pane_id` is this pane's and ticks only when its `name` equals `agentName`. Fleetness
+is the *session* — every pane in it shares `HERDR_SESSION` and the cwd — and
+herdr's `agent` field is the *runtime*, `omp` for the orchestrator and for the
+shell beside it, so neither can tell them apart. The registered name can, it is
+what `herdr agent start fleet --kind omp --pane <id>` sets, and it is the same
+identity the recovery plugin keys on. A pane with a different name, or no name at
+all, stays inert.
+
+**Without herdr**, the session claims the directory in a sibling
+`.conductor-tick-owner.json` (pid, session file, claim time) and ticks only while
+it is the live claimant. Liveness is a **pid check, never a timestamp**: a crashed
+orchestrator's claim is reclaimed by the next session rather than wedging the
+fleet until somebody deletes a file, and a slow-but-running orchestrator never
+loses its claim to a lease that expired.
+
+Declining is logged once, at session start, naming the holder — which is the whole
+point, because the original failure was that the second ticker was
+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
+```
+
+A `herdr agent list` that does not answer also declines, for the same reason the
+escalation channel fails closed: under herdr this session is one pane of several
+in that directory, and an unproven identity is exactly the case the check exists
+for. That includes `herdr` not being on the session's `PATH` — worth checking on a
+fleet host, where the orchestrator's environment comes from a unit file rather
+than a login shell — and `HERDR_BIN_PATH` names the binary when it is not, the
+same escape hatch the recovery plugin's `recover.sh` has. On a host with no herdr
+and no prior claimant — the ordinary single-session case — nothing changes.
+
 ### The escalation channel is a gate, and it fails closed
 
 Unattended dispatch is only defensible while a tier-2 escalation can reach a
@@ -863,6 +1057,7 @@ omp-conductor unblock <issue> [--project NAME]
 omp-conductor daemon [--once] [--port N] [--project NAME]
 omp-conductor pause
 omp-conductor resume
+omp-conductor graph-setup [--project NAME] [--write]
 omp-conductor brief-upgrade [--apply] [--file PATH] [--project NAME]
 omp-conductor help
 ```
@@ -881,6 +1076,8 @@ omp-conductor help
 | `--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. |
+| `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` | 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. |
 | `--file PATH` | Only for `brief-upgrade`. Check a brief that is not where the wizard would have put it, on a host that may have no config at all. |
@@ -921,6 +1118,7 @@ dispatcher. The brief is explicit about the boundary:
 | It may | It must not |
 | --- | --- |
 | Read the issue and the repo's own guidance (`AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, relevant ADRs) before writing anything. | Touch any path outside its worktree, or switch branches. |
+| Query its repo's [code graph](#code-graph-discovery), when one is configured, by the project name whose `root_path` matches the clone its brief names. | Query that graph by its own cwd or worktree path — no index of a worktree exists — or treat what it returns as current. It is a snapshot of the clone's default branch; the real file in the worktree wins. |
 | Edit code inside its own worktree. | Weaken, skip, delete or loosen **any test it did not write** — that is a design question to escalate, and it is checked by diff review before the push. |
 | Add or update tests for behaviour it introduced. | Suppress a warning, delete an assertion, or special-case an input to make a check pass. |
 | Run the repo's configured cheap gates, each from its listed `cwd`, over the whole tree. | Run docker or image builds, production builds, browser/e2e suites, or the full test suite on the shared host — CI owns the heavy gates. |

package/package.json

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

@@ -1,6 +1,6 @@
 ---
 name: conductor-onboarding
-description: Interview-driven onboarding for omp-conductor. Use when the user wants to set up conductor, onboard a new fleet or project, configure the fleet, asks for conductor setup help, asks what belongs in ORCHESTRATOR.md, or wants an agent's release and merge authority scoped and written down. Interviews the operator on release policy, escalation taste and reporting scope, reads each routing repo's CI to propose the real pre-push gates, learns the product and roadmap the fleet will groom, scaffolds the release procedure from the repo's own release workflows rather than from the operator's memory, tailors ORCHESTRATOR.md from the shipped template, verifies the worker brief's assumptions against the actual repos, then finishes through the deterministic /conductor setup wizard.
+description: Interview-driven onboarding for omp-conductor. Use when the user wants to set up conductor, onboard a new fleet or project, configure the fleet, asks for conductor setup help, asks what belongs in ORCHESTRATOR.md, or wants an agent's release and merge authority scoped and written down. Interviews the operator on release policy, escalation taste and reporting scope, reads each routing repo's CI to propose the real pre-push gates, learns the product and roadmap the fleet will groom, scaffolds the release procedure from the repo's own release workflows rather than from the operator's memory, tailors ORCHESTRATOR.md from the shipped template, verifies the worker brief's assumptions against the actual repos, finishes through the deterministic /conductor setup wizard, then builds the code-graph indexes workers query instead of grepping.
 ---
 
 # Onboarding a conductor fleet
@@ -549,9 +549,11 @@ You have the answers ready, so this is fast — and it stays the wizard's decisi
 to write, not yours. It asks, in this order: project name; tracker repo; queue
 label; whether to rename the state labels; routing label prefix; then per repo the
 routing key, clone URL, default branch and **pre-push gates** (your Step 2
-proposal, in `cmd @ cwd` form); whether to add another repo; caps; the Telegram
-chat id for tier 2; the escalation fallback; the report scope; and finally whether
-to write `ORCHESTRATOR.md`.
+proposal, in `cmd @ cwd` form); whether to add another repo; whether to set up
+**code-graph discovery** and the root its clones live under (Step 8); caps; the
+authority confirms; the worker model; the Telegram chat id for tier 2; the
+escalation fallback; whether an orchestrator session already runs elsewhere; the
+report scope; and finally whether to write `ORCHESTRATOR.md`.
 
 Two things about the end of it that you must not smooth over:
 
@@ -606,7 +608,98 @@ Operators conflate these, and the failure modes are not the same.
 
 ---
 
-## Step 8 — hand over the learning loop
+## Step 8 — build the code graph, if they said yes to it
+
+Only if the wizard's code-graph question was answered yes. It is optional, and a
+fleet without it works exactly as it did before — but it is the cheapest single
+improvement to how far a worker gets, so lead with the number: **workers spend
+most of a run finding code, not changing it.** Measured on the reference fleet, a
+run typically spends 30–62 `read` and 32–69 `bash` calls against 9–24 edits, and
+the runs that hit the turns cap hit it with the work unfinished. A graph answers
+"who calls this" in one call instead of twenty greps.
+
+Say the thing operators get wrong before you run anything: **the indexed
+directories are conductor's, not theirs.** Three candidates and only one works.
+
+- A worker's **worktree** cannot be indexed usefully — an index is keyed by the
+  realpath it was built from, so a throwaway `worktrees/<issue>` path is always an
+  empty project. That is why the brief hands the worker an absolute path instead.
+- Their **own checkout** must not be indexed. Refreshing means resetting to the
+  default branch, which in a directory they work in either destroys uncommitted
+  work or indexes the feature branch they left checked out.
+- Conductor's **mirrors** are bare. No working tree, nothing to index.
+
+So each `graphProject` is a fourth thing: a disposable clone that exists only to
+be indexed, pinned to the repo's default branch, never edited by a human. Say that
+out loud, because an operator who points it at `~/projects/<repo>` to "save disk"
+has armed something that will one day `git reset --hard` over their work.
+
+Two host prerequisites come before any of that, and neither is conductor's to
+install. `graph-setup` reports both as step 0, so run it first and read that
+block before running anything else.
+
+- **The indexer must be on PATH.** `codebase-memory-mcp` is a separate project
+  ([source](https://github.com/DeusData/codebase-memory-mcp)); the package never
+  installs, spawns or depends on it. A host without it gets command-not-found
+  partway down the plan.
+- **It must be mounted as an MCP server for sessions**, in `~/.omp/agent/mcp.json`
+  on the account the daemon runs as. This is the one that bites, because it fails
+  *silently*: indexing succeeds, the databases are real and correct, and worker
+  sessions have no graph tools at all — so every worker quietly greps and the
+  whole thing looks like it simply did not help. `graph-setup` prints the exact
+  entry to paste, pointed at the binary it found.
+
+Check the mount on the daemon's account, not yours — a per-user config that is
+present for the operator and absent for the service account looks fine from the
+shell they are typing in.
+
+Then, on the host that runs the daemon:
+
+```bash
+omp-conductor graph-setup                 # read-only: prints the whole plan
+```
+
+Walk them through what it printed rather than pasting it silently. It has three
+parts, and each one is a decision they can still refuse: a `git clone` per missing
+clone, an index command per repo (minutes each — run them now, or the first worker
+queries an empty graph), and a `cbm-reindex.service` + `cbm-reindex.timer` pair
+derived from their own repos and branches. Then:
+
+```bash
+omp-conductor graph-setup --write         # stages the script and the two units (no root)
+```
+
+**Have them run this as the account the fleet runs as, not under `sudo`.** The
+command refuses sudo outright, and that refusal is the whole point: config path,
+state directory, `~/.cache` and the unit's own `User=` all resolve per-account,
+so a root run stages a timer that goes green while writing indexes into
+`/root/.cache` where no worker session looks. It is silent, and it looks exactly
+like the feature not helping.
+
+`--write` stages all three files in the state directory and prints the two `sudo`
+lines that install and enable them — installing units is the only privileged
+step, and it never runs `systemctl` itself. Have them start the service once by
+hand and read the result: a first real run is where a wrong branch or a missing
+clone shows up, and the unit is written to fail loudly rather than index a stale
+tree.
+
+Two things to leave them with:
+
+- **A timer, not the server's own watcher.** That watcher lives inside a connected
+  MCP session and dies with it, so nothing a worker mounts keeps anything fresh.
+  If the timer is not enabled, the graph decays and no one is told.
+- **The graph is a snapshot, and the brief says so.** Workers are told to orient
+  with it and then read the real file before editing, because the index is the
+  default branch at the last reindex — not their branch, and not their edits.
+
+Verify before moving on: `codebase-memory-mcp cli list_projects` must show one
+entry per repo whose `root_path` is exactly the configured `graphProject`. That
+match is the whole contract — the worker brief tells the session to find its
+project by that path, so a mismatch means a silent fallback to grep.
+
+---
+
+## Step 9 — hand over the learning loop
 
 Finish by telling the operator the truth about what they just wrote:
 

package/src/briefs/orchestrator.md

@@ -176,12 +176,23 @@ Not yours to relax:
   it, never you. A fleet that patches its own dispatcher is a fleet whose
   behavior nobody can reproduce, and the next install silently reverts the
   patch, which is worse than never having made it.
+- **A worker's branch is theirs; the PR is yours to steer.** Never `git checkout`,
+  commit or push inside a worker's worktree, never cut a branch from one, never
+  force-push or rewrite history anywhere, and never author a commit under an
+  invented identity. But `gh pr update-branch` **is** yours to run and is the
+  sanctioned remedy for a green PR that has fallen behind: it is a server-side
+  merge of the base into the head, it destroys nothing, it rewrites nothing, and
+  under a ruleset that requires branches to be up to date it is the only way a
+  correct PR ever merges. Closing a green PR to make a fresh worker redo the
+  merge costs a whole attempt to buy what one command does in minutes — do not.
+  Bypassing branch protection with admin rights is still forbidden; updating the
+  branch is how you satisfy it, not how you dodge it.
 
 **Your own** merge and release authority is not decided here. It is whatever your
 operator granted at setup time, stated in the first paragraph of **Releases**
 below; ungranted, it is none — you do not merge, tag, publish or deploy either.
 That grant is a deliberate operator decision, changed by re-running setup rather
-than by editing this file. The four boundaries above are not.
+than by editing this file. The five boundaries above are not.
 
 ## Learning loop
 
@@ -248,7 +259,12 @@ eventually publishes something at 03:00. Spell out all seven.
 - **Whether you may merge**, and which PRs. Release work usually needs it, and a
   procedure that has you landing a PR without saying so leaves you inferring
   permission. Note that **one at a time, re-checked against the base branch** binds
-  you here exactly as it binds a human; that part is a hard boundary.
+  you here exactly as it binds a human; that part is a hard boundary. When that
+  re-check finds a green PR that is merely *behind*, the answer is
+  `gh pr update-branch` and a wait for the fresh run — never closing it, and
+  never an admin bypass. Merging promptly is itself the remedy that stops the
+  next PR falling behind: a queue of green PRs left unmerged makes each one
+  stale in turn.
 - **The release authority**, named. Which workflow or command ships this repo, and
   how it is invoked. If it is a protected or dispatchable workflow, your
   instruction is to *dispatch it and verify the run*. You never reproduce what it

package/src/briefs/worker.md

@@ -39,16 +39,27 @@ files are canonical; your priors are not.
    mid-refactor loses the run. If code-graph MCP tools are mounted (a
    `codebase-memory` server or similar), start there: list its indexed projects,
    and query by **project name** — your worktree is a throwaway path the index
-   has never seen, so a cwd-based lookup finds nothing while the canonical
-   checkout's index has the whole call graph. Fall back to grep where the graph
+   has never seen, so a cwd-based lookup finds nothing while the clone that was
+   actually indexed has the whole call graph. Fall back to grep where the graph
    is silent. Either way, trace the real flow end to end — every file the change
    touches — and check the callers of any function you are about to change; the
    smallest diff in the wrong place is a second bug.
-2. **Follow existing patterns.** A second convention beside an existing one is a
+{{GRAPH_HINT}}2. **One read per file, not one per question.** A turn that reads forty lines
+   costs exactly what a turn that rewrites a module costs, and you have a fixed
+   number of them. So take every range you already know you want in a single
+   call — `read path.py:1-40,120-160,300-340` — rather than returning to the
+   same file three times as each question occurs to you. When you do not yet
+   know the ranges, read the file once and keep what you learned instead of
+   re-reading a neighbouring slice later. Measured on this fleet: one run spent
+   58 reads, of which 20 were consecutive reads of the *same* file and 28 were
+   return visits to a file it had already opened — roughly a sixth of its whole
+   budget, on a run that then died with the work unfinished. The same applies to
+   `grep`: one pattern that answers the question beats three that narrow it.
+3. **Follow existing patterns.** A second convention beside an existing one is a
    defect. Reuse the helper that already exists rather than writing a sibling.
-3. **Keep the diff small.** Small PRs merge; large ones conflict. If the issue
+4. **Keep the diff small.** Small PRs merge; large ones conflict. If the issue
    genuinely cannot be done small, stop and escalate rather than ballooning.
-4. **Fix the root cause, never the symptom.** Do not suppress a warning, delete an
+5. **Fix the root cause, never the symptom.** Do not suppress a warning, delete an
    assertion, or special-case an input to make a check pass.
 
 ## Tests — read this carefully

package/src/cli.ts

@@ -10,6 +10,7 @@ import { join } from "node:path";
 import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
 import { findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { dbPath, formatStatus, runDaemon, setPaused, statusSnapshot } from "./daemon.ts";
+import { formatGraphSetup, graphRepos, writeGraphSetup, type GraphSetupWrite } from "./graph.ts";
 import {
   clearRecord,
   DEFAULT_PORT,
@@ -38,6 +39,7 @@ usage:
   omp-conductor daemon [--once] [--port N] [--project NAME]
   omp-conductor pause
   omp-conductor resume
+  omp-conductor graph-setup [--project NAME] [--write]
   omp-conductor brief-upgrade [--apply] [--file PATH] [--project NAME]
   omp-conductor help
 
@@ -63,6 +65,13 @@ usage:
            and exits. This is what \`start\` launches.
   pause    stop claiming new work. The running daemon notices on its next tick.
   resume   allow claiming again.
+  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
+           index command per repo, and a systemd service+timer that keeps them
+           current. --write writes the two units and the script they run, and
+           prints the systemctl line to run — it never runs systemctl itself.
+           Exits 1 when no repo in the project has graphProject configured.
   brief-upgrade
            compare a project's ORCHESTRATOR.md against the brief this version of
            the package ships. Reports by default; --apply replaces the half above
@@ -451,6 +460,57 @@ try {
       process.stdout.write("resumed — work will be claimed on the next tick\n");
       break;
 
+    case "graph-setup": {
+      // Refused rather than accommodated. Under sudo every path this command
+      // derives — the config it loads, the state directory it writes to, the
+      // HOME and User= it bakes into the unit — resolves as root instead of the
+      // fleet's account, and the result is a timer that goes green while
+      // building indexes in a store no worker session ever reads. Nothing about
+      // that announces itself, so the only safe answer is to stop.
+      if (process.env["SUDO_USER"] !== undefined) {
+        process.stderr.write(
+          "omp-conductor: run graph-setup as the account the fleet runs as, not under sudo.\n" +
+            `Under sudo the config, ~/.cache and the unit's User= all resolve as root, and the\n` +
+            `indexes land where no worker can read them. Only installing the units needs root,\n` +
+            "and this command prints those two lines for you at the end.\n",
+        );
+        process.exit(1);
+      }
+
+      const project = findProject(loadConfig(), flag(argv, "project"));
+      if (graphRepos(project).length === 0) {
+        // Not a warning: with nothing configured there is nothing to print, and
+        // the fix is a wizard answer rather than a flag on this command.
+        process.stderr.write(
+          `omp-conductor: no repo in project "${project.name}" has graphProject set — re-run\n` +
+            "/conductor setup and say yes to code-graph discovery.\n",
+        );
+        process.exit(1);
+      }
+
+      if (!argv.includes("--write")) {
+        process.stdout.write(`${formatGraphSetup(project)}\n`);
+        break;
+      }
+
+      let result: GraphSetupWrite;
+      try {
+        result = writeGraphSetup(project);
+      } catch (err) {
+        // No longer the permissions case — all three files go to this account's
+        // own state directory — so this is a full disk, a read-only mount or a
+        // state directory someone else owns. Say what failed and offer the
+        // printed plan, which is a complete substitute for the write.
+        process.stderr.write(
+          `omp-conductor: could not stage the files (${err instanceof Error ? err.message : String(err)}).\n` +
+            "Drop --write and copy the printed text yourself — it is the same content.\n",
+        );
+        process.exit(1);
+      }
+      process.stdout.write(`wrote:\n${result.written.map((f) => `  ${f}`).join("\n")}\n\n${result.next}\n`);
+      break;
+    }
+
     case "brief-upgrade": {
       // `--file` exists because a real fleet's brief is often not where the wizard
       // would have put it: the supervising session runs from its own directory, and