@flyingrobots/graft 0.3.1

package/src/mcp/metrics.ts

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// Session metrics — replaces loose counters in server.ts
+// ---------------------------------------------------------------------------
+
+export interface MetricsSnapshot {
+  readonly reads: number;
+  readonly outlines: number;
+  readonly refusals: number;
+  readonly cacheHits: number;
+  readonly bytesReturned: number;
+  readonly bytesAvoided: number;
+}
+
+export class Metrics {
+  private totalReads = 0;
+  private totalOutlines = 0;
+  private totalRefusals = 0;
+  private totalCacheHits = 0;
+  private totalBytesAvoidedByCache = 0;
+  private cumulativeBytesReturned = 0;
+
+  recordRead(): void {
+    this.totalReads++;
+  }
+
+  recordOutline(): void {
+    this.totalOutlines++;
+  }
+
+  recordRefusal(): void {
+    this.totalRefusals++;
+  }
+
+  recordCacheHit(bytesAvoided: number): void {
+    this.totalCacheHits++;
+    this.totalBytesAvoidedByCache += bytesAvoided;
+  }
+
+  addBytesReturned(n: number): void {
+    this.cumulativeBytesReturned += n;
+  }
+
+  snapshot(): MetricsSnapshot {
+    return {
+      reads: this.totalReads,
+      outlines: this.totalOutlines,
+      refusals: this.totalRefusals,
+      cacheHits: this.totalCacheHits,
+      bytesReturned: this.cumulativeBytesReturned,
+      bytesAvoided: this.totalBytesAvoidedByCache,
+    };
+  }
+}

package/src/mcp/receipt.ts

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// Receipt builder — attaches decision metadata to every tool response
+// ---------------------------------------------------------------------------
+
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { MetricsSnapshot } from "./metrics.js";
+import type { Tripwire } from "../session/types.js";
+import type { JsonCodec } from "../ports/codec.js";
+
+export type McpToolResult = CallToolResult;
+
+export interface ReceiptDeps {
+  readonly sessionId: string;
+  readonly seq: number;
+  readonly metrics: MetricsSnapshot;
+  readonly tripwires: Tripwire[];
+  readonly codec: JsonCodec;
+  readonly budget?: { total: number; consumed: number; remaining: number; fraction: number } | null;
+}
+
+/**
+ * Build a tool response with an attached receipt.
+ * Returns the finalized MCP result and the byte count of the serialized text
+ * so the caller can feed it back into cumulative metrics.
+ */
+export function buildReceiptResult(
+  tool: string,
+  data: Record<string, unknown>,
+  deps: ReceiptDeps,
+): { result: McpToolResult; textBytes: number } {
+  const receipt: Record<string, unknown> = {
+    sessionId: deps.sessionId,
+    seq: deps.seq,
+    ts: new Date().toISOString(),
+    tool,
+    projection: (data["projection"] as string | undefined) ?? "none",
+    reason: (data["reason"] as string | undefined) ?? "none",
+    fileBytes: (data["actual"] as { bytes: number } | undefined)?.bytes ?? null,
+    returnedBytes: 0,
+    cumulative: {
+      reads: deps.metrics.reads,
+      outlines: deps.metrics.outlines,
+      refusals: deps.metrics.refusals,
+      cacheHits: deps.metrics.cacheHits,
+      bytesReturned: 0,
+      bytesAvoided: deps.metrics.bytesAvoided,
+    },
+  };
+
+  if (deps.budget != null) {
+    receipt["budget"] = deps.budget;
+  }
+
+  const fullData: Record<string, unknown> = { ...data, _receipt: receipt };
+  if (deps.tripwires.length > 0) {
+    fullData["tripwire"] = deps.tripwires;
+  }
+
+  // Stabilize self-referential size fields (use UTF-8 byte length, not char count)
+  let prev = 0;
+  let text = "";
+  for (let i = 0; i < 5; i++) {
+    text = deps.codec.encode(fullData);
+    const byteLen = Buffer.byteLength(text, "utf8");
+    if (byteLen === prev) break;
+    prev = byteLen;
+    receipt["returnedBytes"] = byteLen;
+    const fb = receipt["fileBytes"] as number | null;
+    receipt["compressionRatio"] = fb !== null && fb > 0
+      ? Math.round((byteLen / fb) * 1000) / 1000
+      : null;
+    (receipt["cumulative"] as Record<string, number>)["bytesReturned"] =
+      deps.metrics.bytesReturned + byteLen;
+  }
+
+  Object.freeze(receipt["cumulative"]);
+  Object.freeze(receipt);
+
+  return {
+    result: { content: [{ type: "text", text }] },
+    textBytes: Buffer.byteLength(text, "utf8"),
+  };
+}

