@sporhq/spor 0.2.5 → 0.2.7

package/.claude-plugin/plugin.json

@@ -2,6 +2,6 @@
   "name": "spor",
   "displayName": "Spor Context Compiler",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "author": { "name": "losthammer" }
 }

package/README.md

@@ -24,21 +24,8 @@ Requires Node 20+ and nothing else — the client is zero-dependency. To run
 from a checkout instead (e.g. to hack on it), clone the repo and `npm link`
 from its root; that symlinks the same two commands onto your PATH.
 
-Then create the graph home (this is yours, kept outside any code repo):
-
-```bash
-spor init        # creates ~/.spor/nodes, git-inits it, writes .gitignore
-```
-
-`spor init` is idempotent. `spor status` then tells you the resolved mode,
-graph, project, and (in remote mode) server health and identity — run it any
-time you're unsure whether Spor is active or which graph you're on. (Without
-the `spor` CLI on your PATH the equivalent is
-`mkdir -p ~/.spor/nodes && git -C ~/.spor init && printf 'journal/\n' > ~/.spor/.gitignore`.)
-
-Then install for your agent. One verb wires up any supported host — it
-resolves the adapter manifest to this checkout and drops it into the host's
-config:
+Wire Spor into your agent. One verb resolves the adapter manifest to this
+install and drops it into the host's config:
 
 ```bash
 spor install claude     # Claude Code (via its plugin CLI — no marketplace browsing)
@@ -50,26 +37,56 @@ spor install            # no host => list the hosts detected on this machine
 per-repo config. `--all` installs every detected host, `--print` is a dry run,
 and `--server <url> --token <tok>` also points the client at a team graph in
 the same step. Re-running is idempotent — it refreshes the path and never
-duplicates your other hooks.
+duplicates your other hooks. (In Claude Code you can also install by hand:
+`/plugin marketplace add sporhq/spor` then `/plugin install spor@spor`.)
 
-In Claude Code you can still install from the marketplace by hand if you
-prefer:
+Then onboard a repo — one command, from inside it:
 
-```
-/plugin marketplace add sporhq/spor
-/plugin install spor@spor
+```bash
+cd ~/my-repo && spor dispatch --backfill
 ```
 
+That does the whole setup in one step: creates your graph home if it doesn't
+exist yet (`~/.spor/nodes`, git-initialised), registers the repo so Spor knows
+where it lives on this machine, makes sure Spor is enabled for it, and launches
+the `/spor:backfill` agent in a Claude Code background session — it mines git
+history, design docs, and issue trackers (edges first) and proposes how to
+group your repos into projects. Watch or attach to it with `claude agents`.
+Re-run it whenever you add a repo, or skip it entirely and just work —
+distillation grows the graph one session at a time.
+
+`spor status` tells you the resolved mode, graph, project, and (on a team
+graph) server health and identity — run it any time you're unsure whether Spor
+is active or which graph you're on. `spor init` does the graph-home setup on
+its own if you'd rather not dispatch anything yet.
+
 For the per-host event mapping, fidelity notes, distiller backend, and the
 `AGENTS.md` fallback for hosts with no hook support, see
 [adapters/](adapters/).
 
-To start with a populated graph, run `/spor:backfill` — the onboarding door. It
-dispatches the heavy mining (git history, design docs, issue trackers, edges
-first) to the bundled `spor-backfill` **subagent**, which runs in its own
-context, and then proposes how to group your repos into projects (re-run it as
-you add repos). Or skip it and just work — distillation grows the graph one
-session at a time.
+## Dispatching background agents
+
+`spor dispatch` hands a task to Claude Code's background-agent machinery
+(`claude --bg`) with a briefing already compiled in:
+
+```bash
+spor dispatch "wire up token rotation in the pipeline"   # free-text task, briefed
+spor dispatch issue-86                                    # a node id — briefs its neighborhood
+spor dispatch --from-queue                                # the top item from 'spor next'
+spor dispatch --backfill                                  # onboard this repo via /spor:backfill
+spor dispatch <task> --print                              # dry run: show dir, prompt, argv
+```
+
+It compiles the briefing (the same two-arm compiler the `/spor:brief` skill
+drives), prepends it to the prompt, and launches `claude --bg` **in the right
+repo**. Which directory that is comes from a per-machine slug→path map: the
+shared graph is path-free by design (every teammate clones to a different
+path), so the map is local, kept in the config cascade under `dispatch.repos`
+(`spor repos` to inspect; written to `$SPOR_HOME/config.json`). It self-learns
+as you open sessions, so by the time you dispatch a node from another repo,
+Spor already knows where that repo lives. Flags pass through to `claude`
+(`--model`, `--permission-mode`, `--agent`, `--name`); `--full` embeds the whole
+neighborhood and `--no-brief` skips the briefing.
 
 ## What your agent gets, and gives back
 

