pi-odd-worktree 1.0.0 → 1.1.1

package/README.md

@@ -15,9 +15,12 @@ alone; Herdr is optional.
 | `worktree_create` | tool | Creates a branch and its checkout from the **local** `main`, registers it, runs the creation hooks, and copies the pending changes you name. |
 | `worktree_warp` | tool | Queues the session move to another checkout as a `/warp` handoff; the command performs the move when the turn ends. |
 | `worktree_close` | tool | Removes a registered checkout with `git worktree remove`, keeping the branch, and refuses while a live Pi session is working in it. |
-| `/warp` | panel | Moves this session to another checkout: no argument opens the selector (list, create, delete, extended list); `/warp <name>` jumps straight there. |
+| `/warp` | panel | Moves this session to another checkout: no argument opens the selector (list, create, delete, extended list); `/warp <name>` jumps straight there. A session with no conversation yet changes checkout **silently** — no fork, no `Warp · moved` card, nothing to carry — and warping back from it is the same empty case. |
 | `/odd-list` | panel | Two-pane reader of this checkout's `odd/tasks/*.md`: list on the left, styled markdown on the right. |
 | `/issues` | panel | Full-screen reader of this checkout's repository issues — My issues / Assigned / Involved / All — with preview, comments, labels, assignees and close, gated on your repository role. |
+| `/codegraph-hook` | command | **Only when the CodeGraph CLI is installed.** Turns the edit/write sync on or off for the session. |
+| `/codegraph-init` | command | **Only when the CLI is installed.** Runs `codegraph init` at the session's current directory and says what happened: `initialized <path> — 1 file, 3 nodes, 3 edges`, or `already initialized at <path> — nothing to do`. |
+| `/codegraph-sync` | command | **Only when the CLI is installed.** Runs `codegraph sync` at the session's current directory and says what happened: `already up to date — nothing to sync`, `synced 3 changed files — 12 nodes`, or `no index in this checkout — run /codegraph-init first`. |
 
 A checkout's **name** is the slug of its branch, and its path is
 `<repo-parent>/<repo-name>-worktrees/<slug>`: the slug lowercases the branch and
@@ -33,6 +36,7 @@ interchangeably by `worktree_close`, and by `/warp`.
 | Node.js >= 18 and `git` | `engines` declares 18 as the floor, and every repository operation is a git child process. |
 | `herdr` — optional | Not required: only `worktree_create` tries a Herdr workspace association, and it falls back to plain `git`. |
 | `gh`, authenticated (`gh auth login`) | `/issues` only. Without it the command stays registered, says once per session what is missing, and never opens. |
+| `codegraph` — optional | Keeps each checkout's index fresh: `codegraph init` when a checkout is created, and a background `codegraph sync` after edits and writes. Absent, both stay off for the whole session. |
 | Gentle Shell — recommended | Supplies the presence and transport records the deletion guard reads to see sessions other than this one. |
 
 ```bash
@@ -160,18 +164,80 @@ the checkout's remote moves while the reader is open, mutations refuse with
 …); reopen /issues`, and the reads keep the displayed repository. An issue
 number on screen can never be sent to another repository.
 