package/src/mcp/server.ts

@@ -0,0 +1,166 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionTracker } from "../session/tracker.js";
+import { Metrics } from "./metrics.js";
+import { ObservationCache } from "./cache.js";
+import { buildReceiptResult } from "./receipt.js";
+import type { ToolHandler, ToolContext, ToolDefinition } from "./context.js";
+import { createPathResolver } from "./context.js";
+import type { McpToolResult } from "./receipt.js";
+import { nodeFs } from "../adapters/node-fs.js";
+import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
+import { evaluatePolicy } from "../policy/evaluate.js";
+import { RefusedResult } from "../policy/types.js";
+
+// Tool definitions — each file exports a ToolDefinition object
+import { safeReadTool } from "./tools/safe-read.js";
+import { fileOutlineTool } from "./tools/file-outline.js";
+import { readRangeTool } from "./tools/read-range.js";
+import { changedSinceTool } from "./tools/changed-since.js";
+import { graftDiffTool } from "./tools/graft-diff.js";
+import { runCaptureTool } from "./tools/run-capture.js";
+import { stateSaveTool, stateLoadTool } from "./tools/state.js";
+import { doctorTool } from "./tools/doctor.js";
+import { statsTool } from "./tools/stats.js";
+import { explainTool } from "./tools/explain.js";
+import { setBudgetTool } from "./tools/budget.js";
+
+export type { McpToolResult, ToolHandler, ToolContext };
+
+/** All registered tool definitions. Add new tools here. */
+const TOOL_REGISTRY: readonly ToolDefinition[] = [
+  safeReadTool,
+  fileOutlineTool,
+  readRangeTool,
+  changedSinceTool,
+  graftDiffTool,
+  runCaptureTool,
+  stateSaveTool,
+  stateLoadTool,
+  doctorTool,
+  statsTool,
+  explainTool,
+  setBudgetTool,
+];
+
+export interface GraftServer {
+  getRegisteredTools(): string[];
+  callTool(name: string, args: Record<string, unknown>): Promise<McpToolResult>;
+  injectSessionMessages(count: number): void;
+  getMcpServer(): McpServer;
+}
+
+export function createGraftServer(): GraftServer {
+  const mcpServer = new McpServer({ name: "graft", version: "0.0.0" });
+  const session = new SessionTracker();
+  const sessionId = crypto.randomUUID();
+  const projectRoot = process.cwd();
+  const graftDir = path.join(projectRoot, ".graft");
+  const metrics = new Metrics();
+  const cache = new ObservationCache();
+  const codec = new CanonicalJsonCodec();
+  const handlers = new Map<string, ToolHandler>();
+  const schemas = new Map<string, z.ZodObject>();
+  let seq = 0;
+
+  function respond(tool: string, data: Record<string, unknown>): McpToolResult {
+    seq++;
+    const { result, textBytes } = buildReceiptResult(tool, data, {
+      sessionId, seq, codec,
+      metrics: metrics.snapshot(),
+      tripwires: session.checkTripwires(),
+      budget: session.getBudget(),
+    });
+    metrics.addBytesReturned(textBytes);
+    session.recordBytesConsumed(textBytes);
+    return result;
+  }
+
+  const ctx: ToolContext = { projectRoot, graftDir, session, cache, metrics, respond, resolvePath: createPathResolver(projectRoot), fs: nodeFs, codec };
+
+  function wrapWithPolicyCheck(toolName: string, inner: ToolHandler): ToolHandler {
+    return (args: Record<string, unknown>) => {
+      const rawPath = args["path"] as string | undefined;
+      if (rawPath === undefined) return inner(args);
+      const filePath = ctx.resolvePath(rawPath);
+      let content: string;
+      try {
+        content = ctx.fs.readFileSync(filePath, "utf-8");
+      } catch {
+        // File unreadable — let the inner handler deal with the error
+        return inner(args);
+      }
+      const actual = { lines: content.split("\n").length, bytes: Buffer.byteLength(content) };
+      const budget = session.getBudget();
+      const policy = evaluatePolicy(
+        { path: filePath, lines: actual.lines, bytes: actual.bytes },
+        {
+          sessionDepth: session.getSessionDepth(),
+          budgetRemaining: budget?.remaining,
+        },
+      );
+      if (policy instanceof RefusedResult) {
+        metrics.recordRefusal();
+        return respond(toolName, {
+          path: filePath,
+          projection: "refused",
+          reason: policy.reason,
+          reasonDetail: policy.reasonDetail,
+          next: [...policy.next],
+          actual,
+        });
+      }
+      return inner(args);
+    };
+  }
+
+  for (const def of TOOL_REGISTRY) {
+    const rawHandler = def.createHandler(ctx);
+    const handler = def.policyCheck === true ? wrapWithPolicyCheck(def.name, rawHandler) : rawHandler;
+    handlers.set(def.name, handler);
+
+    if (def.schema !== undefined) {
+      const zodSchema = z.object(def.schema).strict();
+      schemas.set(def.name, zodSchema);
+      mcpServer.registerTool(def.name, { description: def.description, inputSchema: def.schema }, async (args) => {
+        session.recordMessage();
+        session.recordToolCall(def.name);
+        const parsed: Record<string, unknown> = zodSchema.parse(args);
+        return handler(parsed);
+      });
+    } else {
+      mcpServer.registerTool(def.name, { description: def.description }, async () => {
+        session.recordMessage();
+        session.recordToolCall(def.name);
+        return handler({});
+      });
+    }
+  }
+
+  return {
+    getRegisteredTools(): string[] {
+      return [...handlers.keys()];
+    },
+    async callTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+      const handler = handlers.get(name);
+      if (handler === undefined) {
+        throw new Error(`Unknown tool: ${name}`);
+      }
+      session.recordMessage();
+      session.recordToolCall(name);
+      const schema = schemas.get(name);
+      const parsed: Record<string, unknown> = schema !== undefined ? schema.parse(args) : args;
+      return handler(parsed);
+    },
+    injectSessionMessages(count: number): void {
+      for (let i = 0; i < count; i++) {
+        session.recordMessage();
+      }
+    },
+    getMcpServer(): McpServer {
+      return mcpServer;
+    },
+  };
+}

