pi-plans 0.2.0 → 0.3.1

package/references/state-and-config.md

@@ -25,8 +25,9 @@ Bare repositories are refused with a clear error. A missing `git` executable is
 ```text
 <git-common-dir>/pi_plans/
   config.json
+  pi-vcc-config.json
   active.json
-  runs/
+  runs/            # note: the refs root is a sibling — .git/pi-plans/refs (hyphenated), not under pi_plans/
     <run-id>/
       run.json
       decisions.jsonl
@@ -36,7 +37,7 @@ Bare repositories are refused with a clear error. A missing `git` executable is
   cache/
 ```
 
-`config.json` is stable workspace preference state. `active.json` and `runs/` are run state. Large external references stay outside the repository by default under `~/.cache/pi-plans/refs/`, with metadata recorded in the run state and public artifacts.
+`config.json` is stable workspace preference state. `pi-vcc-config.json` is the repo-private compaction config used only by pi-plans' VCC-style compact hook. `active.json` and `runs/` are run state. Reference downloads go to the configured `refs_root` (asked once per workspace when unset; the recommended `.git/pi-plans/refs/` sits inside the git dir so git never tracks it), with metadata recorded in the run state and public artifacts.
 
 ## Config Schema
 
@@ -60,7 +61,10 @@ The default config is:
   },
   "artifact_root": "./docs/pi-plans",
   "artifact_root_source": "unset",
-  "artifact_root_updated_at": null
+  "artifact_root_updated_at": null,
+  "refs_root": null,
+  "refs_root_source": "unset",
+  "refs_root_updated_at": null
 }
 ```
 
@@ -74,8 +78,33 @@ Rules:
 - `artifact_root` is relative to the target workspace unless absolute.
 - `artifact_root_source` is `user`, `auto`, or `unset`.
 - `artifact_root_updated_at` is the selection timestamp or `null` before confirmation.
+- `refs_root` is where plan-with-refs downloads references, relative to the target workspace unless absolute, or `null` before selection; `refs_root_source` is `user`, `auto`, or `unset`; `refs_root_updated_at` is the selection timestamp or `null`.
 - There is intentionally no `effort` field: subagents inherit the dispatching session's model and thinking level unless an exact selector is stored. The real lever is the main session's thinking level at refine time.
 
+## VCC Compact Config
+
+`pi-vcc-config.json` is scaffolded under the resolved `<git-common-dir>/pi_plans/` state root when an active planning or execution compaction hook first needs it. It is independent from `config.json` so planning preferences, run state, and compact policy can evolve separately.
+
+Default values:
+
+```json
+{
+  "overrideDefaultCompaction": true,
+  "smartKeepTail": true,
+  "continueAfterThresholdCompact": true,
+  "debug": false
+}
+```
+
+Rules:
+
+- Only the repo-private file is read. Upstream global pi-vcc config such as `~/.pi/agent/pi-vcc-config.json` and `PI_VCC_CONFIG_PATH` are ignored.
+- Missing files are created with defaults; valid files keep user values and receive missing default keys; invalid JSON is never clobbered and the runtime falls back to defaults for that read.
+- `overrideDefaultCompaction:false` returns ordinary Pi manual/threshold/overflow compactions to Pi core. Explicit pi-plans internal compact hints can still use the VCC path.
+- `smartKeepTail:true` starts from the requested/default keep count and may retain more recent user turns when the retained tail remains within the safe token budget. Explicit `keep:N` is honored.
+- `continueAfterThresholdCompact:true` permits one hidden continuation after successful threshold/overflow compaction only on Pi versions that still need extension-driven resume behavior. Plain manual `/compact` never auto-continues, and `/compact <text>` sends the text once as the follow-up prompt.
+- `debug:false` writes no diagnostics; `debug:true` writes a best-effort `/tmp/pi-vcc-debug.json` snapshot for local troubleshooting.
+
 ## Language Setting
 
 Before the first product planning question, check the persisted config (`plans` action `show`). If `language.tag` is missing or invalid, ask exactly one `ask_choice` question:
@@ -88,7 +117,14 @@ Before the first product planning question, check the persisted config (`plans`
 
 Persist with `plans` (`set-language`, `languageSource: "user"`). Use the selected language for visible questions, choices, review summaries, criticizer questions, and Markdown artifacts. Keep IDs, file paths, command names, JSON keys, and protocol labels stable in English.
 
-## Planning Docs Location
+## Code Graph Enabled
+
+`graph_enabled` (`boolean | null`) records whether the workspace wants graph-aware read/write/edit wrappers and `code_graph` mutations for indexed source files. `null` means the question was never asked: the first `plans` `init`/`show` in a workspace returns a `hint` instructing the agent to ask the user once via `ask_choice` (recommended: yes) and persist with the `plans` tool (`set-graph-enabled`, `enabled: true|false`). This question does not count against the planning-question limit. `/enable-graph` and `/disable-graph` toggle it later; disable refuses while graph drift is dirty. When enabled, DB-first staged edits are materialized agent-side via the `code_graph` tool's `apply` action (same planning/accepted gate as `/apply-graph`; refused for read-only refiner subagents via the `PI_PLANS_REFINER` env marker; the result carries per-file counts and a post-apply drift summary and never changes run status).
+
+## `/config-pi-plans`
+
+`/config-pi-plans` is an interactive workspace configuration wizard. It re-asks the workspace language, planning docs root, refs root, code graph toggle, reviewer mode/model, and criticizer mode/model, then writes the chosen defaults back to `.git/pi_plans/config.json`. When code graph is enabled, the extension also overrides built-in `read`/`write`/`edit` for indexed source files so graph-backed source reads and DB-first edits happen automatically. Model pickers can reuse the current session model, any available selector surfaced by `ctx.scopedModels` or the model registry, or a manually entered exact `provider/model` string. If a run is already active, only the workspace defaults change; the active run's `artifact_dir` and `language_tag` stay unchanged.
+
 
 Before the first product planning question, check the persisted config again. If `artifact_root_source` is missing or `unset`, ask exactly one `ask_choice` question:
 
@@ -99,6 +135,15 @@ Before the first product planning question, check the persisted config again. If
 
 Persist with `plans` (`set-artifact-root`, `artifactRoot: <selected path>`, `artifactRootSource: "user"` or `"auto"`). Use the selected path for the run's artifact directory root. This question does not count against the planning-question limit.
 
+Before downloading any reference in a plan-with-refs flow, check the persisted config. If `refs_root_source` is missing or `unset`, ask exactly one `ask_choice` question:
+
+1. `.git/pi-plans/refs` — recommended; inside the git dir so git never tracks the downloads.
+2. `./refs/` — inside the worktree; the planning write guard allows writes under the configured refs root.
+3. `~/.cache/pi-plans/refs/` — outside the repository; matches the historical default.
+4. `Other` / `Auto-complete` — select the recommended path.
+
+Persist with `plans` (`set-refs-root`, `refsRoot: <selected path>`, `refsRootSource: "user"` or `"auto"`). Download references under this root. This question does not count against the planning-question limit.
+
 
 Before running a `refine` round, read the role setting from the persisted config.
 
@@ -128,10 +173,12 @@ When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` s
 
 The main agent consolidates the results, records dispositions, revises the plan, and asks the next merged accept/execute question — all in the same turn.
 