package/bin/spor.js

@@ -57,6 +57,14 @@ Repo scoping
   brief <id>           compile a briefing for a node (alias: compile --root <id>)
   validate             lint the local graph (byte-identical)
 
+Dispatch (Claude Code background agents)
+  dispatch "<task>"    compile a briefing + launch 'claude --bg' in the repo.
+                       Also: dispatch <node-id> | --node <id> | --from-queue |
+                       --backfill. Flags: --dir P, --full, --no-brief, --model M,
+                       --permission-mode P, --agent A, --name N, --print
+  repos                show the local slug->repo-dir map used to pick the
+                       directory (repos add <slug> <path> | repos rm <slug>)
+
 Other
   cost [--since D]      LLM spend summary from journal/llm-calls (local)
   version              print version
@@ -93,7 +101,10 @@ function nodeCount(nodesDir) {
   }
 }
 
-function cmdInit(cfg) {
+// Idempotently create the local graph home (nodes/, git, .gitignore). Returns
+// { home, nodesDir, created } and prints nothing — callers do their own UX.
+// Shared by `spor init` and the `spor dispatch --backfill` onboarding path.
+function ensureGraphHome(cfg) {
   const home = cfg.graphHome();
   const nodesDir = path.join(home, "nodes");
   let created = false;
@@ -114,6 +125,11 @@ function cmdInit(cfg) {
       /* non-fatal */
     }
   }
+  return { home, nodesDir, created };
+}
+
+function cmdInit(cfg) {
+  const { home, nodesDir, created } = ensureGraphHome(cfg);
   out(`${created ? "Created" : "Graph already present at"} ${home}`);
   out(`  nodes:  ${nodesDir} (${nodeCount(nodesDir) ?? 0} nodes)`);
   out(`  mode:   ${cfg.mode()}`);
@@ -905,6 +921,312 @@ async function cmdInstall(cfg, args) {
   return rc;
 }
 
+// --- spor dispatch: kick off a Claude Code background agent --------------
+// (task-spor-cli-dispatch-background-agents) Compile a briefing for a task and
+// launch `claude --bg "<prompt>"` in the correct repo. The "correct repo" comes
+// from a per-machine slug->path map stored in the config cascade under
+// `dispatch.repos` (read via cfg.get; written to $SPOR_HOME/config.json) — the
+// shared graph is path-free by design (repo nodes carry slugs/fingerprints,
+// never a local path; teammates clone to different paths), so the map MUST be
+// local. It self-learns from session-start and from `--dir`/`spor repos`.
+
+// Read a single frontmatter scalar from raw node markdown (regex, like the
+// engines' parser — no YAML lib). `repo:` is the current stamp; `project:` legacy.
+function fmField(raw, key) {
+  const m = raw.match(new RegExp(`^${key}: *(.*)$`, "m"));
+  return m ? m[1].trim() : null;
+}
+
+// Resolve a node id to { id, raw, repo, title } or null if it doesn't exist.
+async function resolveNode(cfg, id) {
+  let raw = "";
+  if (cfg.mode() === "remote") {
+    const r = await remote.get(cfg, `/v1/nodes/${encodeURIComponent(id)}`, { timeoutMs: 6000 });
+    if (!r.ok) return null;
+    raw = (r.json && r.json.raw) || r.text || "";
+  } else {
+    try {
+      raw = fs.readFileSync(path.join(cfg.nodesDir(), `${id}.md`), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  return { id, raw, repo: fmField(raw, "repo") || fmField(raw, "project"), title: fmField(raw, "title") || "" };
+}
+
+// Compile a briefing: a node id -> its neighborhood; free text -> a digest.
+// Mode-aware, reusing the primitives the /spor:brief skill drives. Default is
+// the compact digest; `full` emits the whole neighborhood. "" = graph had
+// nothing relevant (or the compile failed — fail-soft, dispatch still proceeds).
+async function compileBriefing(cfg, { nodeId, query, full, project }) {
+  if (cfg.mode() === "remote") {
+    if (nodeId) {
+      const r = await remote.get(cfg, `/v1/nodes/${encodeURIComponent(nodeId)}`, { timeoutMs: 8000 });
+      return r.ok && r.json ? r.json.raw || r.text || "" : "";
+    }
+    const r = await remote.post(cfg, "/v1/digest", project ? { query, project } : { query });
+    return r.ok && r.json && r.json.found !== false ? r.json.text || "" : "";
+  }
+  const args = nodeId ? ["--root", nodeId] : ["--query", query];
+  if (!full) args.push("--digest");
+  if (project) args.push("--project", project);
+  args.push("--quiet"); // suppress the stderr stats / no-graph lines
+  const r = spawnSync(process.execPath, [path.join(ROOT, "lib", "compile.js"), ...args], { encoding: "utf8" });
+  return (r.stdout || "").trim();
+}
+
+// The single highest-ranked open queue item (for --from-queue). Mode-aware,
+// fail-soft (null on any error/empty).
+async function topQueueItem(cfg, slug) {
+  if (cfg.mode() === "remote") {
+    const q = slug ? `?project=${encodeURIComponent(slug)}&limit=1` : "?limit=1";
+    const r = await remote.get(cfg, `/v1/queue${q}`, { timeoutMs: 6000 });
+    return r.ok && r.json ? (r.json.items || [])[0] || null : null;
+  }
+  try {
+    const g = require(path.join(ROOT, "lib", "graph.js")).loadGraph(cfg.nodesDir());
+    const { rankQueue } = require(path.join(ROOT, "lib", "queue.js"));
+    const r = rankQueue(g, slug ? { project: slug, limit: 1 } : { limit: 1 });
+    return (r.items || [])[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve the directory to launch in. --dir wins; else a known slug is looked up
+// in the map; else the cwd's repo root. { dir:null } means "slug unknown here".
+function resolveDir(cfg, { dir, slug }) {
+  if (dir) {
+    const abs = path.resolve(dir);
+    return { dir: abs, slug: slug || u.projectSlug(abs), source: "--dir" };
+  }
+  if (slug) {
+    const p = (cfg.get("dispatch.repos", {}) || {})[slug];
+    return p ? { dir: p, slug, source: "config" } : { dir: null, slug, source: "unknown" };
+  }
+  return { dir: repoRoot(), slug: safeSlug(), source: "cwd" };
+}
+
+// Quote an argv element for the --print display only (never used to spawn).
+function shellQuote(s) {
+  return /[^\w./:-]/.test(s) ? `'${String(s).replace(/'/g, "'\\''")}'` : s;
+}
+
+// Re-enable Spor for a repo by merging { enabled: true } into its committable
+// .spor.json (and clearing a `mode: off`, which also disables). Used by the
+// --backfill onboarding to repair a repo a prior `spor disable` turned off.
+function enableRepoAt(dir) {
+  const file = path.join(dir, ".spor.json");
+  let data = {};
+  try {
+    data = JSON.parse(fs.readFileSync(file, "utf8")) || {};
+  } catch {
+    /* absent or malformed — start fresh */
+  }
+  data.enabled = true;
+  if (data.mode === "off") delete data.mode;
+  try {
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+  } catch {
+    /* non-fatal */
+  }
+}
+
+// `spor dispatch --backfill` is the onboarding door (task-spor-cli-dispatch-
+// background-agents): set the repo up before launching its backfill agent.
+// Idempotent; prints what it did. The dir-registration happens in cmdDispatch
+// (it applies to every dispatch), this adds the init + enable steps.
+function onboardRepo(cfg, dir) {
+  // Init the local graph home — but only in local mode; remote mode keeps the
+  // graph on the server, so there is nothing to create locally.
+  if (cfg.mode() !== "remote") {
+    const r = ensureGraphHome(cfg);
+    out(r.created ? `initialized graph home at ${r.home}` : `graph home ready: ${r.home}`);
+  }
+  // Re-enable the repo if a prior `spor disable` turned it off, so onboarding a
+  // disabled repo actually works instead of silently launching into a no-op.
+  if (!cfg.enabled()) {
+    enableRepoAt(dir);
+    out(`re-enabled Spor for ${dir}`);
+  }
+}
+
+async function cmdDispatch(cfg, args) {
+  const dryRun = args.includes("--print") || args.includes("--dry-run");
+  const full = args.includes("--full");
+  const noBrief = args.includes("--no-brief");
+  const backfill = args.includes("--backfill");
+  const fromQueue = args.includes("--from-queue");
+  const dirOpt = optVal(args, "dir");
+  const model = optVal(args, "model");
+  const permMode = optVal(args, "permission-mode");
+  const agent = optVal(args, "agent");
+  let nodeId = optVal(args, "node");
+  let targetSlug = optVal(args, "slug");
+  let name = optVal(args, "name");
+
+  // Positional task text: everything that isn't a flag or a flag's value.
+  const VALUE_OPTS = new Set(["dir", "node", "slug", "model", "permission-mode", "agent", "name"]);
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      if (VALUE_OPTS.has(a.slice(2))) i++;
+      continue;
+    }
+    pos.push(a);
+  }
+  let taskText = pos.join(" ").trim();
+
+  let brief = "";
+  let instruction = "";
+
+  if (fromQueue) {
+    const top = await topQueueItem(cfg, targetSlug);
+    if (!top || !top.id) {
+      err("queue empty — nothing to dispatch");
+      return 1;
+    }
+    nodeId = top.id;
+    targetSlug = targetSlug || top.repo || top.project || null;
+  }
+
+  if (backfill) {
+    // Onboarding a (possibly thin) repo: dispatch the skill; no briefing to compile.
+    instruction = taskText ? `/spor:backfill\n\n${taskText}` : "/spor:backfill";
+    name = name || "spor-backfill";
+  } else if (!nodeId && pos.length === 1 && /^[a-z0-9]+(-[a-z0-9]+)+$/.test(pos[0])) {
+    // Auto-detect: a single hyphenated token that resolves to a node => node mode.
+    const maybe = await resolveNode(cfg, pos[0]);
+    if (maybe) {
+      nodeId = maybe.id;
+      taskText = "";
+    }
+  }
+
+  if (!backfill && nodeId) {
+    const node = await resolveNode(cfg, nodeId);
+    if (!node) {
+      err(`no such node: ${nodeId}`);
+      return 1;
+    }
+    targetSlug = targetSlug || node.repo || null;
+    if (!noBrief) brief = await compileBriefing(cfg, { nodeId, full, project: targetSlug });
+    instruction = `Work on ${nodeId}${node.title ? ` — ${node.title}` : ""}. The compiled Spor briefing above is your standing context.${taskText ? ` ${taskText}` : ""}`;
+    name = name || nodeId;
+  } else if (!backfill) {
+    if (!taskText) {
+      err('usage: spor dispatch "<task>" | --node <id> | --from-queue | --backfill');
+      return 1;
+    }
+    if (!noBrief) brief = await compileBriefing(cfg, { query: taskText, full, project: targetSlug });
+    instruction = taskText;
+    name = name || taskText.split(/\s+/).slice(0, 8).join(" ").slice(0, 60);
+  }
+
+  const res = resolveDir(cfg, { dir: dirOpt, slug: targetSlug });
+  if (!res.dir) {
+    err(`don't know where '${res.slug}' lives on this machine.`);
+    err(`  run 'spor dispatch' from inside that repo once (it self-registers), then re-run, or:`);
+    err(`  spor repos add ${res.slug} <path>`);
+    err(`  or pass --dir <path>.`);
+    return 1;
+  }
+  if (!fs.existsSync(res.dir)) {
+    err(`target dir does not exist: ${res.dir}`);
+    return 1;
+  }
+  const prompt = brief
+    ? `# Spor briefing (compiled for this task — your standing context)\n\n${brief}\n\n---\n\n# Task\n\n${instruction}\n`
+    : instruction;
+
+  const claudeBin = process.env.SPOR_CLAUDE_CMD || "claude";
+  const claudeArgs = ["--bg"];
+  if (name) claudeArgs.push("--name", name);
+  if (model) claudeArgs.push("--model", model);
+  if (permMode) claudeArgs.push("--permission-mode", permMode);
+  if (agent) claudeArgs.push("--agent", agent);
+  claudeArgs.push(prompt);
+
+  if (dryRun) {
+    out(`dir:    ${res.dir}  (slug: ${res.slug}, via ${res.source})`);
+    if (backfill) {
+      const steps = [];
+      if (cfg.mode() !== "remote") steps.push(fs.existsSync(cfg.nodesDir()) ? "graph home ready" : "init graph home");
+      steps.push(`register ${res.slug} → ${res.dir}`);
+      if (!cfg.enabled()) steps.push("re-enable repo (currently disabled)");
+      out(`onboard: ${steps.join("; ")}`);
+    }
+    out(`brief:  ${brief ? `${brief.length} bytes` : "(none — graph had nothing relevant, or --no-brief/--backfill)"}`);
+    out(`run:    ${claudeBin} ${claudeArgs.slice(0, -1).map(shellQuote).join(" ")} <prompt>`);
+    out(`\n--- prompt ---\n${prompt}`);
+    return 0;
+  }
+
+  // Side effects (real run only — --print writes nothing). --backfill is the
+  // onboarding door, so it sets the repo up (init + enable) first; every
+  // dispatch self-registers the dir it resolved.
+  if (backfill) onboardRepo(cfg, res.dir);
+  u.registerRepo(cfg.graphHome(), res.slug, res.dir);
+  if (backfill) out(`registered ${res.slug} → ${res.dir}; launching the backfill agent…`);
+
+  if (claudeBin === "claude" && !hasCmd("claude")) {
+    err("claude CLI not on PATH — install Claude Code, then re-run (or 'spor dispatch … --print' to see the prompt).");
+    return 1;
+  }
+  const r = spawnSync(claudeBin, claudeArgs, { cwd: res.dir, stdio: "inherit" });
+  if (r.error) {
+    err(`could not launch ${claudeBin}: ${r.error.message}`);
+    return 1;
+  }
+  return r.status == null ? 1 : r.status;
+}
+
+// --- spor repos: inspect/manage the local slug->path map -----------------
+function cmdRepos(cfg, args) {
+  const home = cfg.graphHome();
+  const sub = args[0];
+  if (!sub || sub === "list") {
+    // Resolved through the config cascade (dispatch.repos), so user, global, and
+    // any repo/env override layers compose; writes land in $SPOR_HOME/config.json.
+    const map = cfg.get("dispatch.repos", {}) || {};
+    const keys = Object.keys(map).sort();
+    if (!keys.length) {
+      out("no repos mapped yet — they self-register as you open sessions, or: spor repos add <slug> <path>");
+      return 0;
+    }
+    for (const k of keys) out(`${k}\t${map[k]}`);
+    return 0;
+  }
+  if (sub === "add" || sub === "set") {
+    const slug = args[1];
+    const p = args[2];
+    if (!slug || !p) {
+      err("usage: spor repos add <slug> <path>");
+      return 1;
+    }
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+      err(`invalid slug '${slug}' — must match ^[a-z0-9][a-z0-9-]*$`);
+      return 1;
+    }
+    const abs = path.resolve(p);
+    u.registerRepo(home, slug, abs);
+    out(`mapped ${slug} -> ${abs}`);
+    return 0;
+  }
+  if (sub === "rm" || sub === "remove" || sub === "forget") {
+    const slug = args[1];
+    if (!slug) {
+      err("usage: spor repos rm <slug>");
+      return 1;
+    }
+    out(u.forgetRepo(home, slug) ? `forgot ${slug}` : `no mapping for ${slug}`);
+    return 0;
+  }
+  err("usage: spor repos [list] | spor repos add <slug> <path> | spor repos rm <slug>");
+  return 1;
+}
+
 function version() {
   try {
     return require(path.join(ROOT, "package.json")).version || "0.0.0";
@@ -967,6 +1289,11 @@ async function main() {
     case "compile":
     case "brief":
       return cmdCompile(cfg, verb, args);
+    case "dispatch":
+    case "bg":
+      return await cmdDispatch(cfg, args);
+    case "repos":
+      return cmdRepos(cfg, args);
     case "validate":
       return passthrough("validate.js", args);
     case "cost":

package/lib/config.js

@@ -46,7 +46,7 @@ const REPO_FORBIDDEN_KEYS = ["token"];
 // warning so a silently-ignored setting is visible rather than mysterious.
 const KNOWN_KEYS = new Set([
   "mode", "server", "token", "home", "nodes", "enabled",
-  "search", "distill", "nudge", "inferCommits",
+  "search", "distill", "nudge", "inferCommits", "dispatch",
 ]);
 
 // Map of env var (sans SPOR_/SUBSTRATE_ prefix) -> config key path. Only vars

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
   "license": "Apache-2.0",
   "author": "Anthony Allen",

package/scripts/engines/session-start.js

@@ -100,6 +100,22 @@ async function sessionStart(input) {
     /* best effort */
   }
 
+  // Learn where this slug lives on THIS machine (slug -> checkout path), so
+  // `spor dispatch` can later launch `claude --bg` in the right repo without a
+  // path map in the shared graph (paths differ per teammate; repo nodes carry
+  // slugs/fingerprints, never a local path). inferenceRoot() is the same repo
+  // root projectSlug() derives the slug from, so path and slug stay consistent
+  // and a linked worktree resolves to its main checkout. Pure side effect: never
+  // alters this run's output; fail-open (registerRepo no-ops on a non-canonical
+  // slug or unchanged value). (task-spor-cli-dispatch-background-agents)
+  try {
+    if (cwd && fs.existsSync(cwd)) {
+      u.registerRepo(graph, slug, u.inferenceRoot(cwd) || cwd);
+    }
+  } catch {
+    /* best effort */
+  }
+
   // -------------------------------------------------------------------------
   // REMOTE MODE
   // -------------------------------------------------------------------------

package/scripts/engines/util.js

@@ -331,6 +331,71 @@ function ensureDir(dir) {
   }
 }
 
+// --- local repo map (slug -> checkout path) -------------------------------
+// Which directory a project slug lives in on THIS machine. Per-machine and
+// machine-specific: it is NEVER in the shared graph (every teammate clones to a
+// different path — repo nodes carry slugs/fingerprints, never a local path).
+// It lives in the client config cascade under `dispatch.repos`
+// (dec-spor-client-config-cascade), so it composes with the env/global/repo
+// override layers and is READ via Config.get('dispatch.repos'). Writes target
+// the USER config ($SPOR_HOME/config.json) — the same machine-local,
+// never-committed file that holds server/token — so they never land in a
+// committable repo .spor.json. Learned passively by session-start and written
+// explicitly by `spor repos`/`spor dispatch`; fail-open throughout.
+function userConfigPath(graphHomeDir) {
+  return path.join(graphHomeDir, "config.json");
+}
+// Read-modify-write $SPOR_HOME/config.json, applying `mutate(repos)` to the
+// nested dispatch.repos object. Preserves every other key. Returns true only
+// when it actually wrote. Refuses to clobber a present-but-malformed config
+// (returns false) so a syntax error never costs the user their settings.
+function editRepoMap(graphHomeDir, mutate) {
+  try {
+    const file = userConfigPath(graphHomeDir);
+    let raw = null;
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch {
+      raw = null; // absent — start fresh
+    }
+    let data = {};
+    if (raw != null) {
+      try {
+        data = JSON.parse(raw);
+      } catch {
+        return false; // malformed — do NOT overwrite
+      }
+      if (data == null || typeof data !== "object" || Array.isArray(data)) data = {};
+    }
+    if (data.dispatch == null || typeof data.dispatch !== "object" || Array.isArray(data.dispatch)) data.dispatch = {};
+    const d = data.dispatch;
+    if (d.repos == null || typeof d.repos !== "object" || Array.isArray(d.repos)) d.repos = {};
+    if (!mutate(d.repos)) return false; // unchanged — skip the write
+    if (!ensureDir(graphHomeDir)) return false;
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+// Record slug -> dir (last-writer-wins, so a re-clone or worktree updates it).
+// No-op when unchanged, to avoid rewriting config.json on every session.
+function registerRepo(graphHomeDir, slug, dir) {
+  if (!slug || !dir || !/^[a-z0-9][a-z0-9-]*$/.test(slug)) return false;
+  return editRepoMap(graphHomeDir, (repos) => {
+    if (repos[slug] === dir) return false;
+    repos[slug] = dir;
+    return true;
+  });
+}
+function forgetRepo(graphHomeDir, slug) {
+  return editRepoMap(graphHomeDir, (repos) => {
+    if (!(slug in repos)) return false;
+    delete repos[slug];
+    return true;
+  });
+}
+
 function appendLine(file, line) {
   try {
     fs.appendFileSync(file, line + "\n");
@@ -602,11 +667,14 @@ module.exports = {
   byteTail,
   wordCount,
   stripTrailingNewlines,
+  inferenceRoot,
   projectSlug,
   projectGrouping,
   repoFingerprints,
   git,
   ensureDir,
+  registerRepo,
+  forgetRepo,
   appendLine,
   makeLogger,
   loadGraphCached,