package/src/mcp/stdio.ts

@@ -0,0 +1,6 @@
+import { createGraftServer } from "./server.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const graft = createGraftServer();
+const transport = new StdioServerTransport();
+await graft.getMcpServer().connect(transport);

package/src/mcp/tools/budget.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const setBudgetTool: ToolDefinition = {
+  name: "set_budget",
+  description:
+    "Declare a context byte budget for this session. Graft tightens " +
+    "read thresholds as the budget drains — no single read may consume " +
+    "more than 5% of remaining budget. Call once at session start.",
+  schema: { bytes: z.number() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => {
+      const bytes = args["bytes"] as number;
+      ctx.session.setBudget(bytes);
+      return ctx.respond("set_budget", {
+        budget: ctx.session.getBudget(),
+      });
+    };
+  },
+};

package/src/mcp/tools/changed-since.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { evaluatePolicy } from "../../policy/evaluate.js";
+import { RefusedResult } from "../../policy/types.js";
+import { extractOutline } from "../../parser/outline.js";
+import { diffOutlines } from "../../parser/diff.js";
+import { detectLang } from "../../parser/lang.js";
+import { hashContent } from "../cache.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const changedSinceTool: ToolDefinition = {
+  name: "changed_since",
+  description:
+    "Check if a file changed since it was last read. Returns structural " +
+    "diff (added/removed/changed symbols) or 'unchanged'. Peek mode by " +
+    "default; pass consume: true to update the observation cache.",
+  schema: { path: z.string(), consume: z.boolean().optional() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => {
+      const filePath = ctx.resolvePath(args["path"] as string);
+      const consume = (args["consume"] as boolean | undefined) === true;
+
+      // Policy check: refuse banned files even via changed_since.
+      // Read the file first to get dimensions for policy evaluation.
+      let rawContent: string;
+      try {
+        rawContent = ctx.fs.readFileSync(filePath, "utf-8");
+      } catch {
+        return ctx.respond("changed_since", { status: "file_not_found" });
+      }
+
+      const actual = {
+        lines: rawContent.split("\n").length,
+        bytes: Buffer.byteLength(rawContent),
+      };
+      const policy = evaluatePolicy(
+        { path: filePath, lines: actual.lines, bytes: actual.bytes },
+        { sessionDepth: ctx.session.getSessionDepth() },
+      );
+      if (policy instanceof RefusedResult) {
+        return ctx.respond("changed_since", { status: "refused", reason: policy.reason });
+      }
+
+      const cacheResult = ctx.cache.check(filePath, rawContent);
+      if (cacheResult.hit) {
+        return ctx.respond("changed_since", { status: "unchanged" });
+      }
+      if (cacheResult.stale === null) {
+        return ctx.respond("changed_since", { status: "no_previous_observation" });
+      }
+
+      // Use extractOutline with rawContent directly to avoid snapshot race.
+      const newOutlineResult = extractOutline(rawContent, detectLang(filePath) ?? "ts");
+      const diff = diffOutlines(cacheResult.stale.outline, newOutlineResult.entries);
+
+      if (consume) {
+        ctx.cache.record(
+          filePath,
+          hashContent(rawContent),
+          newOutlineResult.entries,
+          newOutlineResult.jumpTable ?? [],
+          actual,
+        );
+      }
+
+      return ctx.respond("changed_since", { diff, consumed: consume });
+    };
+  },
+};