+The `analyze_refs` tool (plan-with-refs) uses the same spawning machinery with the **reviewer** role's gates (`mode` must be `delegated-subagent`; a confirmed `current-session` reviewer is refused with guidance to switch, since analysis is spawn-only) and the reviewer's model selector. Each downloaded reference gets one independent read-only subagent whose system prompt comes from `agents/ref-analyst.md` and whose working directory is that reference's own directory; lanes never get `code_graph`. Lanes run in sequential batches of at most 3 under a standalone overlay titled `Refs`; each batch's controller opens and closes exactly like a single refine round. Successful spawns are recorded best-effort in `subagents.jsonl` with role `ref-analyst` (skipped when no active run exists, e.g. adhoc calls). The structured per-reference sections come back as the tool result; the main agent owns `REF_ANALYSIS.md` and fills `coverage`/`gaps` in `refs.jsonl` via `plans` (`record-ref`).
+
 ## Run State
 
 One run directory per planning request: `<git-common-dir>/pi_plans/runs/<YYYYMMDDTHHMMSSZ-topic>/` (second-precision; `-2`, `-3` suffixes on collision).
 
 `run.json` includes: run ID; skill name; original request; target workspace; artifact directory; language tag; status (`planning` → `accepted` → `executing` → `done`, with `stopped`/`abandoned` as exits); timestamps.
 
-`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer spawns. `refs.jsonl` records reference metadata via `plans` (`record-ref`).
+`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer/ref-analyst spawns. `refs.jsonl` records reference metadata via `plans` (`record-ref`).