+### CodeGraph stays fresh, when the CLI is installed
+
+The probe for `codegraph` on `PATH` runs **once per session** and is cached for
+everything below. Install the CLI mid-session and nothing changes until the next
+start, unless you set `CODEGRAPH_FORCE=1`, which answers "present" without
+probing.
+
+- **On creation**, `worktree_create` runs `codegraph init` inside the new
+  checkout, so it starts with its own index. A session where the gate answered
+  false reports that step as `skipped` and names the gate as the reason; it never
+  silently pretends to have indexed anything.
+- **On edits**, a successful `edit` or `write` schedules `codegraph sync` for the
+  git toplevel of the file touched, so a worktree syncs that worktree. The sync is
+  detached: the tool result never waits for it, and a failure never reaches you.
+- **Debounced and coalesced.** Rapid edits collapse into one sync after ~2s, and
+  an edit that lands while a sync runs starts exactly one more when it ends —
+  never a queue.
+- **One sync at a time across sessions**, guarded by
+  `<root>/.codegraph/pi-sync.lock` holding `{pid, startedAt}`. A lock held by a
+  live process means skip (the other session's sync already covers that tree),
+  with one bounded retry so the edit that raced it still lands. A dead pid or an
+  expired lock is taken over.
+- **Skipped when it would be wasted**: no `.codegraph/` in that checkout, or a
+  live CodeGraph daemon (`<root>/.codegraph/daemon.pid`, either the JSON record
+  1.6 writes or the older bare pid), whose own watcher is already syncing that
+  tree.
+- **Bounded**: a sync that never finishes is terminated after two minutes so a
+  checkout can never be wedged for the rest of the session.
+
+Three commands exist **only when the CLI is present**, and they do not appear at
+all otherwise:
+
+| Command | What it does |
+| --- | --- |
+| `/codegraph-hook` | Turns the edit/write sync on or off for the whole process. No argument toggles; `on`, `off` and `status` say it explicitly. It starts enabled. |
+| `/codegraph-init` | Runs `codegraph init` at the session's current directory. |
+| `/codegraph-sync` | Runs `codegraph sync` at the session's current directory. |
+
+The toggle lasts for the session — this package writes nothing to user
+configuration — so `CODEGRAPH_HOOK=0` is how you start a session with it off.
+
+### The `## ODD worktrees` block in the system prompt
+
+The primary session's system prompt gains a short section telling the agent where
+worktrees live, to resume an ODD in its assigned one, and — when `codegraph` is
+present — that creation indexes the checkout and edits sync it.
+
+It is **appended**, never substituted: the block rides
+`systemPromptOptions.appendSystemPrompt`, so whatever Gentle Shell (or any other
+extension) put there is preserved verbatim and our text lands after it. Two
+variants exist, with and without the CodeGraph sentences, chosen by the same
+session gate. Child and named-agent sessions get nothing, because their own
+instructions are already the bounded task they received. `ODD_WORKTREE_PROMPT=0`
+suppresses the block.
+
+One limit, stated plainly: a string has no "must be last" flag, so the block's
+position follows extension load order. It can sit before a later extension's
+short hint; it can never land inside or in place of another extension's text.
+
 ### Where state lives
 
 The worktree registry is per repository at `<git-common-dir>/pi-worktrees.json`,
 so every worktree of the same clone sees the same rows. Session names derived
 from an ODD write, and the warp's fork/resume bookkeeping, travel in the Pi
-session files the host already owns. Nothing is written to user configuration.
+session files the host already owns. The only other file this package writes is
+the short-lived `<root>/.codegraph/pi-sync.lock`. Nothing is written to user
+configuration.
 
 ### Deliberately absent
 
 This package is the worktree / ODD / issues surface only: no customize panel, no
 plugin-tools toggles, no Herdr plugin management, and no worktree↔issue
-association. There is nothing to configure, and the three commands are always on.
+association. There is nothing to configure, and `/warp`, `/odd-list` and
+`/issues` are always on (the three `/codegraph-*` commands follow the CLI).
 Paths, branches and arguments reach `git`, `herdr` and `gh` as fixed argv arrays,
 never as a shell string.
 

package/extensions/odd-worktree-tools.ts

@@ -4244,6 +4244,16 @@ function warpNoticeText(targetCwd, branch) {
   return `Worktree warp: now in ${to} (branch '${cleanBranch}').`;
 }
 
+// S1 (warp-empty-session): what an EMPTY session's warp reports. It names
+// WHERE the session now is and never a move: nothing was carried, so the
+// `moved:`/`to:` compact — and the card that accompanies it — would claim a
+// transition that did not happen.
+function warpEmptyText(name, targetCwd) {
+  const toName = warpClean(name, 'worktree');
+  const to = warpClean(targetCwd, '(unknown checkout)');
+  return `worktree warp: ${toName} (empty session, nothing to carry; now at ${to})`;
+}
+
 // Deepest live checkout containing a cwd, by resolved identity — the one
 // rule the listing, the selector title and the already-there check share.
 // `extraIds` lets the already-there check keep its target-cwd candidate
@@ -4813,6 +4823,18 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
     }
     if (handoff) await warpConfirm(r, warpHandoffNotice, true);
   };