package/src/mcp/tools/doctor.ts

@@ -0,0 +1,20 @@
+import { STATIC_THRESHOLDS } from "../../policy/evaluate.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const doctorTool: ToolDefinition = {
+  name: "doctor",
+  description:
+    "Runtime health check. Shows project root, parser status, active " +
+    "thresholds, session depth, and message count.",
+  createHandler(ctx: ToolContext): ToolHandler {
+    return () => {
+      return ctx.respond("doctor", {
+        projectRoot: ctx.projectRoot,
+        parserHealthy: true,
+        thresholds: { lines: STATIC_THRESHOLDS.lines, bytes: STATIC_THRESHOLDS.bytes },
+        sessionDepth: ctx.session.getSessionDepth(),
+        totalMessages: ctx.session.getMessageCount(),
+      });
+    };
+  },
+};

package/src/mcp/tools/explain.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+const EXPLANATIONS: Readonly<Record<string, { meaning: string; action: string }>> = {
+  CONTENT: {
+    meaning: "File is within size thresholds — full content returned.",
+    action: "No action needed. You have the complete file.",
+  },
+  OUTLINE: {
+    meaning: "File exceeds line or byte thresholds. Structural outline returned instead of content.",
+    action: "Use read_range with the jump table to read specific sections. Do not re-request the full file.",
+  },
+  SESSION_CAP: {
+    meaning: "Session-depth byte cap triggered. The file might fit static thresholds but exceeds the dynamic session cap.",
+    action: "Use read_range for targeted reads. Consider whether you truly need this file at this stage of the session.",
+  },
+  BINARY: {
+    meaning: "Binary file (image, PDF, etc.) cannot be usefully read as text.",
+    action: "Use file_outline for metadata. Check for a text alternative.",
+  },
+  LOCKFILE: {
+    meaning: "Machine-generated lockfile is not useful to read directly.",
+    action: "Read the package manifest (package.json, Cargo.toml, etc.) for dependency info instead.",
+  },
+  MINIFIED: {
+    meaning: "Minified file is not human-readable.",
+    action: "Look for the unminified source file.",
+  },
+  BUILD_OUTPUT: {
+    meaning: "File is in a build output directory (dist/, build/, .next/, etc.).",
+    action: "Read the source in src/ instead of the compiled output.",
+  },
+  SECRET: {
+    meaning: "File may contain secrets (keys, credentials, environment variables).",
+    action: "Check for a .example or template version of this file.",
+  },
+  BUDGET_CAP: {
+    meaning: "File exceeds the budget-proportional byte cap. No single read may consume more than 5% of remaining budget.",
+    action: "Use file_outline or read_range for targeted reads. Consider whether this file is worth the budget cost.",
+  },
+  GRAFTIGNORE: {
+    meaning: "File matches a pattern in .graftignore.",
+    action: "Check .graftignore if you believe this file should be readable.",
+  },
+  REREAD_UNCHANGED: {
+    meaning: "File was already read and has not changed. Cached outline returned.",
+    action: "Use the cached outline and jump table. The file content has not changed since your last read.",
+  },
+  CHANGED_SINCE_LAST_READ: {
+    meaning: "File changed since last read. Structural diff returned showing what changed.",
+    action: "Review the diff to understand what changed. Use read_range for details on changed sections.",
+  },
+};
+
+export const explainTool: ToolDefinition = {
+  name: "explain",
+  description:
+    "Explain a graft reason code. Returns human-readable meaning and " +
+    "recommended next action for any reason code returned by graft tools.",
+  schema: { code: z.string() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => {
+      const code = (args["code"] as string).toUpperCase();
+      const entry = EXPLANATIONS[code];
+      if (entry === undefined) {
+        const known = Object.keys(EXPLANATIONS).join(", ");
+        return ctx.respond("explain", {
+          code,
+          error: "Unknown reason code",
+          knownCodes: known,
+        });
+      }
+      return ctx.respond("explain", {
+        code,
+        meaning: entry.meaning,
+        action: entry.action,
+      });
+    };
+  },
+};