package/scripts/validate.ts

@@ -21,12 +21,17 @@ const REQUIRED_TOOL_FILES = [
 	"tools/plans.ts",
 	"tools/ask-choice.ts",
 	"tools/refine.ts",
+	"tools/analyze-refs.ts",
 	"tools/execute-plan.ts",
+	"tools/code-graph.ts",
 	"src/state.ts",
 	"src/guard.ts",
 	"src/plan.ts",
 	"src/subagent.ts",
 	"src/exec.ts",
+	"src/code-graph/runtime.ts",
+	"src/code-graph/schema.ts",
+	"src/code-graph/store.ts",
 ];
 
 const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

package/skills/plan-with-refs/SKILL.md

@@ -16,15 +16,15 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 1. Inspect the target Git repo read-only before external research so search terms match the actual codebase and constraints.
 2. Create the `.git/pi_plans` run state and planning artifact directory once the topic is clear (`plans` action `start-run`).
 3. Search proactively for related projects, articles, papers, docs, and prior art. Prefer a websearch skill when installed; otherwise use bash tools such as `curl` or `gh` when already available.
-4. Download or clone at least 3 credible references before writing `PLAN_v1.md`; store large downloads outside the target repo under `~/.cache/pi-plans/refs/<repo-slug>/<topic>/`. Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
+4. Before the first download, check `refs_root` in `.git/pi_plans/config.json` (`plans` action `show`). If it is unset, ask exactly one `ask_choice` question — recommended `.git/pi-plans/refs/` (inside the git dir, never tracked), second `./refs/`, third `~/.cache/pi-plans/refs/` — and persist with `plans` (`set-refs-root`); this question does not count against the planning-question limit. Then download or clone at least 3 credible references before writing `PLAN_v1.md`, under the configured refs root (create per-ref subdirectories). Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
 5. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and in the run's `refs.jsonl` (via `plans` action `record-ref`): title, URL, kind, retrieval method, date accessed, local path, coverage, and evidence gaps.
-6. For every reference, produce a structured analysis artifact (manual structured read recorded in `REF_ANALYSIS.md`) before asking adoption questions.
+6. For every reference, run the `analyze_refs` tool (required path — it replaces manual structured reads): one independent read-only subagent per reference deep-reads it and returns structured sections (Overview / Key Mechanisms And Design Tradeoffs / Adoptable Ideas For The Target Repo / Pitfalls And Anti-Patterns / Evidence Citations / Coverage / Evidence Gaps). Paste each analysis into `REF_ANALYSIS.md` and fill `coverage` and `gaps` in `refs.jsonl` via `plans` (`record-ref`) before asking adoption questions.
 7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both).
 8. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum. `Auto-complete` cannot grant this waiver.
 9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round, then a criticizer round), no refinement limit, at most five high-priority comments or questions per refinement round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 
 ## REF_ANALYSIS.md
 
-Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; local download paths; structured analysis summaries; adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.
+Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; configured refs root and local download paths; the per-reference `analyze_refs` structured analyses (pasted verbatim, one section per reference); adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.
 
 Reference ideas are not eligible for `PLAN_v1.md` until their adoption question answers are recorded.

package/src/code-graph/commands.ts