+  // S1/S3 (warp-empty-session): the switched-to session of an EMPTY warp is
+  // told nothing — no card, and no handoff continuation either, because the
+  // session carries no task yet (the already-there no-op answers a handoff
+  // with text only, for the same reason). The status line stays: it says
+  // WHERE the session is, not what it carried.
+  const warpSilentWithSession = async (r) => {
+    try {
+      r.ui.setStatus("worktree", `${displayName} (${targetCwd})`);
+    } catch {
+      // Status is cosmetic; the silence is the point.
+    }
+  };
   // S43 records. The POINT of a session is its ACTIVE branch (the live
   // leaf's parentId path, never all append-only entries) filtered to
   // entries that are NOT our own bookkeeping — the custom marker, the
@@ -4855,6 +4877,16 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
   const currentPoint = warpSessions.sessionPoint(
     currentEntriesList, typeof currentLeaf === "string" ? currentLeaf : undefined,
   );
+  // S1/S5 (warp-empty-session): an EMPTY session is one whose active branch
+  // carries no conversation — no `message` entry with role user or assistant
+  // outside the warp bookkeeping, so a rename, the session-worktree
+  // registration or a transition marker never counts as content. It has
+  // nothing to carry, so its warp changes PATH instead of moving work: never
+  // a fork (the host refuses a conversation-less source), never a card, never
+  // a "moved:" claim.
+  const sessionEmpty = !warpSessions.hasConversation(
+    currentEntriesList, typeof currentLeaf === "string" ? currentLeaf : undefined,
+  );
   const warpFileOpen = options && typeof options.warpSessionFileOpen === "function"
     ? options.warpSessionFileOpen
     : undefined;
@@ -5023,7 +5055,13 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
           // cached fingerprint. An unreadable destination never resumes.
           // Never throws: any comparison failure reads as "fork".
           const freshDestPoint = warpFreshPoint(recorded.sessionFile);