package/src/mcp/tools/file-outline.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { fileOutline } from "../../operations/file-outline.js";
+import { hashContent } from "../cache.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const fileOutlineTool: ToolDefinition = {
+  name: "file_outline",
+  description:
+    "Structural skeleton of a file \u2014 function signatures, class shapes, " +
+    "exports. Includes a jump table mapping each symbol to its line range " +
+    "for targeted read_range follow-ups.",
+  schema: { path: z.string() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      const filePath = ctx.resolvePath(args["path"] as string);
+
+      // Check cache
+      let rawContent: string | null = null;
+      try {
+        rawContent = ctx.fs.readFileSync(filePath, "utf-8");
+      } catch {
+        // proceed to fileOutline for error handling
+      }
+
+      if (rawContent !== null) {
+        const cacheResult = ctx.cache.check(filePath, rawContent);
+        if (cacheResult.hit) {
+          cacheResult.obs.touch();
+          ctx.metrics.recordCacheHit(cacheResult.obs.actual.bytes);
+          return ctx.respond("file_outline", {
+            path: filePath,
+            outline: cacheResult.obs.outline,
+            jumpTable: cacheResult.obs.jumpTable,
+            cacheHit: true,
+          });
+        }
+        // If stale, fall through to fresh parse (no diff for file_outline)
+      }
+
+      const result = await fileOutline(filePath, { fs: ctx.fs });
+      ctx.metrics.recordOutline();
+
+      // Record observation
+      if (rawContent !== null) {
+        ctx.cache.record(
+          filePath,
+          hashContent(rawContent),
+          result.outline,
+          result.jumpTable,
+          { lines: rawContent.split("\n").length, bytes: Buffer.byteLength(rawContent) },
+        );
+      }
+
+      return ctx.respond("file_outline", result);
+    };
+  },
+};

