omp-conductor 0.3.3 → 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.3",
+  "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/escalate.ts

@@ -233,22 +233,32 @@ async function sendTelegram(token: string, chatId: string, text: string): Promis
     throw new Error(`telegram sendMessage failed: ${redact(reason, token)}`);
   }
 
-  const payload = redact(await res.text().catch(() => ""), token).slice(0, 400);
+  // The raw body is what gets parsed; `diagnostic` is only ever for humans.
+  // These were one variable once, and the bug that produced was expensive: the
+  // 400-char cap meant for a log line was applied first, so `JSON.parse` was
+  // handed a truncated object and threw. Telegram echoes the whole message back
+  // inside `result.text`, so every page long enough to matter overflowed and was
+  // reported as rejected *after being delivered* — with the dedup marker only
+  // written on success, that also re-sent the same page every tick. Redaction
+  // stays out of the parse for the same reason: it rewrites the very bytes the
+  // decision is read from.
+  const raw = await res.text().catch(() => "");
+  const diagnostic = redact(raw, token).slice(0, 400);
   if (!res.ok) {
-    throw new Error(`telegram sendMessage failed: HTTP ${res.status} ${payload}`);
+    throw new Error(`telegram sendMessage failed: HTTP ${res.status} ${diagnostic}`);
   }
 
   // Telegram answers 200 with `{"ok":false}` for plenty of real failures
   // (kicked from the chat, bad chat_id), so the status alone proves nothing.
   let ok = false;
   try {
-    const parsed: unknown = JSON.parse(payload);
+    const parsed: unknown = JSON.parse(raw);
     ok = typeof parsed === "object" && parsed !== null && "ok" in parsed && parsed.ok === true;
   } catch {
     ok = false;
   }
   if (!ok) {
-    throw new Error(`telegram sendMessage rejected: ${payload}`);
+    throw new Error(`telegram sendMessage rejected: ${diagnostic}`);
   }
 }