omp-conductor 0.3.4 → 0.3.5

package/README.md

@@ -524,6 +524,92 @@ 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.
+
+### 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 |
@@ -638,7 +724,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 +774,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. |
@@ -863,6 +951,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 +970,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 +1012,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.5",
   "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/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

package/src/config.ts

@@ -14,7 +14,7 @@
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import {
   AUTHORITY_HOLDERS,
   CONFIG_VERSION,
@@ -432,17 +432,47 @@ function normalizeRepos(parsed: unknown, label: string, problems: string[]): Rec
       problems.push(`${label}: routing.repos.${key}.cloneUrl must be a non-empty string`);
       continue;
     }
-    repos[key] = {
+    const target: RepoTarget = {
       name: pickString(value?.["name"], key),
       cloneUrl,
       defaultBranch: pickString(value?.["defaultBranch"], "main"),
       gates: normalizeGates(value?.["gates"], `${label}: routing.repos.${key}`, problems),
     };
+    const graph = normalizeGraphProject(value?.["graphProject"], `${label}: routing.repos.${key}`, problems);
+    if (graph !== undefined) target.graphProject = graph;
+    repos[key] = target;
   }
 
   return repos;
 }
 
+/**
+ * The path of the index-only clone whose code graph this repo's workers query,
+ * or `undefined` when the repo has none.
+ *
+ * A relative path is rejected rather than resolved, and that rejection is the
+ * whole reason this is validated here: the value is written in one process and
+ * *used* in another, by a session whose cwd is its own throwaway worktree. So
+ * `../graph/api` would name a different directory for every reader, and none of
+ * them the one that was indexed. There is no cwd this file could honestly
+ * resolve it against, so it says so rather than guessing.
+ */
+function normalizeGraphProject(parsed: unknown, label: string, problems: string[]): string | undefined {
+  if (parsed === undefined) return undefined;
+  if (!nonEmptyString(parsed)) {
+    problems.push(`${label}.graphProject must be a non-empty absolute path, found ${JSON.stringify(parsed)}`);
+    return undefined;
+  }
+
+  const path = expandHome(parsed.trim());
+  if (isAbsolute(path)) return path;
+  problems.push(
+    `${label}.graphProject must be an absolute path — it is read by sessions whose cwd is their own ` +
+      `worktree — found ${JSON.stringify(parsed)}`,
+  );
+  return undefined;
+}
+
 /**
  * Gates are the pre-push CI equivalent, so a malformed entry is an error, not
  * something to drop quietly: a skipped gate is exactly how a lint failure
@@ -550,8 +580,14 @@ function pickLiteral<T extends string>(
   return hit;
 }
 
-/** `~/x` in a hand-written config must not create a literal `~` directory. */
-function expandHome(p: string): string {
+/**
+ * `~/x` in a hand-written config must not create a literal `~` directory.
+ *
+ * Exported because the wizard and `graph-setup` derive paths the operator may
+ * have typed with a `~` in them, and one spelling of this rule in the package
+ * is the only way a path shown in a plan matches the path a validator accepts.
+ */
+export function expandHome(p: string): string {
   if (p === "~") return homedir();
   return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
 }

package/src/daemon.ts

@@ -12,6 +12,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync
 import { dirname, join, relative } from "node:path";
 import { configPath, findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { createEscalator } from "./escalate.ts";
+import { graphHint } from "./graph.ts";
 import { livingDaemon } from "./lifecycle.ts";
 import { STALL_MARKER_FILE } from "./orchestrator-tick.ts";
 import { startOrchestrator } from "./orchestrator.ts";
@@ -429,7 +430,16 @@ function endedBy(killedBy: KilledBy | undefined): string {
   return "a failed run";
 }
 
-async function buildBrief(
+/**
+ * The worker's opening prompt.
+ *
+ * Exported for the same reason `salvageLines` is: this text is the entire
+ * context a session with the host's credentials gets, so the two things a test
+ * can hold it to are worth holding — that a configured graph reaches the worker,
+ * and that a project without one gets the brief this package has always shipped,
+ * to the byte.
+ */
+export async function buildBrief(
   project: ProjectConfig,
   r: Routed,
   branch: string,
@@ -447,6 +457,10 @@ async function buildBrief(
     WORKTREE: worktree,
     ACCEPTANCE_CRITERIA: acceptanceCriteria(r.issue),
     GATES: gatesBlock(r.repo),
+    // Empty for a repo with no `graphProject`, and empty means *nothing*: the
+    // placeholder sits flush against the next list item in the template, so an
+    // unconfigured render leaves no blank line where a hint would have gone.
+    GRAPH_HINT: graphHint(r.repo),
   });
 }
 

package/src/graph.ts

@@ -0,0 +1,508 @@
+/**
+ * Code-graph discovery: the indexes workers query instead of grepping, and the
+ * commands that create and refresh them.
+ *
+ * Why this exists at all, measured on the dogfood fleet rather than assumed:
+ * workers spend roughly four fifths of a 120-turn budget *finding* code — 30–62
+ * `read` calls and 32–69 `bash` calls against 9–24 edits per run, 215–390k
+ * characters of tool output. A code graph answers "who calls this" and "where is
+ * this defined" in one call, which is the difference between a run that lands
+ * and a run that dies mid-refactor with the work unfinished.
+ *
+ * Two hard boundaries hold everything here together:
+ *
+ * - **This package never runs an indexer, and never depends on one.** Nothing
+ *   below spawns the graph server, imports it, or checks for it; the daemon's
+ *   dispatch, caps and escalation paths do not mention it. `graph-setup` prints
+ *   commands, and with `--write` writes two systemd units — it does not even run
+ *   `systemctl`, because the wizard and the CLI are not root and a package that
+ *   silently writes root-level state is not one you can trust with a fleet.
+ * - **A worker never queries its own worktree.** An index is keyed by the
+ *   realpath of the directory it was built from, with no git-worktree awareness,
+ *   so a run's `worktrees/<issue>` path is always an empty project. Workers are
+ *   pointed at {@link RepoTarget.graphProject} — a conductor-owned clone nothing
+ *   human edits — and {@link graphHint} is the text that makes that unmissable.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+import { expandHome, stateDir } from "./config.ts";
+import type { ProjectConfig, RepoTarget } from "./types.ts";
+
+/**
+ * The indexer's own CLI, invoked by name rather than by path so the generated
+ * unit's explicit `PATH` is the single place a host's install location is
+ * spelled out. `cli <tool> <json>` runs one tool without an MCP session.
+ */
+const INDEXER = "codebase-memory-mcp";
+
+/** Both units and the script share this stem; `cbm` is the indexer's own prefix. */
+export const REINDEX_UNIT = "cbm-reindex";
+
+/** Where a system timer has to live to be enabled by `systemctl`. */
+export const SYSTEMD_UNIT_DIR = "/etc/systemd/system";
+
+/** Where the upstream indexer lives, for an operator who has to go install it. */
+const INDEXER_SOURCE = "https://github.com/DeusData/codebase-memory-mcp";
+
+/**
+ * The two things that must be true of the *host* before any index is useful,
+ * neither of which conductor installs: the indexer has to be on PATH, and the
+ * agent has to mount it as an MCP server or worker sessions get no graph tools
+ * at all. Indexing without the mount produces a perfectly good database that
+ * nothing can read — the failure this preflight exists to make visible.
+ */
+export interface GraphPrereqs {
+  /** Resolved indexer path, or null when nothing on PATH answers to the name. */
+  indexer: string | null;
+  /** The agent's MCP server config, whether or not it exists yet. */
+  mcpConfig: string;
+  /** Whether that config already mounts the indexer for sessions. */
+  mounted: boolean;
+}
+
+/** Reads the host. Split from {@link formatGraphSetup} so the plan stays pure. */
+export function resolvePrereqs(home: string = homedir()): GraphPrereqs {
+  const onPath = (process.env["PATH"] ?? "")
+    .split(":")
+    .filter((d) => d !== "")
+    .map((d) => join(d, INDEXER))
+    .find((c) => existsSync(c));
+
+  const mcpConfig = join(home, ".omp", "agent", "mcp.json");
+  let mounted = false;
+  try {
+    // Any mention of the binary counts as mounted. Parsing the whole schema to
+    // decide would make this preflight fail on configs it does not understand,
+    // and a false "not mounted" costs an operator a confusing duplicate entry.
+    const raw = JSON.parse(readFileSync(mcpConfig, "utf8")) as Record<string, unknown>;
+    const servers = (raw["mcpServers"] ?? raw) as Record<string, unknown>;
+    mounted = Object.keys(servers).some((k) => k.includes(INDEXER));
+  } catch {
+    // No file, or unreadable: not mounted, and the plan says how to add it.
+  }
+  return { indexer: onPath ?? null, mcpConfig, mounted };
+}
+
+/** The `mcp.json` entry a fresh host needs, using the resolved path when known. */
+export function mcpEntry(prereqs: GraphPrereqs): string {
+  const command = prereqs.indexer ?? `/usr/local/bin/${INDEXER}`;
+  return JSON.stringify({ [INDEXER]: { type: "stdio", command } }, null, 2);
+}
+
+/**
+ * Default parent of every index-only clone, under the cache directory because
+ * that is exactly what these are: derived data, disposable, re-creatable from a
+ * clone URL. Deliberately *not* `~/projects/<org>` — that is where a human's own
+ * checkouts live, and pointing a reindexer at one either destroys their
+ * uncommitted work or indexes whatever branch they left checked out.
+ *
+ * `trackerRepo` supplies the org so a fleet's clones land together, which is
+ * also the answer for the common case where the tracker and the code share one
+ * GitHub organisation.
+ */
+export function defaultGraphRoot(trackerRepo: string): string {
+  const org = trackerRepo.split("/")[0] ?? trackerRepo;
+  return join(homedir(), ".cache", "conductor-graph", org);
+}
+
+/** One repo's clone under a chosen root. `~` is expanded here so a path an
+ *  operator typed matches the absolute path the validator accepts. */
+export function graphProjectPath(root: string, repoName: string): string {
+  return join(expandHome(root.trim()), repoName);
+}
+
+/** A repo that has a graph, narrowed so callers need no further guard. */
+export type GraphRepo = RepoTarget & { graphProject: string };
+
+/** The project's repos that have a graph configured, in config order. */
+export function graphRepos(p: ProjectConfig): GraphRepo[] {
+  return Object.values(p.routing.repos).filter((r): r is GraphRepo => r.graphProject !== undefined);
+}
+
+/**
+ * The paragraph a worker's brief carries about its repo's graph, or `""` when
+ * the repo has none — in which case the rendered brief is byte-for-byte the one
+ * this package shipped before graphs existed.
+ *
+ * The leading newline and the three-space indent are load-bearing: the
+ * placeholder sits immediately before the next numbered item in
+ * `briefs/worker.md`, so an empty value leaves no blank line behind and a
+ * non-empty one reads as a continuation of the item above it.
+ *
+ * Every sentence here is defending against one specific failure. A worker that
+ * passes its own cwd gets an empty answer and concludes there is no graph. A
+ * worker that trusts the graph as current edits against a snapshot that predates
+ * its own branch. Both end the same way — a confident diff in the wrong place —
+ * so the wording says the quiet part out loud rather than describing the tool.
+ */
+export function graphHint(repo: RepoTarget): string {
+  const path = repo.graphProject;
+  if (path === undefined) return "";
+
+  return (
+    "\n" +
+    "   **This repo has a code graph, and it was not built from your worktree.**\n" +
+    "   Call `list_projects` first, find the single entry whose `root_path` is\n" +
+    "   exactly\n" +
+    `   \`${path}\`\n` +
+    "   and pass that entry's `name` as the `project` argument to every graph\n" +
+    "   tool. Never pass a path, and never pass your own cwd: that clone is what\n" +
+    "   was indexed, your worktree has no index and never will, so a cwd-based\n" +
+    "   lookup answers nothing and you lose the run to grep.\n" +
+    "\n" +
+    "   Read what it tells you as a snapshot of that clone's default branch at\n" +
+    "   the last reindex: it does not contain your edits, and it can be hours\n" +
+    "   behind the branch you are on. So orient with the graph, then read the\n" +
+    "   real file in your worktree before you change it. If those tools are not\n" +
+    "   mounted in this session, say so in your report and fall back to grep.\n"
+  );
+}
+
+/** Where the generated refresh script lands: conductor state, not a unit
+ *  directory, because it is ours to regenerate and needs no root to write. */
+export function reindexScriptPath(): string {
+  return join(stateDir(), `${REINDEX_UNIT}.sh`);
+}
+
+/** Both unit files, from the one stem `systemctl enable` will be given. */
+export function unitPaths(unitDir = SYSTEMD_UNIT_DIR): { service: string; timer: string } {
+  return {
+    service: join(unitDir, `${REINDEX_UNIT}.service`),
+    timer: join(unitDir, `${REINDEX_UNIT}.timer`),
+  };
+}
+
+/**
+ * `git clone` for one repo's index-only clone.
+ *
+ * `--single-branch` so the working tree can only ever hold the branch the graph
+ * claims to describe, and the destination is quoted because the root is
+ * operator-typed and a space in it would otherwise clone into two directories.
+ */
+export function cloneCommand(r: GraphRepo): string {
+  return `git clone --single-branch --branch ${r.defaultBranch} ${r.cloneUrl} "${r.graphProject}"`;
+}
+
+/** The one-shot index command, as a human would run it to seed a clone. */
+export function indexCommand(r: GraphRepo): string {
+  return `${INDEXER} cli index_repository '{"repo_path": "${r.graphProject}"}'`;
+}
+
+/**
+ * The refresh-and-reindex script both the timer and a human run.
+ *
+ * It fails loudly on purpose, and that is the one thing about it worth
+ * protecting. A first draft of this — hand-written on the live host — used
+ * `git fetch … || true; git pull --ff-only || true`, which meant a fetch that
+ * failed for a week still indexed the stale tree and still exited 0: a green
+ * timer serving a month-old graph, and workers orienting against code that no
+ * longer exists. So: `set -euo pipefail`, no swallowed failures anywhere, and
+ * the first broken repo takes the whole run non-zero where `systemctl status`
+ * and `systemctl is-failed` will report it.
+ *
+ * `git reset --hard origin/<defaultBranch>` rather than a merge or a pull is
+ * safe *because* of what these clones are — conductor's own, never edited by a
+ * human — and it is the only refresh with no failure mode of its own: no
+ * conflict, no divergence, no detached state to recover from. Each repo's own
+ * configured branch is used, because a fleet with a `master` repo in it would
+ * otherwise silently index nothing.
+ */
+export function reindexScript(p: ProjectConfig): string {
+  const lines = [
+    "#!/usr/bin/env bash",
+    `# Refresh and reindex the code graphs for omp-conductor project "${p.name}".`,
+    "#",
+    "# Generated by \`omp-conductor graph-setup\`. Regenerate it rather than editing:",
+    "# the repo list, branches and paths all come from that project's config.json.",
+    "#",
+    "# Every clone below is conductor's own, index-only and never edited by a human,",
+    "# which is what makes the hard reset safe. Do not point one at a checkout you",
+    "# work in: the reset would destroy uncommitted work.",
+    "#",
+    "# Fails loud and stops at the first problem, deliberately. A refresh that",
+    "# swallowed its errors would index a stale tree and still exit 0 — a green",
+    "# timer serving a month-old graph is worse than no graph at all.",
+    "set -euo pipefail",
+    "",
+  ];
+
+  for (const r of graphRepos(p)) {
+    lines.push(
+      `# ${r.name} — ${r.cloneUrl} @ ${r.defaultBranch}`,
+      `cd "${r.graphProject}"`,
+      "git fetch --prune origin",
+      `git reset --hard origin/${r.defaultBranch}`,
+      indexCommand(r),
+      "",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * The service half. `Type=oneshot` with no `[Install]` section: it is started by
+ * its timer, and a service enabled on its own would run once at boot and never
+ * again, which looks exactly like a working install.
+ */
+export function reindexService(p: ProjectConfig, scriptPath = reindexScriptPath()): string {
+  const home = homedir();
+  const user = userInfo().username;
+  return [
+    "[Unit]",
+    `Description=Reindex the code graphs omp-conductor project "${p.name}" hands its workers`,
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=oneshot",
+    `ExecStart=/bin/bash ${scriptPath}`,
+    "# Pinned to the account that generated this, and it has to be the account the",
+    "# fleet runs as. A systemd service defaults to root, and root is wrong three",
+    "# ways at once here: the indexer would write its store under /root/.cache",
+    "# where no worker session ever looks, a private clone would fetch with root's",
+    "# SSH credentials rather than the fleet's, and every path below points into a",
+    "# different account's home. All three fail silently — the timer goes green",
+    "# and the graph a worker queries is simply never the graph this built.",
+    `User=${user}`,
+    "# Both of these are spelled out because systemd supplies neither usefully.",
+    `# The indexer resolves its store from HOME (${join(home, ".cache", "codebase-memory-mcp")}),`,
+    "# so an unset HOME would build a second index nobody queries; and systemd's",
+    "# default PATH has no ~/.local/bin, while the indexer itself shells out to git.",
+    `Environment=HOME=${home}`,
+    `Environment=PATH=${["/.local/bin", "/.bun/bin"].map((d) => join(home, d)).join(":")}` +
+      ":/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+    "# Indexing is CPU- and IO-heavy, and this host is also running the fleet whose",
+    "# workers read the result.",
+    "Nice=10",
+    "IOSchedulingClass=idle",
+    "# A wedged index must fail rather than hold its timer open indefinitely.",
+    "TimeoutStartSec=1h",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The timer half — and the reason there is a timer at all.
+ *
+ * The graph server's own auto-watch lives inside a connected MCP session and
+ * dies with it, and v0.9.0 ships no daemon. An ephemeral worker session
+ * therefore keeps nothing fresh: whatever it mounts, it un-mounts minutes later.
+ * So the refresh has to come from outside the fleet entirely, on a schedule
+ * nothing in a run can influence.
+ */
+export function reindexTimer(p: ProjectConfig): string {
+  return [
+    "[Unit]",
+    `Description=Periodic code-graph reindex for omp-conductor project "${p.name}"`,
+    "",
+    "[Timer]",
+    "# Twenty minutes, because the measured cost is small and the cost of",
+    "# staleness is not: refreshing four repos takes ~40s of CPU, which at this",
+    "# interval is roughly 3% of one core, and the service runs at Nice=10 with",
+    "# idle IO so it yields to the fleet. A nightly refresh would be cheaper and",
+    "# much worse — a fleet merging several PRs a day would spend most of its",
+    "# dispatches querying a graph that predates the code the worker was sent to",
+    "# change, which is the one way this feature actively misleads. Lengthen it",
+    "# for quiet repos; the brief has workers verify against the real file",
+    "# regardless, so staleness degrades the graph rather than making it lie.",
+    "OnBootSec=3min",
+    "OnUnitActiveSec=20min",
+    "# Persistent catches a host that was down; the jitter keeps every install",
+    "# of this unit off the same second.",
+    "Persistent=true",
+    "RandomizedDelaySec=2m",
+    "AccuracySec=1min",
+    `Unit=${REINDEX_UNIT}.service`,
+    "",
+    "[Install]",
+    "WantedBy=timers.target",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The privileged tail, and the only part of this feature that needs root.
+ *
+ * Split out deliberately. Running the whole CLI under `sudo` looks convenient
+ * and is wrong: `loadConfig`, `stateDir`, `homedir` and `userInfo` would all
+ * resolve as root, so the config would be missed or the wrong one, the script
+ * would land in root's state directory, and the generated unit would bake
+ * root's HOME with no `User=` — indexes written where no worker reads them.
+ * So generation runs unprivileged as the fleet user, and only the copy into
+ * the unit directory is elevated.
+ */
+export function installCommands(unitDir = SYSTEMD_UNIT_DIR, from = stateDir()): string[] {
+  const { service, timer } = unitPaths(from);
+  return [
+    `sudo install -m 0644 ${service} ${timer} ${unitDir}/`,
+    `sudo systemctl daemon-reload && sudo systemctl enable --now ${REINDEX_UNIT}.timer`,
+  ];
+}
+
+function block(title: string, body: string): string[] {
+  return [`--- ${title} ---`, "", body.trimEnd(), ""];
+}
+
+/**
+ * The whole plan as text, with nothing done. This is the default mode of
+ * `graph-setup`, and it is a plan an operator can read, paste, or ignore —
+ * including on a host where they are not root and `--write` would fail.
+ */
+export function formatGraphSetup(
+  p: ProjectConfig,
+  unitDir = SYSTEMD_UNIT_DIR,
+  prereqs: GraphPrereqs = resolvePrereqs(),
+): string {
+  const repos = graphRepos(p);
+  const missing = repos.filter((r) => !existsSync(r.graphProject));
+  // Seeded with 0 so these are still widths when the caller ignored the exit-1
+  // guard and asked for a plan for a project with no graph at all.
+  const nameWidth = Math.max(0, ...repos.map((r) => r.name.length));
+  const pathWidth = Math.max(0, ...repos.map((r) => r.graphProject.length));
+
+  const lines = [
+    `code-graph discovery for project "${p.name}"`,
+    "",
+    "Workers spend most of a run finding code rather than changing it. These",
+    'indexes answer "who calls this" and "where is this defined" in one call, so',
+    "the turns go into the work instead. Nothing below has been run.",
+    "",
+    `repos with a graph configured (${repos.length}):`,
+  ];
+  for (const r of repos) {
+    // Padded so the (missing) markers line up: which clones do not exist yet is
+    // the one thing an operator scans this list for.
+    const marker = missing.includes(r) ? "  (missing)" : "";
+    lines.push(`  ${r.name.padEnd(nameWidth)}  ${r.graphProject.padEnd(marker === "" ? 0 : pathWidth)}${marker}`);
+  }
+
+  // Before anything else, because both of these are host state conductor does
+  // not own and neither failure is self-announcing: a missing binary surfaces
+  // as command-not-found halfway down the plan, and a missing mount surfaces
+  // as workers that never mention the graph and quietly grep instead.
+  lines.push("", "0. host prerequisites", "");
+  lines.push(
+    prereqs.indexer === null
+      ? `   [ ] ${INDEXER} is NOT on your PATH. Install it first — conductor never
+       does, and never depends on it: ${INDEXER_SOURCE}`
+      : `   [x] indexer: ${prereqs.indexer}`,
+  );
+  if (prereqs.mounted) {
+    lines.push(`   [x] mounted for sessions in ${prereqs.mcpConfig}`);
+  } else {
+    lines.push(
+      `   [ ] NOT mounted as an MCP server, so worker sessions have no graph`,
+      `       tools and every index below would be unreadable. Add to`,
+      `       ${prereqs.mcpConfig}:`,
+      "",
+      ...mcpEntry(prereqs)
+        .split("\n")
+        .map((l) => `       ${l}`),
+    );
+  }
+
+  lines.push("", "1. create the clones that are missing", "");
+  if (missing.length === 0) {
+    lines.push("   every clone above already exists — nothing to create.");
+  } else {
+    lines.push(
+      "   These are conductor's, not yours. Nothing human edits them, which is what",
+      "   makes step 3's hard reset both safe and deterministic — so never point a",
+      "   graphProject at a checkout you work in.",
+      "",
+    );
+    for (const r of missing) lines.push(`   ${cloneCommand(r)}`);
+  }
+
+  lines.push(
+    "",
+    "2. index each one once now, so the first worker does not wait for the timer",
+    "",
+  );
+  for (const r of repos) lines.push(`   ${indexCommand(r)}`);
+  lines.push(
+    "",
+    "   Then check what a worker will see. Each root_path below must match a path",
+    "   above exactly, and the name beside it is what a worker passes as `project`:",
+    "",
+    `   ${INDEXER} cli list_projects`,
+    "",
+    "3. keep them current",
+    "",
+  );
+
+  const script = reindexScriptPath();
+  const { service, timer } = unitPaths(stateDir());
+  lines.push(
+    `   \`graph-setup --write\` writes these three files for you, all under`,
+    `   ${stateDir()}. Run it as the account the fleet runs as — never under`,
+    "   sudo, which would resolve the config, the state directory and the unit's",
+    "   own User= as root and quietly build indexes no worker can read.",
+    "",
+    ...block(script, reindexScript(p)),
+    ...block(service, reindexService(p, script)),
+    ...block(timer, reindexTimer(p)),
+    `   then install them, which is the only step that needs root:`,
+    "",
+    ...installCommands(unitDir).map((c) => `   ${c}`),
+  );
+
+  return lines.join("\n");
+}
+
+/** What `graph-setup --write` did, and the root-only steps it deliberately left. */
+export interface GraphSetupWrite {
+  written: string[];
+  next: string;
+}
+
+/**
+ * Writes the script and both units, and returns what to do next.
+ *
+ * Deliberately stops there. Running `systemctl` would need root the wizard and
+ * the CLI may not have, and a package that enables system timers behind an
+ * operator's back is one you cannot audit by reading its output.
+ */
+export function writeGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): GraphSetupWrite {
+  const script = reindexScriptPath();
+  // All three land in the state directory, which this account owns — so the
+  // whole command runs unprivileged and there is no sudo path that could
+  // resolve HOME, the config or the unit's User= as the wrong account.
+  const { service, timer } = unitPaths(stateDir());
+
+  mkdirSync(dirname(script), { recursive: true });
+  writeFileSync(script, reindexScript(p));
+  // Executable so an operator can run the refresh by hand before trusting a
+  // timer with it; the unit calls bash explicitly either way.
+  chmodSync(script, 0o755);
+  writeFileSync(service, reindexService(p, script));
+  writeFileSync(timer, reindexTimer(p));
+
+  const missing = graphRepos(p).filter((r) => !existsSync(r.graphProject));
+  const next = [
+    "nothing has been installed, enabled or started — this command needs no root",
+    `and takes none. The units are staged in ${stateDir()}.`,
+    "",
+    "to install them, which is the only privileged step:",
+    "",
+    ...installCommands(unitDir).map((c) => `  ${c}`),
+    "",
+    "then watch one real run before trusting the schedule (it takes minutes per repo):",
+    "",
+    `  sudo systemctl start ${REINDEX_UNIT}.service && systemctl status ${REINDEX_UNIT}.service`,
+    ...(missing.length === 0
+      ? []
+      : [
+          "",
+          `first, though: ${missing.length} clone(s) do not exist yet, and the script fails`,
+          "loudly rather than skipping them —",
+          "",
+          ...missing.map((r) => `  ${cloneCommand(r)}`),
+        ]),
+  ].join("\n");
+
+  return { written: [script, service, timer], next };
+}

package/src/plugin.ts

@@ -11,8 +11,9 @@
  * worth protecting is on `setup()` below — nothing is written before the confirm.
  */
 import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute } from "node:path";
 import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
-import { configPath, findProject, loadConfig, saveConfig } from "./config.ts";
+import { configPath, expandHome, findProject, loadConfig, saveConfig } from "./config.ts";
 import {
   armConductor,
   formatStatus,
@@ -22,6 +23,7 @@ import {
   statusSnapshot,
   type QueuePreview,
 } from "./daemon.ts";
+import { defaultGraphRoot } from "./graph.ts";
 import {
   ORCHESTRATOR_BRIEF_NAME,
   REPORT_SCOPE_CHOICES,
@@ -287,6 +289,44 @@ async function askOrchestratorMode(ctx: CommandContext, prior: OrchestratorMode)
   return external ? "external" : "embedded";
 }
 
+/**
+ * Whether workers get a code graph, and where its clones live.
+ *
+ * One confirm and at most one prompt, asked after the repos are known because
+ * the answer is derived per repo. A declined answer leaves the field off every
+ * repo, which is what keeps an existing fleet's briefs byte-identical.
+ *
+ * The root is validated as absolute here rather than at load time so the
+ * operator learns immediately: a relative path would be resolved against
+ * whichever cwd happened to read the config, and never against the directory
+ * that was indexed.
+ */
+async function askGraphRoot(
+  ctx: CommandContext,
+  trackerRepo: string,
+  repoNames: string[],
+  prior: string | undefined,
+): Promise<string | undefined> {
+  const wanted = await ctx.ui.confirm(
+    "Code-graph discovery",
+    "Set up code-graph discovery for workers? Workers spend most of their turn budget finding code; " +
+      'a graph answers "who calls this" in one call. Conductor keeps one disposable clone per repo, ' +
+      "pinned to the default branch purely for indexing — never your own checkout" +
+      `${prior === undefined ? "" : `. Currently on, under ${prior}`}.`,
+  );
+  if (!wanted) return undefined;
+
+  return await askValid(
+    ctx,
+    `Root for those clones — one per repo (${repoNames.join(", ")}) is created under it`,
+    prior ?? defaultGraphRoot(trackerRepo),
+    (v) =>
+      isAbsolute(expandHome(v))
+        ? undefined
+        : `"${v}" is not an absolute path — a worker reads this from its own worktree, so a relative one names the wrong directory.`,
+  );
+}
+
 /**
  * Whether to render the operator's own brief, and — separately — whether an
  * existing one may be replaced. Two questions on purpose: that file is where a
@@ -400,6 +440,17 @@ async function collectAnswers(
     if (!more) break;
   }
 
+  // Straight after the repos, because it is a fact about them: one clone per
+  // routed repo, under one root. Seeded from whichever prior repo already had
+  // one — the wizard writes them as siblings, so any one of them names the root.
+  const priorGraph = Object.values(prior?.routing.repos ?? {}).find((r) => r.graphProject !== undefined);
+  const graphRoot = await askGraphRoot(
+    ctx,
+    trackerRepo,
+    targetRepos.map((r) => r.name),
+    priorGraph?.graphProject === undefined ? undefined : dirname(priorGraph.graphProject),
+  );
+
   const caps: Partial<Caps> = { ...prior?.caps };
   const tuneCaps = await ctx.ui.confirm(
     "Caps",
@@ -495,6 +546,7 @@ async function collectAnswers(
   };
   if (telegramChatId !== undefined) answers.telegramChatId = telegramChatId;
   if (workerModel !== undefined) answers.workerModel = workerModel;
+  if (graphRoot !== undefined) answers.graphRoot = graphRoot;
   return { ...answers, writeOrchestratorBrief: await askOrchestratorBrief(ctx, answers) };
 }
 

package/src/setup.ts

@@ -24,6 +24,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { configPath, resolveCaps, stateDir } from "./config.ts";
+import { graphProjectPath, graphRepos } from "./graph.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_AUTHORITY,
@@ -83,6 +84,17 @@ export interface SetupAnswers {
    * that session to drain, rather than starting a second brain.
    */
   orchestratorMode: OrchestratorMode;
+  /**
+   * Parent directory of the index-only clones workers query, or absent when the
+   * operator declined code-graph discovery — in which case no repo gets a
+   * `graphProject` and every rendered brief is the one this package shipped
+   * before graphs existed.
+   *
+   * One answer for the whole project rather than one per repo: the clones are
+   * derived data with no reason to live apart, and a per-repo prompt would ask
+   * the same question four times to arrive at four siblings.
+   */
+  graphRoot?: string;
 }
 
 /** What `gh auth status` says the active token may do. */
@@ -398,12 +410,19 @@ function buildProject(a: SetupAnswers): ProjectConfig {
   const dir = stateDir();
 
   const repos: Record<string, RepoTarget> = {};
+  const graphRoot = a.graphRoot?.trim();
   for (const r of a.targetRepos) {
     repos[r.name] = {
       name: r.name,
       cloneUrl: r.cloneUrl,
       defaultBranch: r.defaultBranch,
       gates: r.gates.map((g) => ({ cmd: g.cmd, cwd: g.cwd })),
+      // One answered root becomes one clone per routed repo. Omitted entirely
+      // when unanswered rather than written empty: the key's absence is what
+      // makes an existing config's briefs render exactly as they did before.
+      ...(graphRoot === undefined || graphRoot.length === 0
+        ? {}
+        : { graphProject: graphProjectPath(graphRoot, r.name) }),
     };
   }
 
@@ -694,6 +713,19 @@ export function summarisePlan(
     }
   }
 
+  // Absent entirely when unanswered: a plan for a project with no graph must
+  // read exactly as it did before graphs were a thing this wizard could offer.
+  const graphed = graphRepos(project);
+  if (graphed.length > 0) {
+    lines.push("", "code graph     workers query these clones instead of grepping:");
+    for (const r of graphed) lines.push(`                 ${r.name}  ${r.graphProject}`);
+    lines.push(
+      "               conductor's own index-only clones — nothing human edits them, and",
+      "               nothing here creates them. Run `omp-conductor graph-setup` after",
+      "               setup: it prints the clone, index and systemd-timer commands.",
+    );
+  }
+
   lines.push("", "caps (effective)");
   for (const [key, value] of Object.entries(effective)) {
     const answered = Object.hasOwn(project.caps, key) ? "  (answered)" : "";

package/src/types.ts

@@ -46,6 +46,31 @@ export interface RepoTarget {
    * subset lets lint errors outside the source dir reach the runners.
    */
   gates: { cmd: string; cwd: string }[];
+  /**
+   * Absolute path of the **conductor-owned, index-only clone** of this repo
+   * whose code-graph index workers query. Optional: absent means this repo has
+   * no graph, and the worker brief says nothing about one.
+   *
+   * Two things it deliberately is not, and both were paid for:
+   *
+   * - **Not a worker's worktree.** A code-graph index is keyed by the realpath
+   *   of the directory it was built from, with no git-worktree awareness, so a
+   *   run's throwaway `worktrees/<issue>` path is always an empty project. A
+   *   worker that queried its own cwd would find nothing, conclude there is no
+   *   graph, and go back to grepping — which is the entire cost this field
+   *   exists to remove.
+   * - **Not a human's checkout.** Refreshing an index means hard-resetting the
+   *   clone to its default branch. Doing that where somebody works destroys
+   *   their uncommitted edits; making it safe instead (a fast-forward pull)
+   *   means the graph reflects whatever feature branch they left checked out.
+   *   So this names a disposable clone nothing human ever edits, which is what
+   *   makes the reset both safe and deterministic.
+   *
+   * `omp-conductor graph-setup` prints how to create and refresh it. Nothing in
+   * this package reads an index itself: the daemon only passes this path into
+   * the worker brief.
+   */
+  graphProject?: string;
 }
 
 /**

package/src/worktree.ts

@@ -8,8 +8,8 @@
  * for the delta.
  */
 
-import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import type { RepoTarget } from "./types.ts";
 
@@ -96,6 +96,50 @@ async function gitSucceeds(args: string[], cwd?: string): Promise<boolean> {
   return code === 0;
 }
 
+/** Fences the block below so it can be found, replaced, and never duplicated. */
+const EXCLUDE_BEGIN = "# >>> omp-conductor (managed; edit outside this block)";
+const EXCLUDE_END = "# <<< omp-conductor";
+
+/**
+ * Appended to every mirror's `info/exclude`, and so in force in every worktree
+ * cut from it. Deliberately the same shapes salvage therefore skips, and
+ * for the same reason — a worker's own scaffolding is not the repo's business.
+ *
+ * Two layers because they catch different moments: this one keeps scratch out
+ * of a worker's own `git add -A` and out of its `git status`, which salvage
+ * never observes; the salvage list catches whatever a worker created before
+ * this landed, or wrote past an ignore with `add -f`.
+ */
+const LOCAL_EXCLUDE = [".scratch*/", ".scratch*", ".env.local", "*.local.sh"];
+
+/**
+ * Adds the managed block to an `info/exclude`, preserving everything else.
+ *
+ * `info/exclude` is a *local* ignore file, which means it is exactly where an
+ * operator or another tool puts patterns they could not put in the tracked
+ * `.gitignore` — so overwriting it would silently destroy work that has no
+ * other copy. The block is fenced and replaced in place, so re-running this on
+ * every dispatch neither duplicates our lines nor disturbs theirs.
+ */
+export function mergeExclude(existing: string): string {
+  const begin = existing.indexOf(EXCLUDE_BEGIN);
+  const end = existing.indexOf(EXCLUDE_END);
+  const theirs =
+    begin === -1 || end === -1 || end < begin
+      ? existing
+      : existing.slice(0, begin) + existing.slice(end + EXCLUDE_END.length + 1);
+
+  // Normalised before recomposing, so the result is byte-identical on every
+  // call. Trimming the tail matters twice over: a hand-edited file often has no
+  // trailing newline (the first managed line would glue onto their last
+  // pattern and match nothing), and without it the blank separator below would
+  // accumulate one more newline on each of the thousands of dispatches that
+  // call this.
+  const body = theirs.replace(/\n+$/, "");
+  const head = body === "" ? [] : [body, ""];
+  return [...head, EXCLUDE_BEGIN, ...LOCAL_EXCLUDE, EXCLUDE_END, ""].join("\n");
+}
+
 /**
  * Rewrites the two `clone --mirror` defaults that are actively dangerous for a
  * cache we cut worktrees from. Applied on every `ensureMirror` so a mirror left
@@ -122,6 +166,20 @@ async function configureMirror(mirrorPath: string): Promise<void> {
     ["config", "--replace-all", "remote.origin.fetch", TRACKING_REFSPEC],
     mirrorPath,
   );
+
+  // A mirror's `info/exclude` is the common git dir for every worktree cut from
+  // it, so one write here keeps a worker's own scratch out of `git status` in
+  // all of them — without touching the repo's tracked `.gitignore`, which is
+  // the operator's file and not ours to edit.
+  //
+  // Belt and braces with the salvage excludes rather than a replacement for
+  // them: this stops scratch reaching a *worker's* own `git add`, which salvage
+  // never sees. Merged rather than written, because `info/exclude` is precisely
+  // where an operator keeps patterns that cannot go in the tracked file — and
+  // this runs on every dispatch, so overwriting would destroy them repeatedly.
+  const exclude = join(mirrorPath, "info", "exclude");
+  mkdirSync(dirname(exclude), { recursive: true });
+  writeFileSync(exclude, mergeExclude(existsSync(exclude) ? readFileSync(exclude, "utf8") : ""));
 }
 
 /**
@@ -343,7 +401,28 @@ export async function salvageWip(
     const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], worktree);
 
     // `-A` on purpose: the losses this exists for were mostly *new* files.
+    //
+    // Filtering scratch is git's job, not a pathspec's. The mirror's
+    // `info/exclude` (see {@link mergeExclude}) is the common git dir for this
+    // worktree, and git's own rules then give exactly the semantics needed:
+    // untracked ignored files are skipped, while modifications to *tracked*
+    // files are staged even when the name matches an ignore. That second half
+    // is why an exclude pathspec here was wrong — it matched on filename alone,
+    // so a repo legitimately versioning a `bootstrap.local.sh` would have lost
+    // a worker's edits to it, salvage destroying the work it exists to save.
+    //
+    // A literal `:(exclude)<path>` was also an outright bug: git counts it as
+    // naming the path, so an already-ignored file made `add` exit 1 and every
+    // cap-kill would have reported a salvage *failure*.
     await git(["add", "-A"], worktree);
+
+    // The dirty check above ran before git applied its ignores, so a tree whose
+    // only changes were ignored scratch had work by that test and none by this.
+    // Without this, `commit` exits non-zero on an empty index and a tree
+    // holding nothing worth keeping gets reported as a salvage *failure*.
+    if ((await git(["diff", "--cached", "--name-only"], worktree)) === "") {
+      return { kind: "nothing" };
+    }
     await git(
       [
         ...SALVAGE_COMMIT_CONFIG,