package/src/mcp/tools/graft-diff.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { graftDiff } from "../../operations/graft-diff.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const graftDiffTool: ToolDefinition = {
+  name: "graft_diff",
+  description:
+    "Structural diff between two git refs. Shows added, removed, and " +
+    "changed symbols per file \u2014 not line hunks. Defaults to working " +
+    "tree vs HEAD.",
+  schema: { base: z.string().optional(), head: z.string().optional(), path: z.string().optional() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => {
+      const result = graftDiff({
+        cwd: ctx.projectRoot,
+        fs: ctx.fs,
+        base: args["base"] as string | undefined,
+        head: args["head"] as string | undefined,
+        path: args["path"] as string | undefined,
+      });
+      return ctx.respond("graft_diff", result);
+    };
+  },
+};

package/src/mcp/tools/read-range.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { readRange } from "../../operations/read-range.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const readRangeTool: ToolDefinition = {
+  name: "read_range",
+  description:
+    "Read a bounded range of lines from a file. Maximum 250 lines. " +
+    "Use jump table entries from file_outline or safe_read to target " +
+    "specific symbols.",
+  schema: { path: z.string(), start: z.number(), end: z.number() },
+  policyCheck: true,
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      const filePath = ctx.resolvePath(args["path"] as string);
+      const result = await readRange(filePath, args["start"] as number, args["end"] as number, { fs: ctx.fs });
+      ctx.metrics.recordRead();
+      return ctx.respond("read_range", result);
+    };
+  },
+};

package/src/mcp/tools/run-capture.ts

@@ -0,0 +1,67 @@
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const runCaptureTool: ToolDefinition = {
+  name: "run_capture",
+  description:
+    "Execute a shell command and return the last N lines of output " +
+    "(default 60). Full output saved to .graft/logs/capture.log for " +
+    "follow-up read_range calls.",
+  schema: { command: z.string(), tail: z.number().optional() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      const command = args["command"] as string;
+      const tail = Math.max(1, Math.floor((args["tail"] as number | undefined) ?? 60));
+      // execFileSync is intentional: MCP tool calls are sequential per-session,
+      // and synchronous execution simplifies stdout/stderr capture with timeout.
+      let output: string;
+      try {
+        output = execFileSync("sh", ["-c", command], {
+          cwd: ctx.projectRoot,
+          encoding: "utf-8",
+          timeout: 30000,
+          stdio: ["pipe", "pipe", "pipe"],
+          maxBuffer: 10 * 1024 * 1024,
+        });
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const stdout = (err as { stdout?: string }).stdout ?? "";
+        const stderr = (err as { stderr?: string }).stderr ?? "";
+        // Return whatever stdout was captured before failure
+        const tailed = typeof stdout === "string"
+          ? stdout.split("\n").slice(-tail).join("\n")
+          : "";
+        const totalLines = typeof stdout === "string" ? stdout.split("\n").length : 0;
+        return ctx.respond("run_capture", {
+          error: msg,
+          output: tailed,
+          totalLines,
+          tailedLines: Math.min(tail, totalLines),
+          truncated: totalLines > tail,
+          stderr: typeof stderr === "string" ? stderr.slice(0, 2000) : "",
+        });
+      }
+
+      const lines = output.split("\n");
+      const tailed = lines.slice(-tail).join("\n");
+      const logPath = path.join(ctx.graftDir, "logs", "capture.log");
+      let logWriteSucceeded = true;
+      try {
+        await ctx.fs.mkdir(path.dirname(logPath), { recursive: true });
+        await ctx.fs.writeFile(logPath, output, "utf-8");
+      } catch {
+        // Log persistence failure must not mask a successful command
+        logWriteSucceeded = false;
+      }
+      return ctx.respond("run_capture", {
+        output: tailed,
+        totalLines: lines.length,
+        tailedLines: Math.min(tail, lines.length),
+        logPath: logWriteSucceeded ? logPath : null,
+        truncated: lines.length > tail,
+      });
+    };
+  },
+};