@@ -0,0 +1,483 @@
+/**
+ * Slash-command handlers for /init-graph, /update-graph, and /apply-graph.
+ * They defer loading the runtime and SQLite until invoked so other pi-plans tools stay usable
+ * even when the graph feature is unavailable.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	loadGraphRuntime,
+	describeRuntimeIssues,
+	type RuntimeStatus,
+} from "./runtime.ts";
+import { resolveCanonicalWorktree } from "./paths.ts";
+import { Store } from "./store.ts";
+import { runIndex } from "./indexer.ts";
+import { makeBackend } from "./parsers/javascript.ts";
+import { PythonBackend } from "./parsers/python.ts";
+import type { ParserBackend } from "./parser.ts";
+import type { Language } from "./types.ts";
+import { materialize, type MaterializeReport } from "./materialize.ts";
+import { generateSummaries, type CompletionHandle, type SummaryReport } from "./summary.ts";
+import { readActive, getRun, setRunStatus } from "../state.ts";
+
+interface CommandContext {
+	cwd: string;
+	hasUI: boolean;
+	ui: {
+		notify: (message: string, kind?: "info" | "warning" | "error") => void;
+		confirm: (title: string, body: string) => Promise<boolean>;
+	};
+	modelRegistry?: {
+		find?: (provider: string, id: string) => unknown;
+		complete?: (
+			model: unknown,
+			context: { messages: Array<{ role: "user"; content: string }> },
+			options: Record<string, unknown>,
+		) => Promise<{ content: Array<{ type: "text"; text: string }>; stopReason?: string }>;
+		hasConfiguredAuth?: (model: unknown) => boolean;
+	};
+	model?: unknown;
+	thinkingLevel?: string;
+}
+
+async function buildParsers(runtime: Awaited<ReturnType<typeof loadGraphRuntime>>["runtime"]): Promise<Record<Language, ParserBackend>> {
+	const ParserCtor = runtime.parser.Parser as unknown as new () => {
+		parse(input: string | Buffer): unknown;
+		setLanguage(language: unknown): void;
+	};
+	return {
+		javascript: makeBackend("javascript", ParserCtor, runtime.parser.javascript),
+		typescript: makeBackend("typescript", ParserCtor, runtime.parser.typescript),
+		tsx: makeBackend("tsx", ParserCtor, runtime.parser.tsx),
+		python: new PythonBackend(ParserCtor, runtime.parser.python),
+	};
+}
+
+interface Bootstrap {
+	store: Store;
+	paths: ReturnType<typeof resolveCanonicalWorktree>;
+	parsers: Record<Language, ParserBackend>;
+	runtimeStatus: RuntimeStatus;
+}
+
+async function bootstrap(ctx: CommandContext, opts: { reindex?: boolean }): Promise<Bootstrap | null> {
+	const paths = resolveCanonicalWorktree(ctx.cwd);
+	const { runtime, status } = await loadGraphRuntime();
+	if (status.issues.length > 0 && !status.sqliteAvailable && !status.parserAvailable) {
+		ctx.ui.notify(`code-graph unavailable: ${describeRuntimeIssues(status).join("; ")}`, "error");
+		return null;
+	}
+	const store = new Store(
+		{ dbPath: paths.codeGraphDb, worktreeRoot: paths.worktreeRoot, gitCommonDir: paths.gitCommonDir },
+		runtime.sqlite,
+	);
+	try {
+		store.checkWorktree(paths.worktreeRoot, paths.gitCommonDir);
+	} catch (error) {
+		store.close();
+		ctx.ui.notify(`code-graph: ${(error as Error).message}`, "error");
+		return null;
+	}
+	const parsers = await buildParsers(runtime);
+	void opts;
+	return { store, paths, parsers, runtimeStatus: status };
+}
+
+function activePlanningRun(workdir: string): ActiveInfo | null {
+	const active = readActive(workdir);
+	if (!active) return null;
+	const run = getRun(workdir, active.run_id);
+	if (!run) return null;
+	return run.status === "planning" || run.status === "accepted" ? active : null;
+}
+
+function denyActivePlanning(ctx: CommandContext): boolean {
+	return activePlanningRun(ctx.cwd) !== null;
+}
+
+export async function initGraphCommand(args: string, ctx: CommandContext): Promise<void> {
+	const flags = parseCommandArgs(args).flags;
+	const preflightPaths = resolveCanonicalWorktree(ctx.cwd);
+	const preferRebuild = flags.has("reindex") || !ctx.hasUI;
+	if (fs.existsSync(preflightPaths.codeGraphDb) && !preferRebuild) {
+		const rebuild = await ctx.ui.confirm(
+			"code-graph DB already exists",
+			`${preflightPaths.codeGraphDb}\n\nRebuild the graph with the current /init-graph flow, or sync changed paths via /update-graph?\n\nYes = rebuild the full graph\nNo = sync changed paths only`,
+		);
+		if (!rebuild) {
+			const bootstrapResult = await bootstrap(ctx, {});
+			if (!bootstrapResult) return;
+			const { store, paths, parsers } = bootstrapResult;
+			try {
+				await runChangedPathSync(args, ctx, store, paths, parsers);
+			} catch (error) {
+				ctx.ui.notify(`code-graph update failed: ${(error as Error).message}`, "error");
+			} finally {
+				store.close();
+			}
+			return;
+		}
+	}
+	const bootstrapResult = await bootstrap(ctx, { reindex: flags.has("reindex") });
+	if (!bootstrapResult) return;
+	const { store, paths, parsers, runtimeStatus } = bootstrapResult;
+	try {
+		// Pre-index chore commit: snapshot any uncommitted work so the DB indexes
+		// a recoverable state (--no-commit skips this).
+		let choreCommit = "";
+		if (!flags.has("no-commit")) {
+			choreCommit = gitAddAllAndCommit(paths.worktreeRoot, "chore(code-graph): pre-init snapshot");
+			if (choreCommit) ctx.ui.notify(`code-graph pre-init commit: ${choreCommit.slice(0, 12)}`, "info");
+		}
+		const report = await runIndex({
+			store,
+			worktreeRoot: paths.worktreeRoot,
+			parsers,
+			reindex: flags.has("reindex"),
+		});
+		ctx.ui.notify(
+			`code-graph indexed ${report.functionsIndexed} function(s) in ${report.filesScanned} file(s) — ${report.edgesResolved} resolved, ${report.edgesUnresolved} unresolved`,
+			"info",
+		);
+		if (!flags.has("no-summary") && ctx.hasUI && ctx.modelRegistry?.complete && ctx.model) {
+			const handle: CompletionHandle = {
+				complete: async (request) =>
+					await ctx.modelRegistry!.complete!(ctx.model, { messages: request.messages }, {}),
+				model: () => ctx.model as { id?: string; provider?: string; api?: string; reasoning?: boolean } | undefined,
+				thinkingLevel: () => ctx.thinkingLevel,
+				hasUI: ctx.hasUI,
+				confirm: ctx.ui.confirm,
+				notify: ctx.ui.notify,
+			};
+			try {
+				const summary: SummaryReport = await generateSummaries({ store, ctx: handle, skipConsent: flags.has("consent") });
+				ctx.ui.notify(
+					`code-graph summaries: ${summary.ok} ok, ${summary.failed} failed, ${summary.declined} declined`,
+					summary.failed > 0 ? "warning" : "info",
+				);
+			} catch (error) {
+				ctx.ui.notify(`code-graph summary failed: ${(error as Error).message}`, "warning");
+			}
+		}
+		ctx.ui.notify(
+			`code-graph db: ${paths.codeGraphDb} (Node ${runtimeStatus.nodeVersion}${runtimeStatus.hasExperimentalSqliteFlag ? " +sqlite-flag" : ""})`,
+			"info",
+		);
+		// Post-index snapshot: anchor drift checks to this commit + status.
+		const head = gitHead(paths.worktreeRoot) || choreCommit;
+		const uncommitted = gitStatusPorcelain(paths.worktreeRoot).map((entry) => entry.path);
+		store.upsertSnapshot(head, uncommitted);
+		ctx.ui.notify(`code-graph snapshot: ${head.slice(0, 12) || "(no commits)"} · ${uncommitted.length} uncommitted path(s)`, "info");
+	} catch (error) {
+		ctx.ui.notify(`code-graph index failed: ${(error as Error).message}`, "error");
+	} finally {
+		store.close();
+	}
+}
+
+export interface ApplyGraphCoreResult {
+	refused?: string;
+	failed?: string;
+	report?: MaterializeReport;
+	drift?: { pending: number; ok: boolean } | null;
+}
+
+/**
+ * Shared core for /apply-graph and the code_graph "apply" tool action:
+ * gate (planning/accepted refusal) → bootstrap → materialize → drift summary.
+ * No notifications and no run-status side effects; callers own presentation
+ * and lifecycle transitions.
+ */
+export async function applyGraphCore(workdir: string, opts: { force?: boolean } = {}): Promise<ApplyGraphCoreResult> {
+	const planned = activePlanningRun(workdir);
+	if (planned) {
+		return { refused: `code-graph apply refused: a planning run is currently planning or accepted (run ${planned.run_id}).` };
+	}
+	let bootstrapFailure = "";
+	const bootstrapResult = await bootstrap(
+		{ cwd: workdir, hasUI: false, ui: { notify: (message: string) => { bootstrapFailure ||= message; }, confirm: async () => false } } as never,
+		{},
+	);
+	if (!bootstrapResult) return { failed: bootstrapFailure || "code-graph runtime unavailable" };
+	const { store, paths } = bootstrapResult;
+	try {
+		const report = materialize({ store, worktreeRoot: paths.worktreeRoot, force: opts.force ?? false });
+		let drift: ApplyGraphCoreResult["drift"] = null;
+		try {
+			const d = computeDrift(store, paths.worktreeRoot);
+			drift = { pending: d.pending.length, ok: d.ok };
+		} catch {
+			drift = null; // drift summary is best-effort; materialization already succeeded
+		}
+		return { report, drift };
+	} catch (error) {
+		return { failed: (error as Error).message };
+	} finally {
+		store.close();
+	}
+}
+
+export async function applyGraphCommand(args: string, ctx: CommandContext): Promise<void> {
+	if (denyActivePlanning(ctx)) {
+		ctx.ui.notify("code-graph apply refused: a planning run is currently planning or accepted.", "error");
+		return;
+	}
+	const flags = parseCommandArgs(args).flags;
+	const core = await applyGraphCore(ctx.cwd, { force: flags.has("force") });
+	if (core.refused) {
+		ctx.ui.notify(core.refused, "error");
+		return;
+	}
+	if (core.failed || !core.report) {
+		ctx.ui.notify(`code-graph apply failed: ${core.failed ?? "unknown error"}`, "error");
+		return;
+	}
+	const report = core.report;
+	const stale = report.files.filter((file) => file.status === "stale").length;
+	const errors = report.files.filter((file) => file.status === "error").length;
+	const ok = report.files.filter((file) => file.status === "ok").length;
+	const deleted = report.files.filter((file) => file.status === "deleted").length;
+	const skipped = report.files.filter((file) => file.status === "skipped-missing").length;
+	ctx.ui.notify(
+		`code-graph apply: ${ok} ok, ${deleted} deleted, ${stale} stale, ${skipped} skipped-missing, ${errors} error`,
+		errors > 0 ? "error" : "info",
+	);
+	const active = readActive(ctx.cwd);
+	if (active) setRunStatus(ctx.cwd, active.run_id, "executing");
+}
+
+export async function graphStatusCommand(_args: string, ctx: CommandContext): Promise<void> {
+	const bootstrapResult = await bootstrap(ctx, {});
+	if (!bootstrapResult) return;
+	const { store, paths } = bootstrapResult;
+	try {
+		const files = store.read(() => store.db.prepare("SELECT COUNT(*) AS c FROM files").get()) as { c: number };
+		const functions = store.read(() => store.db.prepare("SELECT COUNT(*) AS c FROM functions").get()) as { c: number };
+		const edges = store.read(() => store.db.prepare("SELECT COUNT(*) AS c FROM call_edges").get()) as { c: number };
+		ctx.ui.notify(
+			`code-graph: ${functions.c} functions, ${files.c} files, ${edges.c} edges — ${paths.codeGraphDb}`,
+			"info",
+		);
+	} finally {
+		store.close();
+	}
+}
+
+// ---------------------------------------------------------------------------
+// /update-graph, /graph-drift, /enable-graph, /disable-graph
+// ---------------------------------------------------------------------------
+
+import { gitAddAllAndCommit, gitDiffNameOnly, gitHead, gitStatusPorcelain, parseCommandArgs } from "./git.ts";
+import { isIndexablePath } from "./discovery.ts";
+import { hashText } from "./parser.ts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadConfig, resolveStateRootOrNull, setGraphEnabled } from "../state.ts";
+
+export interface DriftResult {
+	ok: boolean;
+	/** Invariant (a): per-file hash drift, unless pending_kind is set. */
+	hashDrift: Array<{ path: string; kind: "hash-mismatch" | "pending-update" | "pending-delete" }>;
+	/** Invariant (b): indexable uncommitted paths missing from the DB. */
+	unindexed: string[];
+	/** Invariant (c), informational: snapshot vs current git state. */
+	snapshot: { stale: boolean; headCommit: string; snapshotHead: string; uncommittedAtSnapshot: string[] };
+	pending: Array<{ path: string; kind: string }>;
+	recommendation: string;
+}
+
+/** Normalize a porcelain/git path ("src/a.ts", "a.ts") to the DB key form ("./a.ts"). */
+export function toDbKey(porcelainPath: string): string {
+	return porcelainPath.includes("/") ? porcelainPath : `./${porcelainPath}`;
+}
+
+export function computeDrift(store: Store, worktreeRoot: string): DriftResult {
+	const entries = gitStatusPorcelain(worktreeRoot);
+	const renameOrigPaths = new Set(
+		entries.filter((entry) => entry.origPath !== null).map((entry) => toDbKey(entry.origPath!)),
+	);
+	const porcelainPaths = entries.filter((entry) => !entry.status.includes("D")).map((entry) => toDbKey(entry.path));
+	const indexableChanged = [...new Set([...porcelainPaths, ...renameOrigPaths])].filter(isIndexablePath);
+
+	const filesRows = store.read(() =>
+		store.db.prepare(`SELECT file_dir, file_name, source_hash, pending_kind FROM files`).all(),
+	) as Array<{ file_dir: string; file_name: string; source_hash: string; pending_kind: string | null }>;
+	const byPath = new Map(filesRows.map((row) => [`${row.file_dir}/${row.file_name}`, row]));
+
+	const hashDrift: DriftResult["hashDrift"] = [];
+	const pending: DriftResult["pending"] = [];
+	const unindexed: string[] = [];
+	for (const row of filesRows) {
+		const rel = `${row.file_dir}/${row.file_name}`;
+		if (row.pending_kind === "update") {
+			pending.push({ path: rel, kind: "update" });
+			hashDrift.push({ path: rel, kind: "pending-update" });
+			continue;
+		}
+		if (row.pending_kind === "delete") {
+			pending.push({ path: rel, kind: "delete" });
+			hashDrift.push({ path: rel, kind: "pending-delete" });
+			continue;
+		}
+		const absolute = path.join(worktreeRoot, row.file_dir === "." ? row.file_name : path.join(row.file_dir, row.file_name));
+		let onDisk: string | null = null;
+		try {
+			onDisk = fs.readFileSync(absolute, "utf8");
+		} catch {
+			onDisk = null;
+		}
+		if (onDisk === null) {
+			// Deleted on disk but not marked pending: untracked deletion.
+			hashDrift.push({ path: rel, kind: "hash-mismatch" });
+			continue;
+		}
+		if (hashText(onDisk) !== row.source_hash) {
+			hashDrift.push({ path: rel, kind: "hash-mismatch" });
+		}
+	}
+	for (const changed of indexableChanged) {
+		if (renameOrigPaths.has(changed)) continue; // rename-old: purge is the fix, not reindex
+		if (!byPath.has(changed)) unindexed.push(changed);
+	}
+
+	const snapshot = store.readLatestSnapshot();
+	const head = gitHead(worktreeRoot);
+	const snapshotInfo = {
+		stale: snapshot !== null && snapshot.headCommit !== head,
+		headCommit: head,
+		snapshotHead: snapshot?.headCommit ?? "(none)",
+		uncommittedAtSnapshot: snapshot?.uncommittedPaths ?? [],
+	};
+
+	const needsUpdate = hashDrift.some((item) => item.kind === "hash-mismatch") || unindexed.length > 0;
+	const needsApply = pending.length > 0;
+	const recommendation = needsUpdate
+		? "run /update-graph to reindex changed paths"
+		: needsApply
+			? "run code_graph apply (or /apply-graph) to materialize pending DB edits"
+			: "in sync";
+	return {
+		ok: hashDrift.every((item) => item.kind !== "hash-mismatch") && unindexed.length === 0,
+		hashDrift,
+		unindexed,
+		snapshot: snapshotInfo,
+		pending,
+		recommendation,
+	};
+}
+
+async function runChangedPathSync(
+	args: string,
+	ctx: CommandContext,
+	store: Store,
+	paths: Bootstrap["paths"],
+	parsers: Record<Language, ParserBackend>,
+): Promise<void> {
+	const { flags, values } = parseCommandArgs(args);
+	const entries = gitStatusPorcelain(paths.worktreeRoot);
+	const renameOrigPaths = new Set(
+		entries.filter((entry) => entry.origPath !== null).map((entry) => toDbKey(entry.origPath!)),
+	);
+	const porcelainPaths = entries.map((entry) => toDbKey(entry.path));
+	// --base <commit>: union porcelain with diff-vs-base so pinned-base
+	// changes (possibly already committed) are included.
+	const basePath = values.get("base");
+	const basePaths = basePath
+		? gitDiffNameOnly(paths.worktreeRoot, basePath).map(toDbKey)
+		: [];
+	const candidates = [...new Set([...porcelainPaths, ...renameOrigPaths, ...basePaths])].filter(isIndexablePath);
+	if (candidates.length === 0) {
+		ctx.ui.notify("code-graph update: no changed indexable paths — nothing to do", "info");
+		return;
+	}
+	if (flags.has("dry-run")) {
+		ctx.ui.notify(`code-graph update (dry-run): would reindex ${candidates.length} path(s):\n${candidates.join("\n")}`, "info");
+		return;
+	}
+	const report = await runIndex({ store, worktreeRoot: paths.worktreeRoot, parsers, paths: candidates });
+	ctx.ui.notify(
+		`code-graph update: ${report.reindexedPaths.length} reindexed, ${report.purgedPaths.length} purged, ${report.functionsIndexed} function(s)`,
+		"info",
+	);
+}
+
+export async function updateGraphCommand(args: string, ctx: CommandContext): Promise<void> {
+	const bootstrapResult = await bootstrap(ctx, {});
+	if (!bootstrapResult) return;
+	const { store, paths, parsers } = bootstrapResult;
+	try {
+		await runChangedPathSync(args, ctx, store, paths, parsers);
+	} catch (error) {
+		ctx.ui.notify(`code-graph update failed: ${(error as Error).message}`, "error");
+	} finally {
+		store.close();
+	}
+}
+
+export async function graphDriftCommand(args: string, ctx: CommandContext): Promise<void> {
+	const { flags } = parseCommandArgs(args);
+	const bootstrapResult = await bootstrap(ctx, {});
+	if (!bootstrapResult) return;
+	const { store, paths } = bootstrapResult;
+	try {
+		const drift = computeDrift(store, paths.worktreeRoot);
+		if (flags.has("json")) {
+			const payload = flags.has("commit-aware")
+				? { ...drift, gitStatus: gitStatusPorcelain(paths.worktreeRoot) }
+				: drift;
+			ctx.ui.notify(JSON.stringify(payload, null, 2), "info");
+			return;
+		}
+		const lines: string[] = [];
+		lines.push(`graph drift: ${drift.ok ? "OK" : "DIRTY"} — ${drift.recommendation}`);
+		for (const item of drift.hashDrift) {
+			if (item.kind === "hash-mismatch") lines.push(`  (a) hash mismatch: ${item.path}`);
+			else if (item.kind === "pending-update") lines.push(`  (a) pending apply (update): ${item.path}`);
+			else lines.push(`  (a) pending apply (delete): ${item.path}`);
+		}
+		for (const missing of drift.unindexed) lines.push(`  (b) uncommitted but unindexed: ${missing}`);
+		if (drift.snapshot.stale) {
+			lines.push(`  (c) snapshot stale: recorded ${drift.snapshot.snapshotHead.slice(0, 8)} vs HEAD ${drift.snapshot.headCommit.slice(0, 8)} (run /init-graph after committing to refresh)`);
+		}
+		if (flags.has("commit-aware")) {
+			for (const entry of gitStatusPorcelain(paths.worktreeRoot)) {
+				lines.push(`  (git) ${entry.status} ${entry.path}${entry.origPath ? ` (from ${entry.origPath})` : ""}`);
+			}
+		}
+		ctx.ui.notify(lines.join("\n"), drift.ok ? "info" : "warning");
+	} catch (error) {
+		ctx.ui.notify(`graph drift failed: ${(error as Error).message}`, "error");
+	} finally {
+		store.close();
+	}
+}
+
+export async function enableGraphCommand(_args: string, ctx: CommandContext): Promise<void> {
+	setGraphEnabled(ctx.cwd, true);
+	ctx.ui.notify("code-graph enabled: agents will use graph-aware read/write/edit on indexed source files. Run /init-graph to index.", "info");
+}
+
+export async function disableGraphCommand(_args: string, ctx: CommandContext): Promise<void> {
+	const stateRoot = resolveStateRootOrNull(ctx.cwd);
+	if (stateRoot && loadConfig(stateRoot).graph_enabled === true) {
+		const bootstrapResult = await bootstrap(ctx, {});
+		if (bootstrapResult) {
+			const { store, paths } = bootstrapResult;
+			try {
+				const drift = computeDrift(store, paths.worktreeRoot);
+				if (!drift.ok || drift.pending.length > 0) {
+					ctx.ui.notify(
+						`code-graph disable refused: worktree/DB is dirty (${drift.recommendation}). Fix drift first, then disable.`,
+						"error",
+					);
+					return;
+				}
+			} finally {
+				store.close();
+			}
+		}
+	}
+	setGraphEnabled(ctx.cwd, false);
+	ctx.ui.notify("code-graph disabled: agents fall back to Read/grep/ls. Re-enable anytime with /enable-graph.", "info");
+}