-          if (freshDestPoint !== null && warpSessions.samePoint(currentPoint, freshDestPoint)) {
+          // An empty source has no point to compare (its own point is empty
+          // by definition), so it RESUMES the destination session whenever
+          // that file is readable — the conversation it already holds (S4)
+          // or its own emptiness — instead of allocating a copy of nothing. A
+          // session with conversation keeps the same-point gate.
+          if (freshDestPoint !== null
+            && (sessionEmpty || warpSessions.samePoint(currentPoint, freshDestPoint))) {
             recordedSession = recorded;
             recordedFreshPoint = freshDestPoint;
           }
@@ -5039,7 +5077,9 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
   if (recordedSessionFile !== null) {
     let resumed;
     try {
-      resumed = await ctx.switchSession(recordedSessionFile, { withSession: warpResumeWithSession });
+      resumed = await ctx.switchSession(recordedSessionFile, {
+        withSession: sessionEmpty ? warpSilentWithSession : warpResumeWithSession,
+      });
     } catch (err) {
       return failAfterCopy(
         `worktree warp: the session switch to ${targetCwd} failed: ${(err && err.message) || err}; the recorded warp session was kept`,
@@ -5066,8 +5106,12 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
     );
     emitOsc7(options.oscStream || process.stdout, targetCwd);
     return {
-      text: moveText,
-      details: { name: displayName, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false, ...handoffCopyDetails() },
+      text: sessionEmpty ? warpEmptyText(name, targetCwd) : moveText,
+      details: {
+        name: displayName, path: targetCwd, branch: displayBranch, kind: resolved.kind,
+        alreadyThere: false, cancelled: false,
+        ...(sessionEmpty ? { emptySession: true } : {}), ...handoffCopyDetails(),
+      },
     };
   }
   const sm = ctx.sessionManager || {};
@@ -5082,7 +5126,11 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
   const leaf = typeof sm.getLeafId === "function" ? safe(() => sm.getLeafId()) : null;
   const sessionDir = typeof sm.getSessionDir === "function" ? safe(() => sm.getSessionDir()) : undefined;
   let carried = [];
-  if (!warpSourceUsable(file, warpFileOpen)) {
+  // S1: an empty session is allowed through without a persisted file or
+  // in-memory entries — the refusal below exists because a session with
+  // nothing to carry had nothing to warp FOR, and the empty path now changes
+  // its path instead of carrying anything.
+  if (!sessionEmpty && !warpSourceUsable(file, warpFileOpen)) {
     const entries = typeof sm.getEntries === "function" ? safe(() => sm.getEntries()) : undefined;
     carried = Array.isArray(entries) ? entries : [];
     if (carried.length === 0) {
@@ -5093,6 +5141,82 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
     }
   }
   const SM = options.sessionManagerClass || await sessionManagerClassFor(ctx);
+  // S3 (warp-empty-session): an empty session changes PATH. There is nothing
+  // to carry, so nothing is forked (`forkFrom` refuses a conversation-less
+  // source anyway) and the in-place move the host would need does not exist —
+  // `switchSession(file)` is the only mount, and a session's cwd comes from
+  // its own header. So the equivalent is used: a FRESH session allocated at
+  // the target cwd through the same create/switch machinery the non-persisted
+  // path uses, with only its header written (`wx`, never clobbering) so the
+  // mount and the record both have a real file. The switch is silent: no
+  // card, no transition entry, no rename — bookkeeping this flow did not earn.
+  if (sessionEmpty) {
+    if (!SM || typeof SM.create !== "function") {
+      return failAfterCopy(
+        "worktree warp is unavailable here: the host SessionManager has no create",
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false },
+      );
+    }
+    let emptyFile = null;
+    try {
+      const allocated = SM.create(targetCwd, sessionDir);
+      const allocatedFile = allocated && typeof allocated.getSessionFile === "function" ? allocated.getSessionFile() : undefined;
+      if (typeof allocatedFile !== "string" || allocatedFile.length === 0) {
+        throw new Error("the host allocated no session file for the target");
+      }
+      const header = typeof allocated.getHeader === "function" ? allocated.getHeader() : null;
+      if (!header) throw new Error("the allocated session has no header");
+      // The file is the header alone: there is no entry to carry, and a file
+      // naming the target cwd is what makes the mount and the fresh point
+      // real. `wx` never clobbers an existing file.
+      fs.writeFileSync(allocatedFile, `${JSON.stringify(header)}\n`, { flag: "wx" });
+      emptyFile = allocatedFile;
+    } catch (err) {
+      return failAfterCopy(
+        `worktree warp: could not change this session's path to ${targetCwd}: ${(err && err.message) || err}`,
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false },
+      );
+    }
+    let changed;
+    try {
+      changed = await ctx.switchSession(emptyFile, { withSession: warpSilentWithSession });
+    } catch (err) {
+      return failAfterCopy(
+        `worktree warp: the session switch to ${targetCwd} failed: ${(err && err.message) || err}; the new session file was kept at ${emptyFile}`,
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false },
+      );
+    }
+    if (changed && changed.cancelled === true) {
+      try {
+        fs.unlinkSync(emptyFile);
+      } catch {
+        // Best effort: the report below is what matters.
+      }
+      return failAfterCopy(
+        `worktree warp: ${name} cancelled (the session stays in ${fromCwd}; the new session file was removed)`,
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: true },
+      );
+    }
+    // Recording is unchanged: both sides are recorded at their own points, so
+    // a later warp finds this destination session again (S2: warping back
+    // from an empty session is the same empty case).
+    try {
+      recordBothSides(
+        targetCwd, emptyFile, warpFreshPoint(emptyFile),
+        sourceIdentity, currentFile, currentPoint,
+      );
+    } catch {
+      // Best effort: the warp already switched.
+    }
+    emitOsc7(options.oscStream || process.stdout, targetCwd);
+    return {
+      text: warpEmptyText(name, targetCwd),
+      details: {
+        name: displayName, path: targetCwd, branch: displayBranch, kind: resolved.kind,
+        alreadyThere: false, cancelled: false, emptySession: true, ...handoffCopyDetails(),
+      },
+    };
+  }
   if (!SM || typeof SM.forkFrom !== "function") {
     return failAfterCopy(
       "worktree warp is unavailable here: the host SessionManager has no forkFrom",
@@ -7528,6 +7652,65 @@ function registerIssuesCommand(pi) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// `/codegraph-hook`, `/codegraph-init`, `/codegraph-sync` (T5 S9): the sync
+// hook's switch and the two on-demand CLI runs. The bodies live in
+// lib/codegraph-commands.js so they are testable without a host; this file only
+// registers them and hands their one-line result to the session UI.
+//
+// GATED REGISTRATION: the three commands do not exist at all in a session whose
+// gate says the `codegraph` CLI is absent, so they never appear in that
+// session's command list. The gate caches its answer per process (S3), so
+// asking at registration time costs one PATH probe for the whole session.
+function codegraphCommandsAvailable() {
+  try {
+    return libRequire("codegraph-session.js").hasCodegraph(process.env) === true;
+  } catch {
+    return false;
+  }
+}
+
+function registerCodegraphCommands(pi) {
+  if (typeof pi?.registerCommand !== "function") return;
+  if (!codegraphCommandsAvailable()) return;
+  const render = (ctx, result) => {
+    const notify = ctx && ctx.ui ? ctx.ui.notify : undefined;
+    if (typeof notify === "function") notify(result.text, result.level);
+    return result;
+  };
+  // A command never throws into the host: the lib returns a failure line
+  // instead of rejecting, and anything unforeseen is swallowed here.
+  const run = async (ctx, work) => {
+    try {
+      render(ctx, await work());
+    } catch {
+      // Nothing to report that the lib did not already describe.
+    }
+  };
+  pi.registerCommand("codegraph-hook", {
+    description: "Turn the automatic edit/write CodeGraph sync on or off: on, off, status (no argument toggles)",
+    handler: async (args, ctx) => {
+      await run(ctx, () => libRequire("codegraph-commands.js").codegraphHook(args));
+    },
+  });
+  pi.registerCommand("codegraph-init", {
+    description: "Initialize a CodeGraph index in this session's checkout: codegraph init .",
+    handler: async (args, ctx) => {
+      await run(ctx, () => libRequire("codegraph-commands.js").codegraphInit(args, ctx, {
+        run: libRunner(libRequire("worktree-git.js")),
+      }));
+    },
+  });
+  pi.registerCommand("codegraph-sync", {
+    description: "Sync this session's checkout CodeGraph index: codegraph sync .",
+    handler: async (args, ctx) => {
+      await run(ctx, () => libRequire("codegraph-commands.js").codegraphSync(args, ctx, {
+        run: libRunner(libRequire("worktree-git.js")),
+      }));
+    },
+  });
+}
+
 export default function (pi) {
   // A TOOL context has no session control, so `worktree_warp` queues the
   // `/warp` COMMAND through this handle (`sendUserMessage` with
@@ -7537,6 +7720,7 @@ export default function (pi) {
   registerWarpCommand(pi);
   registerOddCommand(pi);
   registerIssuesCommand(pi);
+  registerCodegraphCommands(pi);
   pi.registerTool(worktreeCreateTool);
   pi.registerTool(worktreeListTool);
   pi.registerTool(worktreeCloseTool);
@@ -7560,6 +7744,30 @@ export default function (pi) {
   });
   pi.on("tool_call", (event, ctx) => handleWorktreeOddEvent(event, ctx, pi));
   pi.on("tool_result", (event, ctx) => handleWorktreeOddEvent(event, ctx, pi, true));
+  // S1/S3: a successful edit or write asks for ONE background `codegraph sync`
+  // of that file's checkout. The call is fire-and-forget — never awaited, its
+  // decision never reaches the tool result, and a failure here is swallowed
+  // instead of surfacing as a broken edit.
+  pi.on("tool_result", (event) => {
+    try {
+      if (!event || (event.toolName !== "edit" && event.toolName !== "write")) return;
+      if (event.isError) return;
+      const filePath = event.input && event.input.path;
+      if (typeof filePath !== "string" || filePath.length === 0) return;
+      libRequire("codegraph-session.js").scheduleSync(filePath);
+    } catch {
+      // Index freshness is best effort and never touches the tool result.
+    }
+  });
+  // S7: the ODD worktree rules ride the prompt options, appended after the
+  // harness's own text. Sync mutation, so the host reads the final string.
+  pi.on("before_agent_start", (event) => {
+    try {
+      libRequire("odd-worktrees-prompt.js").appendOddWorktreesSection(event);
+    } catch {
+      // The prompt block is best effort.
+    }
+  });
   // Register every live checkout the registry does not own yet. Dispatched here
   // and awaited by the barrier below: the host runs session_start handlers one
   // at a time, so awaiting the scan inside this handler would put the session's

package/lib/codegraph-commands.js

@@ -0,0 +1,165 @@
+'use strict';
+// The three CodeGraph session commands' bodies (S9): `/codegraph-hook`,
+// `/codegraph-init` and `/codegraph-sync`.
+//
+// They are plain functions returning a render-ready result — `{ok, level,
+// text}` — so the extension only has to hand the line to `ctx.ui.notify`. The
+// registration itself is the extension's job and is gated on the session gate,
+// so a session without the CLI never lists these commands.
+//
+// `/codegraph-hook` flips the in-memory, process-wide switch owned by
+// `codegraph-session.js`: nothing is written to user configuration, and the
+// environment (`CODEGRAPH_HOOK=0`) is only the starting state.
+//
+// `init` and `sync` run the real CLI once, at the session's current directory,
+// through the injected `run` seam. The reported line is the child's real
+// outcome: a non-zero (or unstartable) child is a failure, and no path throws
+// into the command handler.
+
+const { isHookEnabled, setHookEnabled } = require('./codegraph-session.js');
+
+const CODEGRAPH_BIN = 'codegraph';
+const COMMANDS = { init: 'codegraph init', sync: 'codegraph sync' };
+
+function pick(deps, name, fallback) {
+  return deps && typeof deps[name] === 'function' ? deps[name] : fallback;
+}
+
+// The convention every other lib helper uses for its runner;
+// `runArgvAsync` resolves (never rejects) with `{status, stdout, stderr, error}`.
+function defaultRun(bin, args, cwd) {
+  return require('./worktree-git.js').runArgvAsync(bin, args, { cwd });
+}
+
+function sessionCwd(ctx) {
+  const cwd = ctx && ctx.cwd;
+  return typeof cwd === 'string' && cwd.length > 0 ? cwd : process.cwd();
+}
+
+// One line of child output, so a multi-line stack never becomes the message.
+function firstLine(text) {
+  const raw = String(text === undefined || text === null ? '' : text);
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0) return trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed;
+  }
+  return '';
+}
+
+function hookState() {
+  return isHookEnabled() ? 'enabled' : 'disabled';
+}
+
+// `/codegraph-hook` — no argument toggles; `on` and `off` set the state
+// explicitly; `status` only reports it.
+function codegraphHook(rawArgs) {
+  const raw = String(rawArgs === undefined || rawArgs === null ? '' : rawArgs).trim().toLowerCase();
+  if (raw === '' || raw === 'on' || raw === 'off') setHookEnabled(raw === '' ? !isHookEnabled() : raw === 'on');
+  else if (raw !== 'status') {
+    return { ok: false, level: 'error', text: `codegraph hook: unknown option "${raw}". Use on, off or status.` };
+  }
+  return { ok: true, level: 'info', text: `codegraph hook: ${hookState()}` };
+}
+
+// The CLI is chatty and decorative (a box around every line, ANSI colours, and
+// glyphs that change between releases), so the report is built from the plain
+// text it puts on stdout and stderr rather than from the exit status alone. The
+// captured shapes this reads:
+//
+//   init, fresh      "Initialized in <path>" / "Indexed N files" / "N nodes, M edges in Tms"
+//   init, indexed    "Already initialized in <path>" / "Use \"codegraph index\" to re-index ..."
+//   sync, clean      "Already up to date"
+//   sync, changed    "Synced N changed files" / "Modified: N — M nodes in Tms"
+//   sync, no index   "CodeGraph not initialized in <path>" (stderr, exit 1)
+const ANSI = /\u001b\[[0-9;]*[a-zA-Z]/g;
+
+function plain(text) {
+  return String(text === undefined || text === null ? '' : text).replace(ANSI, '');
+}
+
+function count(value, noun) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return '';
+  return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}
+
+function summarize(label, out) {
+  const text = `${plain(out.stdout)}\n${plain(out.stderr)}`;
+  const path = (match) => (match && match[1] ? match[1].trim() : '');
+
+  const notIndexed = text.match(/not initialized in\s+(\S+)/i);
+  if (notIndexed) {
+    return { ok: false, level: 'error', text: `${label}: no index in this checkout — run /codegraph-init first` };
+  }
+  const already = text.match(/already initialized in\s+(\S+)/i);
+  if (already) {
+    return { ok: true, level: 'info', text: `${label}: already initialized at ${path(already)} — nothing to do, use /codegraph-sync to update` };
+  }
+  const upToDate = /already up to date/i.test(text);
+  if (upToDate) {
+    return { ok: true, level: 'info', text: `${label}: already up to date — nothing to sync` };
+  }
+  const synced = text.match(/synced\s+(\d+)\s+changed\s+files?/i);
+  if (synced) {
+    const nodes = text.match(/(\d+)\s+nodes?/i);
+    const counts = [count(synced[1], 'changed file'), nodes ? count(nodes[1], 'node') : ''].filter(Boolean).join(' — ');
+    return { ok: true, level: 'info', text: `${label}: synced ${counts}` };
+  }
+  const initialized = text.match(/initialized in\s+(\S+)/i);
+  if (initialized) {
+    const files = text.match(/indexed\s+(\d+)\s+files?/i);
+    const nodes = text.match(/(\d+)\s+nodes?/i);
+    const edges = text.match(/(\d+)\s+edges?/i);
+    const sorted = [
+      files ? count(files[1], 'file') : '',
+      nodes ? count(nodes[1], 'node') : '',
+      edges ? count(edges[1], 'edge') : '',
+    ].filter(Boolean).join(', ');
+    return { ok: true, level: 'info', text: `${label}: initialized ${path(initialized)}${sorted ? ` — ${sorted}` : ''}` };
+  }
+  return null;
+}
+
+async function runStep(verb, rawArgs, ctx, deps) {
+  const label = COMMANDS[verb];
+  const raw = String(rawArgs === undefined || rawArgs === null ? '' : rawArgs).trim();
+  if (raw !== '') return { ok: false, level: 'error', text: `${label}: takes no argument.` };
+
+  const cwd = sessionCwd(ctx);
+  let outcome;
+  try {
+    outcome = await pick(deps, 'run', defaultRun)(CODEGRAPH_BIN, [verb, '.'], cwd);
+  } catch (err) {
+    return { ok: false, level: 'error', text: `${label}: failed — ${firstLine((err && err.message) || String(err))}` };
+  }
+  const out = outcome && typeof outcome === 'object' ? outcome : {};
+  const summary = summarize(label, out);
+  // The CLI answers `sync` in a checkout with no index on stderr with exit 1,
+  // so the recognised message decides before the exit status does.
+  if (summary && (summary.ok || /no index/.test(summary.text))) return summary;
+  if (out.error) {
+    return { ok: false, level: 'error', text: `${label}: failed — ${firstLine(out.error) || 'unknown error'}` };
+  }
+  if (out.status !== 0) {
+    const exit = Number.isInteger(out.status) ? out.status : 'unknown';
+    const detail = firstLine(plain(out.stderr)) || firstLine(plain(out.stdout)) || 'no output';
+    return { ok: false, level: 'error', text: `${label}: exit ${exit} — ${detail}` };
+  }
+  return summary || { ok: true, level: 'info', text: `${label}: done` };
+}
+
+// `/codegraph-init` and `/codegraph-sync` — one awaited CLI run at the session's
+// current directory, reported by its real exit status.
+function codegraphInit(rawArgs, ctx, deps) {
+  return runStep('init', rawArgs, ctx, deps);
+}
+
+function codegraphSync(rawArgs, ctx, deps) {
+  return runStep('sync', rawArgs, ctx, deps);
+}
+
+module.exports = {
+  codegraphHook,
+  codegraphInit,
+  codegraphSync,
+};