@flyingrobots/graft 0.6.1 → 0.7.0

package/src/mcp/monitor-tick-job.ts

@@ -1,5 +1,6 @@
-import { indexCommits } from "../warp/indexer.js";
+import { DEFAULT_INDEX_MAX_FILES_PER_CALL, indexHead } from "../warp/index-head.js";
 import { nodeGit } from "../adapters/node-git.js";
+import { nodePathOps } from "../adapters/node-paths.js";
 import { openWarp } from "../warp/open.js";
 
 export interface MonitorTickWorkerJob {
@@ -7,6 +8,7 @@ export interface MonitorTickWorkerJob {
   readonly worktreeRoot: string;
   readonly writerId: string;
   readonly lastIndexedCommit: string | null;
+  readonly maxFilesPerBatch?: number | undefined;
 }
 
 export type MonitorTickWorkerResult =
@@ -26,8 +28,8 @@ export type MonitorTickWorkerResult =
     readonly backlogCommits: number;
   };
 
-async function readGit(cwd: string, args: readonly string[]): Promise<string | null> {
-  const result = await nodeGit.run({ cwd, args });
+async function readHeadCommit(cwd: string): Promise<string | null> {
+  const result = await nodeGit.run({ cwd, args: ["rev-parse", "--verify", "HEAD"] });
   if (result.error !== undefined || result.status !== 0) {
     return null;
   }
@@ -35,68 +37,117 @@ async function readGit(cwd: string, args: readonly string[]): Promise<string | n
   return trimmed.length === 0 ? null : trimmed;
 }
 
-async function readHeadCommit(cwd: string): Promise<string | null> {
-  return readGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+function parseGitPathList(output: string): readonly string[] {
+  const seen = new Set<string>();
+  const paths: string[] = [];
+  for (const line of output.split("\n")) {
+    const filePath = line.trim();
+    if (filePath.length === 0 || seen.has(filePath)) continue;
+    seen.add(filePath);
+    paths.push(filePath);
+  }
+  return paths;
 }
 
-async function countPendingCommits(
-  cwd: string,
-  from: string | null,
-  to: string | null,
-): Promise<number> {
-  if (to === null) return 0;
-  const range = from === null ? to : `${from}..${to}`;
-  const output = await readGit(cwd, ["rev-list", "--count", range]);
-  if (output === null) return 0;
-  const parsed = Number.parseInt(output, 10);
-  return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+async function listTrackedPaths(cwd: string): Promise<readonly string[]> {
+  const result = await nodeGit.run({ cwd, args: ["ls-files"] });
+  if (result.error !== undefined || result.status !== 0) {
+    throw result.error ?? new Error(result.stderr.trim() || `git ls-files exited with status ${String(result.status)}`);
+  }
+  return parseGitPathList(result.stdout);
+}
+
+async function listChangedPaths(cwd: string, base: string, head: string): Promise<readonly string[] | null> {
+  const result = await nodeGit.run({ cwd, args: ["diff", "--name-only", `${base}..${head}`] });
+  if (result.error !== undefined || result.status !== 0) {
+    return null;
+  }
+  return parseGitPathList(result.stdout);
+}
+
+async function monitorIndexPaths(input: {
+  readonly cwd: string;
+  readonly currentHead: string | null;
+  readonly lastIndexedCommit: string | null;
+}): Promise<readonly string[]> {
+  if (input.currentHead === null) return [];
+  if (input.lastIndexedCommit !== null) {
+    const changedPaths = await listChangedPaths(input.cwd, input.lastIndexedCommit, input.currentHead);
+    if (changedPaths !== null) return changedPaths;
+  }
+  return listTrackedPaths(input.cwd);
+}
+
+function pathBatches(paths: readonly string[], size: number): readonly (readonly string[])[] {
+  const batches: (readonly string[])[] = [];
+  for (let index = 0; index < paths.length; index += size) {
+    batches.push(paths.slice(index, index + size));
+  }
+  return batches;
 }
 
 export async function runMonitorTickJob(job: MonitorTickWorkerJob): Promise<MonitorTickWorkerResult> {
   const headAtStart = await readHeadCommit(job.worktreeRoot);
 
+  // ── Tick ceiling: skip indexing when HEAD hasn't moved ───────────
+  // When HEAD equals the last indexed commit (including both null for
+  // empty repos), there is nothing to index. Short-circuit before
+  // opening WARP or calling indexCommits to keep idle ticks near-zero-cost.
+  if (headAtStart === job.lastIndexedCommit) {
+    return {
+      ok: true,
+      headAtStart,
+      currentHead: headAtStart,
+      lastIndexedCommit: job.lastIndexedCommit,
+      backlogCommits: 0,
+      commitsIndexed: 0,
+      patchesWritten: 0,
+    };
+  }
+
   try {
-    const warp = await openWarp({
+    const app = await openWarp({
       cwd: job.worktreeRoot,
       writerId: job.writerId,
     });
-    const result = await indexCommits(warp, {
+    const ctx = { app, strandId: null };
+    const paths = await monitorIndexPaths({
       cwd: job.worktreeRoot,
-      git: nodeGit,
-      ...(job.lastIndexedCommit !== null ? { from: job.lastIndexedCommit } : {}),
-      ...(headAtStart !== null ? { to: headAtStart } : {}),
+      currentHead: headAtStart,
+      lastIndexedCommit: job.lastIndexedCommit,
     });
-    if (!result.ok) {
-      throw new Error(result.error);
+    let commitsIndexed = 0;
+    let patchesWritten = 0;
+    const maxFilesPerBatch = job.maxFilesPerBatch ?? DEFAULT_INDEX_MAX_FILES_PER_CALL;
+    for (const batch of pathBatches(paths, maxFilesPerBatch)) {
+      const result = await indexHead({
+        cwd: job.worktreeRoot,
+        git: nodeGit,
+        pathOps: nodePathOps,
+        ctx,
+        paths: batch,
+        maxFilesPerCall: maxFilesPerBatch,
+      });
+      commitsIndexed += result.filesIndexed;
+      patchesWritten += result.nodesEmitted;
     }
     const currentHead = await readHeadCommit(job.worktreeRoot);
-    const lastIndexedCommit = headAtStart ?? job.lastIndexedCommit;
-    const backlogCommits = await countPendingCommits(
-      job.worktreeRoot,
-      lastIndexedCommit,
-      currentHead,
-    );
     return {
       ok: true,
       headAtStart,
       currentHead,
-      lastIndexedCommit,
-      backlogCommits,
-      commitsIndexed: result.commitsIndexed,
-      patchesWritten: result.patchesWritten,
+      lastIndexedCommit: headAtStart,
+      backlogCommits: 0,
+      commitsIndexed,
+      patchesWritten,
     };
   } catch (error) {
     const currentHead = await readHeadCommit(job.worktreeRoot);
-    const backlogCommits = await countPendingCommits(
-      job.worktreeRoot,
-      job.lastIndexedCommit,
-      currentHead,
-    );
     return {
       ok: false,
       error: error instanceof Error ? error.message : String(error),
       currentHead,
-      backlogCommits,
+      backlogCommits: 0,
     };
   }
 }

package/src/mcp/monitor-types.ts

@@ -18,7 +18,7 @@ export const DEFAULT_POLL_INTERVAL_MS = 5_000;
 export type MonitorLifecycleState = "running" | "paused" | "stopped";
 export type MonitorHealth = "ok" | "lagging" | "error" | "unauthorized" | "paused" | "stopped";
 export type MonitorWorkerKind = "git_poll_indexer";
-export type MonitorAction = "start" | "pause" | "resume" | "stop";
+export type MonitorAction = "start" | "pause" | "resume" | "stop" | "nudge";
 
 // ── Persistence schemas ────────────────────────────────────────────
 

package/src/mcp/persisted-local-history-graph.ts

@@ -6,10 +6,11 @@ import type {
   CausalRegion,
   Evidence,
 } from "../contracts/causal-ontology.js";
-import type { WarpHandle } from "../ports/warp.js";
+import type { WarpContext } from "../warp/context.js";
+import { patchGraph } from "../warp/context.js";
 import type { RuntimeStagedTargetFullFile } from "./runtime-staged-target.js";
 
-export type PersistedLocalHistoryGraphWarp = Pick<WarpHandle, "hasNode" | "observer" | "patch">;
+export type PersistedLocalHistoryGraphWarp = WarpContext;
 
 export interface PersistedLocalHistoryGraphContext {
   readonly warp: PersistedLocalHistoryGraphWarp;
@@ -161,10 +162,10 @@ async function commitAccumulator(
   const ids = [...accumulator.nodes.keys()];
   const existence = new Map<string, boolean>();
   for (const id of ids) {
-    existence.set(id, await graph.warp.hasNode(id));
+    existence.set(id, await graph.warp.app.core().hasNode(id));
   }
 
-  await graph.warp.patch((patch) => {
+  await patchGraph(graph.warp, (patch) => {
     for (const [id, props] of accumulator.nodes.entries()) {
       const exists = existence.get(id) ?? false;
       if (!exists) {

package/src/mcp/persisted-local-history.ts

@@ -462,7 +462,7 @@ async function loadObservedLocalHistoryGraph(
     return null;
   }
 
-  const observer = await graph.warp.observer({
+  const observer = await graph.warp.app.observer({
     match: [...LOCAL_HISTORY_GRAPH_MATCH],
     expose: [...LOCAL_HISTORY_GRAPH_EXPOSE],
   });
@@ -980,7 +980,7 @@ async function hasLocalHistoryEventNode(
   graph: PersistedLocalHistoryGraphContext,
   eventId: string,
 ): Promise<boolean> {
-  return graph.warp.hasNode(`lh:event:${eventId}`);
+  return graph.warp.app.core().hasNode(`lh:event:${eventId}`);
 }
 
 export async function migrateLegacyPersistedLocalHistoryToGraph(input: {

package/src/mcp/persistent-monitor-runtime.ts

@@ -200,6 +200,43 @@ export class PersistentMonitorRuntime {
     return this.transitionMonitor("stop", request, "stopped");
   }
 
+  async nudgeMonitor(request: WorkspaceBindRequest): Promise<MonitorActionResult> {
+    await this.ensureLoaded();
+    const resolved = await this.resolveAuthorizedRepo(request);
+    if ("errorCode" in resolved) {
+      return {
+        ok: false,
+        action: "nudge",
+        created: false,
+        changed: false,
+        errorCode: resolved.errorCode,
+        error: resolved.error,
+      };
+    }
+    const { repoId } = resolved;
+    const record = this.records.get(repoId);
+    if (record?.lifecycleState !== "running") {
+      return {
+        ok: false,
+        action: "nudge",
+        created: false,
+        changed: false,
+        errorCode: "not_running",
+        error: "Monitor is not running — start it first.",
+      };
+    }
+    // Fire an immediate tick without changing lifecycle state
+    await this.runTick(repoId).catch(() => undefined);
+    return {
+      ok: true,
+      action: "nudge" as MonitorAction,
+      created: false,
+      changed: false,
+      status: await this.getStatusByRepoId(repoId),
+    };
+  }
+
+
   // ── Private: lifecycle transitions ─────────────────────────────
 
   private async transitionMonitor(

package/src/mcp/repo-tool-worker-context.ts

@@ -118,8 +118,8 @@ export function buildRepoToolWorkerContext(
       // captures footprint via AsyncLocalStorage in the invocation engine.
     },
     resolvePath: createRepoPathResolver(job.projectRoot),
-    getWarp() {
-      return openWarp({ cwd: job.projectRoot, writerId: job.writerId });
+    async getWarp() {
+      return { app: await openWarp({ cwd: job.projectRoot, writerId: job.writerId }), strandId: null };
     },
     getRepoState() {
       return job.repoState;
@@ -179,6 +179,9 @@ export function buildRepoToolWorkerContext(
     resumeMonitor() {
       return unsupported("resumeMonitor");
     },
+    nudgeMonitor() {
+      return unsupported("nudgeMonitor");
+    },
     stopMonitor() {
       return unsupported("stopMonitor");
     },

package/src/mcp/server-context.ts

@@ -3,7 +3,7 @@ import type { CanonicalJsonCodec } from "../adapters/canonical-json.js";
 import type { FileSystem } from "../ports/filesystem.js";
 import type { ProcessRunner } from "../ports/process-runner.js";
 import type { GitClient } from "../ports/git.js";
-import type { WarpHandle } from "../ports/warp.js";
+import type { WarpContext } from "../warp/context.js";
 import type { ToolContext, ToolDefinition } from "./context.js";
 import type { McpToolResult } from "./receipt.js";
 import type { RunCaptureConfig } from "./run-capture-config.js";
@@ -92,7 +92,7 @@ export function buildToolContext(deps: ToolContextDeps): ToolContext {
     git: deps.git,
     runCapture: deps.runCapture,
     observability: deps.observability,
-    getWarp(): Promise<WarpHandle> {
+    getWarp(): Promise<WarpContext> {
       return getActiveExecutionContext()?.getWarp() ?? workspaceRouter.getWarp();
     },
     getRepoState() {
@@ -195,6 +195,19 @@ export function buildToolContext(deps: ToolContextDeps): ToolContext {
       }
       return monitorRuntime.resumeMonitor(request);
     },
+    nudgeMonitor(request) {
+      if (monitorRuntime === null) {
+        return Promise.resolve({
+          ok: false,
+          action: "nudge",
+          created: false,
+          changed: false,
+          errorCode: "no_daemon",
+          error: "Monitor runtime is not available.",
+        });
+      }
+      return monitorRuntime.nudgeMonitor(request);
+    },
     stopMonitor(request) {
       if (monitorRuntime === null) {
         throw new Error("monitor_stop is only available in daemon mode");

package/src/mcp/server-tool-access.ts

@@ -1,5 +1,6 @@
 import type { McpToolResult } from "./receipt.js";
-import { parseJsonTextObject, type JsonObject } from "../contracts/json-object.js";
+import type { JsonObject } from "../contracts/json-object.js";
+import { parseJsonTextObject } from "../adapters/json-text-decoder.js";
 import { evaluateMcpPolicy } from "./policy.js";
 import { RefusedResult } from "../policy/types.js";
 import { OFFLOADED_DAEMON_REPO_TOOL_NAMES, type OffloadedRepoToolName } from "./repo-tool-job.js";
@@ -18,6 +19,7 @@ const daemonAlwaysAvailableTools = new Set<string>([
   "monitor_start",
   "monitor_pause",
   "monitor_resume",
+  "monitor_nudge",
   "monitor_stop",
   "workspace_authorize",
   "workspace_authorizations",
@@ -37,6 +39,7 @@ export const repoStateOptionalTools = new Set<string>([
   "monitor_start",
   "monitor_pause",
   "monitor_resume",
+  "monitor_nudge",
   "monitor_stop",
   "workspace_authorize",
   "workspace_authorizations",

package/src/mcp/server.ts

@@ -10,6 +10,7 @@ import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
 import { nodeProcessRunner } from "../adapters/node-process-runner.js";
 import type { ProcessRunner } from "../ports/process-runner.js";
 import { nodeGit } from "../adapters/node-git.js";
+import type { GitClient } from "../ports/git.js";
 import { openWarp } from "../warp/open.js";
 import type { RunCaptureConfig } from "./run-capture-config.js";
 import { resolveRunCaptureConfig } from "./run-capture-config.js";
@@ -64,6 +65,8 @@ export interface CreateGraftServerOptions {
   daemonWorkerPool?: DaemonWorkerPool;
   daemonRuntime?: (() => DaemonRuntimeDescriptor) | undefined;
   processRunner?: ProcessRunner;
+  git?: GitClient;
+  persistedLocalHistoryGraph?: boolean;
 }
 
 export function createGraftServer(options: CreateGraftServerOptions = {}): GraftServer {
@@ -88,6 +91,7 @@ export function createGraftServer(options: CreateGraftServerOptions = {}): Graft
     ...(options.env !== undefined ? { env: options.env } : {}),
     ...(options.runtimeObservability !== undefined ? { overrides: options.runtimeObservability } : {}),
   });
+  const gitClient = options.git ?? nodeGit;
   const runtimeLogger = new RuntimeEventLogger({
     fs: nodeFs,
     codec,
@@ -107,7 +111,7 @@ export function createGraftServer(options: CreateGraftServerOptions = {}): Graft
     ? (options.daemonControlPlane ?? new DaemonControlPlane({
       fs: nodeFs,
       codec,
-      git: nodeGit,
+      git: gitClient,
       graftDir,
     }))
     : null;
@@ -116,7 +120,7 @@ export function createGraftServer(options: CreateGraftServerOptions = {}): Graft
     : (options.monitorRuntime ?? new PersistentMonitorRuntime({
       fs: nodeFs,
       codec,
-      git: nodeGit,
+      git: gitClient,
       graftDir,
       controlPlane: daemonControlPlane,
       scheduler: daemonScheduler,
@@ -139,7 +143,7 @@ export function createGraftServer(options: CreateGraftServerOptions = {}): Graft
   const workspaceRouter = new WorkspaceRouter({
     mode,
     fs: nodeFs,
-    git: nodeGit,
+    git: gitClient,
     graftDir,
     ...(projectRoot !== undefined ? { projectRoot } : {}),
     warpPool,
@@ -148,6 +152,7 @@ export function createGraftServer(options: CreateGraftServerOptions = {}): Graft
     ...(daemonControlPlane !== null ? { authorizationPolicy: daemonControlPlane } : {}),
     ...(daemonControlPlane !== null ? { sharedAttachPolicy: daemonControlPlane } : {}),
     persistedLocalHistory,
+    persistedLocalHistoryGraph: options.persistedLocalHistoryGraph ?? true,
   });
   const daemonRepoOverview = daemonControlPlane !== null && monitorRuntime !== null
     ? new DaemonRepoOverview({

package/src/mcp/tool-registry.ts

@@ -1,6 +1,7 @@
 import type { ToolDefinition } from "./context.js";
 
 import { safeReadTool } from "./tools/safe-read.js";
+import { graftEditTool } from "./tools/graft-edit.js";
 import { fileOutlineTool } from "./tools/file-outline.js";
 import { readRangeTool } from "./tools/read-range.js";
 import { changedSinceTool } from "./tools/changed-since.js";
@@ -16,15 +17,23 @@ import { mapTool } from "./tools/map.js";
 import { codeShowTool } from "./tools/code-show.js";
 import { codeFindTool } from "./tools/code-find.js";
 import { codeRefsTool } from "./tools/code-refs.js";
+import { structuralChurnTool } from "./tools/structural-churn.js";
+import { exportSurfaceDiffTool } from "./tools/export-surface-diff.js";
+import { structuralLogTool } from "./tools/structural-log.js";
+import { structuralBlameTool } from "./tools/structural-blame.js";
+import { refactorDifficultyTool } from "./tools/refactor-difficulty.js";
+import { structuralReviewTool } from "./tools/structural-review.js";
 import { daemonMonitorsTool } from "./tools/daemon-monitors.js";
 import { daemonReposTool } from "./tools/daemon-repos.js";
 import { daemonSessionsTool } from "./tools/daemon-sessions.js";
 import { daemonStatusTool } from "./tools/daemon-status.js";
 import { monitorPauseTool } from "./tools/monitor-pause.js";
 import { monitorResumeTool } from "./tools/monitor-resume.js";
+import { monitorNudgeTool } from "./tools/monitor-nudge.js";
 import { monitorStartTool } from "./tools/monitor-start.js";
 import { monitorStopTool } from "./tools/monitor-stop.js";
 import { activityViewTool } from "./tools/activity-view.js";
+import { knowledgeMapTool } from "./tools/knowledge-map.js";
 import { causalStatusTool } from "./tools/causal-status.js";
 import { causalAttachTool } from "./tools/causal-attach.js";
 import { workspaceAuthorizeTool } from "./tools/workspace-authorize.js";
@@ -36,6 +45,7 @@ import { workspaceRebindTool } from "./tools/workspace-rebind.js";
 
 export const TOOL_REGISTRY: readonly ToolDefinition[] = [
   safeReadTool,
+  graftEditTool,
   fileOutlineTool,
   readRangeTool,
   changedSinceTool,
@@ -55,6 +65,13 @@ export const TOOL_REGISTRY: readonly ToolDefinition[] = [
   codeShowTool,
   codeFindTool,
   codeRefsTool,
+  structuralChurnTool,
+  exportSurfaceDiffTool,
+  structuralLogTool,
+  structuralBlameTool,
+  refactorDifficultyTool,
+  structuralReviewTool,
+  knowledgeMapTool,
 ];
 
 export const DAEMON_TOOL_REGISTRY: readonly ToolDefinition[] = [
@@ -65,6 +82,7 @@ export const DAEMON_TOOL_REGISTRY: readonly ToolDefinition[] = [
   monitorStartTool,
   monitorPauseTool,
   monitorResumeTool,
+  monitorNudgeTool,
   monitorStopTool,
   workspaceAuthorizeTool,
   workspaceAuthorizationsTool,

package/src/mcp/tools/code-find.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { nodePathOps } from "../../adapters/node-paths.js";
+import { indexHead } from "../../warp/index-head.js";
 import { GitFileQuery, listGitFiles } from "./git-files.js";
 import {
   evaluatePrecisionPolicy,
@@ -57,6 +59,26 @@ interface CodeFindOptions {
   readonly allowWarp: boolean;
 }
 
+async function lazyIndexReadPaths(
+  ctx: ToolContext,
+  paths: readonly string[],
+  dirty: boolean,
+): Promise<void> {
+  if (dirty || paths.length === 0) return;
+  try {
+    const warp = await ctx.getWarp();
+    await indexHead({
+      cwd: ctx.projectRoot,
+      git: ctx.git,
+      pathOps: nodePathOps,
+      ctx: warp,
+      paths: [...new Set(paths)],
+    });
+  } catch {
+    // Lazy indexing must never turn a successful read/search into a failure.
+  }
+}
+
 export async function runCodeFind(
   ctx: ToolContext,
   args: Record<string, unknown>,
@@ -140,6 +162,7 @@ export async function runCodeFind(
     paths: [...new Set(visibleMatches.map((m) => m.path))],
     symbols: visibleMatches.map((m) => m.name),
   });
+  await lazyIndexReadPaths(ctx, visibleMatches.map((m) => m.path), repoState.dirty);
 
   return ctx.respond("code_find", {
     query: request.query,

package/src/mcp/tools/code-show.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { readRange } from "../../operations/read-range.js";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { nodePathOps } from "../../adapters/node-paths.js";
+import { indexHead } from "../../warp/index-head.js";
 import { listProjectFiles } from "./git-files.js";
 import {
   evaluatePrecisionPolicy,
@@ -21,6 +23,26 @@ interface CodeShowOptions {
   readonly allowWarp: boolean;
 }
 
+async function lazyIndexReadPaths(
+  ctx: ToolContext,
+  paths: readonly string[],
+  dirty: boolean,
+): Promise<void> {
+  if (dirty || paths.length === 0) return;
+  try {
+    const warp = await ctx.getWarp();
+    await indexHead({
+      cwd: ctx.projectRoot,
+      git: ctx.git,
+      pathOps: nodePathOps,
+      ctx: warp,
+      paths: [...new Set(paths)],
+    });
+  } catch {
+    // Lazy indexing is a cache refresh. It must not break the read response.
+  }
+}
+
 export async function runCodeShow(
   ctx: ToolContext,
   args: Record<string, unknown>,
@@ -186,6 +208,7 @@ export async function runCodeShow(
       paths: [...new Set(visibleLocations.map((m) => m.path))],
       symbols: visibleLocations.map((m) => m.name),
     });
+    await lazyIndexReadPaths(ctx, visibleLocations.map((m) => m.path), repoState.dirty);
     return ctx.respond("code_show", {
       symbol: symbolName,
       ambiguous: true,
@@ -197,6 +220,9 @@ export async function runCodeShow(
 
   const loc = visibleLocations[0];
   if (loc?.startLine === undefined || loc.endLine === undefined) {
+    if (loc?.path !== undefined) {
+      await lazyIndexReadPaths(ctx, [loc.path], repoState.dirty);
+    }
     return ctx.respond("code_show", {
       symbol: symbolName,
       kind: loc?.kind,
@@ -228,6 +254,7 @@ export async function runCodeShow(
     symbols: [loc.name],
     regions: [{ path: loc.path, startLine: loc.startLine, endLine: loc.endLine }],
   });
+  await lazyIndexReadPaths(ctx, [loc.path], repoState.dirty);
 
   return ctx.respond("code_show", {
     symbol: loc.name,

package/src/mcp/tools/diagnostic-models.ts

@@ -12,6 +12,7 @@ import type {
 } from "../persisted-local-history.js";
 import type { RuntimeWorkspaceOverlayFooting } from "../runtime-workspace-overlay.js";
 import type { CausalSurfaceNextAction } from "../../contracts/causal-surface-next-action.js";
+import type { SludgeReport } from "../../operations/sludge-detector.js";
 
 export interface SetBudgetResponse {
   readonly budget: {
@@ -72,6 +73,7 @@ export interface DoctorResponse {
   readonly attribution: PersistedLocalHistorySummary["attribution"];
   readonly persistedLocalHistory: PersistedLocalHistorySummary;
   readonly recommendedNextAction: CausalSurfaceNextAction;
+  readonly sludge?: SludgeReport | undefined;
 }
 
 export interface RunCapturePolicyBoundary {

package/src/mcp/tools/doctor.ts

@@ -5,14 +5,30 @@ import { deriveCausalSurfaceNextAction } from "../semantic-transition-guidance.j
 import type { ToolDefinition, ToolHandler } from "../context.js";
 import { toJsonObject } from "../../operations/result-dto.js";
 import type { DoctorResponse } from "./diagnostic-models.js";
+import { detectSludge } from "../../operations/sludge-detector.js";
+import { z } from "zod";
 
 export const doctorTool: ToolDefinition = {
   name: "doctor",
   description:
     "Runtime health check. Shows project root, parser status, active " +
     "thresholds, session depth, message count, and burden summary.",
+  schema: {
+    sludge: z.boolean().optional(),
+    path: z.string().optional(),
+  },
   createHandler(): ToolHandler {
-    return async (_args, ctx) => {
+    return async (args, ctx) => {
+      const pathArg = typeof args["path"] === "string" ? args["path"] : undefined;
+      const sludge = args["sludge"] === true
+        ? await detectSludge({
+          cwd: ctx.projectRoot,
+          fs: ctx.fs,
+          git: ctx.git,
+          resolvePath: (filePath) => ctx.resolvePath(filePath),
+          ...(pathArg !== undefined ? { path: pathArg } : {}),
+        })
+        : undefined;
       const repoState = ctx.getRepoState();
       const causalContext = ctx.getCausalContext();
       const workspaceOverlayFooting = await ctx.getWorkspaceOverlayFooting();
@@ -59,6 +75,7 @@ export const doctorTool: ToolDefinition = {
         attribution: persistedLocalHistory.attribution,
         persistedLocalHistory,
         recommendedNextAction,
+        ...(sludge !== undefined ? { sludge } : {}),
       };
       return ctx.respond("doctor", toJsonObject(response));
     };

package/src/mcp/tools/export-surface-diff.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { exportSurfaceDiff, exportSurfaceDiffToJson } from "../../operations/export-surface-diff.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const exportSurfaceDiffTool: ToolDefinition = {
+  name: "graft_exports",
+  description:
+    "Export surface diff — what changed in the public API between two " +
+    "refs? Identifies added, removed, and signature-changed exported " +
+    "symbols and derives semver impact.",
+  schema: {
+    base: z.string().optional(),
+    head: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const result = await exportSurfaceDiff({
+        cwd: ctx.projectRoot,
+        git: ctx.git,
+        base: args["base"] as string | undefined,
+        head: args["head"] as string | undefined,
+      });
+      return ctx.respond("graft_exports", exportSurfaceDiffToJson(result));
+    };
+  },
+};