@flyingrobots/graft 0.4.0 → 0.6.0

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

@@ -1,66 +1,148 @@
 import * as path from "node:path";
-import { execFileSync } from "node:child_process";
 import { z } from "zod";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
 
+const RUN_CAPTURE_POLICY_BOUNDARY = {
+  kind: "shell_escape_hatch",
+  boundedReadContract: false,
+  policyEnforced: false,
+} as const;
+
+const PRIVATE_KEY_BLOCK_RE = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+const SECRET_ASSIGNMENT_RE = /(\b(?:api[_-]?key|access[_-]?token|auth(?:orization)?|bearer|token|secret|password|passwd|private[_-]?key|client[_-]?secret|session[_-]?key)\b\s*[:=]\s*)([^\r\n]+)/gi;
+const BEARER_TOKEN_RE = /(\bbearer\s+)([A-Za-z0-9._~+/=-]{8,})/gi;
+
+function tailOutput(output: string, tail: number): {
+  readonly tailed: string;
+  readonly totalLines: number;
+} {
+  const lines = output.split("\n");
+  return {
+    tailed: lines.slice(-tail).join("\n"),
+    totalLines: lines.length,
+  };
+}
+
+function renderCaptureError(result: {
+  readonly status: number | null;
+  readonly stderr: string;
+  readonly error?: Error;
+}): string {
+  if (result.error !== undefined) {
+    return result.error.message;
+  }
+  const stderr = result.stderr.trim();
+  if (stderr.length > 0) {
+    return stderr;
+  }
+  return `Command exited with status ${String(result.status)}`;
+}
+
+function redactForLog(output: string): {
+  readonly value: string;
+  readonly redactions: number;
+} {
+  let redactions = 0;
+  let value = output.replace(PRIVATE_KEY_BLOCK_RE, () => {
+    redactions++;
+    return "[REDACTED PRIVATE KEY BLOCK]";
+  });
+  value = value.replace(SECRET_ASSIGNMENT_RE, (_match, prefix: string) => {
+    redactions++;
+    return `${prefix}[REDACTED]`;
+  });
+  value = value.replace(BEARER_TOKEN_RE, (_match, prefix: string) => {
+    redactions++;
+    return `${prefix}[REDACTED]`;
+  });
+  return { value, redactions };
+}
+
+async function persistCaptureLog(ctx: ToolContext, output: string): Promise<{
+  readonly logPath: string | null;
+  readonly logRedactions: number;
+}> {
+  if (!ctx.runCapture.persistLogs) {
+    return { logPath: null, logRedactions: 0 };
+  }
+
+  const logPath = path.join(ctx.graftDir, "logs", "capture.log");
+  const persisted = ctx.runCapture.redactLogs ? redactForLog(output) : { value: output, redactions: 0 };
+
+  try {
+    await ctx.fs.mkdir(path.dirname(logPath), { recursive: true });
+    await ctx.fs.writeFile(logPath, persisted.value, "utf-8");
+    return {
+      logPath,
+      logRedactions: persisted.redactions,
+    };
+  } catch {
+    return { logPath: null, logRedactions: 0 };
+  }
+}
+
 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.",
+    "(default 60). Responses include an explicit policy boundary. " +
+    "Persisted logs can be disabled and obvious secrets are redacted " +
+    "before writing to .graft/logs/capture.log.",
   schema: { command: z.string(), tail: z.number().optional() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       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;
+      if (!ctx.runCapture.enabled) {
         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) : "",
+          output: "",
+          totalLines: 0,
+          tailedLines: 0,
+          logPath: null,
+          logRedactions: 0,
+          logPersistenceEnabled: false,
+          truncated: false,
+          disabled: true,
+          error: "run_capture is disabled by configuration",
+          policyBoundary: RUN_CAPTURE_POLICY_BOUNDARY,
         });
       }
+      const result = ctx.process.run({
+        command: "sh",
+        args: ["-c", command],
+        cwd: ctx.projectRoot,
+        timeoutMs: 30000,
+        maxBufferBytes: 10 * 1024 * 1024,
+      });
 
-      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;
+      if (result.error !== undefined || result.status !== 0) {
+        const tailedOutput = tailOutput(result.stdout, tail);
+        return ctx.respond("run_capture", {
+          error: renderCaptureError(result),
+          output: tailedOutput.tailed,
+          totalLines: tailedOutput.totalLines,
+          tailedLines: Math.min(tail, tailedOutput.totalLines),
+          logPath: null,
+          logRedactions: 0,
+          logPersistenceEnabled: ctx.runCapture.persistLogs,
+          truncated: tailedOutput.totalLines > tail,
+          stderr: result.stderr.slice(0, 2000),
+          policyBoundary: RUN_CAPTURE_POLICY_BOUNDARY,
+        });
       }
+
+      const output = result.stdout;
+      const tailedOutput = tailOutput(output, tail);
+      const persisted = await persistCaptureLog(ctx, output);
       return ctx.respond("run_capture", {
-        output: tailed,
-        totalLines: lines.length,
-        tailedLines: Math.min(tail, lines.length),
-        logPath: logWriteSucceeded ? logPath : null,
-        truncated: lines.length > tail,
+        output: tailedOutput.tailed,
+        totalLines: tailedOutput.totalLines,
+        tailedLines: Math.min(tail, tailedOutput.totalLines),
+        logPath: persisted.logPath,
+        logRedactions: persisted.logRedactions,
+        logPersistenceEnabled: ctx.runCapture.persistLogs,
+        truncated: tailedOutput.totalLines > tail,
+        policyBoundary: RUN_CAPTURE_POLICY_BOUNDARY,
       });
     };
   },

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

@@ -1,12 +1,13 @@
 import { z } from "zod";
-import { safeRead } from "../../operations/safe-read.js";
-import type { SafeReadResult } from "../../operations/safe-read.js";
-import { evaluatePolicy } from "../../policy/evaluate.js";
+import { safeRead, type SafeReadResult } from "../../operations/safe-read.js";
+import { toJsonObject } from "../../operations/result-dto.js";
 import { RefusedResult } from "../../policy/types.js";
 import { diffOutlines } from "../../parser/diff.js";
 import { CachedFile } from "../cached-file.js";
 import type { Metrics } from "../metrics.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { evaluateMcpPolicy } from "../policy.js";
+import { toRepoPolicyPath } from "../../adapters/repo-paths.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 const PROJECTION_METRICS: Readonly<Record<string, ((m: Metrics) => void) | undefined>> = {
   content: (m) => { m.recordRead(); },
@@ -24,29 +25,27 @@ export const safeReadTool: ToolDefinition = {
     "reason code for banned files. Detects re-reads and returns cached " +
     "outlines or structural diffs.",
   schema: { path: z.string(), intent: z.string().optional() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const filePath = ctx.resolvePath(args["path"] as string);
+      ctx.recordFootprint({ paths: [filePath] });
 
       // Build CachedFile once — all consumers share the same snapshot,
       // eliminating TOCTOU races where the file changes between reads.
       let cf: CachedFile | null = null;
       try {
-        const rawContent = ctx.fs.readFileSync(filePath, "utf-8");
+        const rawContent = await ctx.fs.readFile(filePath, "utf-8");
         cf = new CachedFile(filePath, rawContent);
       } catch {
         // File doesn't exist or can't be read — proceed to safeRead for error handling
       }
 
       // Check cache if we could read the file
-      if (cf !== null) {
+      if (cf?.supportsOutline === true) {
         const cacheResult = ctx.cache.check(filePath, cf.rawContent);
         if (cacheResult.hit) {
           // Defense: re-check policy before returning cached data.
-          const policy = evaluatePolicy(
-            { path: filePath, lines: cf.actual.lines, bytes: cf.actual.bytes },
-            { sessionDepth: ctx.session.getSessionDepth(), budgetRemaining: ctx.session.getBudget()?.remaining },
-          );
+          const policy = evaluateMcpPolicy(ctx, filePath, cf.actual);
           if (policy instanceof RefusedResult) {
             ctx.metrics.recordRefusal();
             return ctx.respond("safe_read", {
@@ -61,6 +60,9 @@ export const safeReadTool: ToolDefinition = {
 
           cacheResult.obs.touch();
           ctx.metrics.recordCacheHit(cf.actual.bytes);
+          ctx.recordFootprint({
+            symbols: cacheResult.obs.outline.map((e) => e.name),
+          });
           return ctx.respond("safe_read", {
             path: filePath,
             projection: "cache_hit",
@@ -77,10 +79,7 @@ export const safeReadTool: ToolDefinition = {
         // File changed since last observation — compute structural diff
         if (cacheResult.stale !== null) {
           // Defense: re-check policy before returning structural data.
-          const policy = evaluatePolicy(
-            { path: filePath, lines: cf.actual.lines, bytes: cf.actual.bytes },
-            { sessionDepth: ctx.session.getSessionDepth(), budgetRemaining: ctx.session.getBudget()?.remaining },
-          );
+          const policy = evaluateMcpPolicy(ctx, filePath, cf.actual);
           if (policy instanceof RefusedResult) {
             ctx.metrics.recordRefusal();
             return ctx.respond("safe_read", {
@@ -96,6 +95,9 @@ export const safeReadTool: ToolDefinition = {
           const diff = diffOutlines(cacheResult.stale.outline, cf.outline);
           const newReadCount = cacheResult.stale.readCount + 1;
           ctx.cache.record(filePath, cf.hash, cf.outline, cf.jumpTable, cf.actual);
+          ctx.recordFootprint({
+            symbols: cf.outline.map((e) => e.name),
+          });
           const updatedObs = ctx.cache.get(filePath);
           return ctx.respond("safe_read", {
             path: filePath,
@@ -117,19 +119,30 @@ export const safeReadTool: ToolDefinition = {
         codec: ctx.codec,
         content: cf?.rawContent,
         intent: args["intent"] as string | undefined,
-        sessionDepth: ctx.session.getSessionDepth(),
-        budgetRemaining: ctx.session.getBudget()?.remaining,
+        policyPath: toRepoPolicyPath(ctx.projectRoot, filePath),
+        graftignorePatterns: [...ctx.graftignorePatterns],
+        sessionDepth: ctx.governor.getGovernorDepth(),
+        budgetRemaining: ctx.governor.getBudget()?.remaining,
       });
 
       PROJECTION_METRICS[result.projection]?.(ctx.metrics);
+      if (result.outline !== undefined) {
+        ctx.recordFootprint({ symbols: result.outline.map((e) => e.name) });
+      }
 
       // Record observation for cacheable projections — uses CachedFile
       // outline (no re-read) to eliminate the snapshot race.
-      if (cf !== null && result.actual !== undefined && CACHEABLE_PROJECTIONS.has(result.projection)) {
+      if (
+        cf !== null &&
+        cf.supportsOutline &&
+        result.actual !== undefined &&
+        CACHEABLE_PROJECTIONS.has(result.projection) &&
+        result.reason !== "UNSUPPORTED_LANGUAGE"
+      ) {
         ctx.cache.record(filePath, cf.hash, cf.outline, cf.jumpTable, result.actual);
       }
 
-      return ctx.respond("safe_read", result);
+      return ctx.respond("safe_read", toJsonObject(result));
     };
   },
 };

package/src/mcp/tools/since.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { graftDiff } from "../../operations/graft-diff.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { evaluateMcpRefusal } from "../policy.js";
 
 export const sinceTool: ToolDefinition = {
   name: "graft_since",
@@ -12,16 +13,19 @@ export const sinceTool: ToolDefinition = {
     base: z.string(),
     head: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const base = args["base"] as string;
       const head = (args["head"] as string | undefined) ?? "HEAD";
 
-      const result = graftDiff({
+      const result = await graftDiff({
         cwd: ctx.projectRoot,
         fs: ctx.fs,
+        git: ctx.git,
+        resolveWorkingTreePath: (filePath) => ctx.resolvePath(filePath),
         base,
         head,
+        refusalCheck: (filePath, actual) => evaluateMcpRefusal(ctx, filePath, actual),
       });
 
       // Aggregate symbol-level changes across all files
@@ -35,9 +39,14 @@ export const sinceTool: ToolDefinition = {
         totalChanged += file.diff.changed.length;
       }
 
+      ctx.recordFootprint({
+        paths: result.files.map((f) => f.path),
+      });
+
       return ctx.respond("graft_since", {
         ...result,
         summary: `+${String(totalAdded)} added, -${String(totalRemoved)} removed, ~${String(totalChanged)} changed across ${String(result.files.length)} files`,
+        layer: "ref_view",
       });
     };
   },

package/src/mcp/tools/state.ts

@@ -1,6 +1,8 @@
+import * as path from "node:path";
 import { z } from "zod";
-import { stateSave, stateLoad } from "../../operations/state.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { STATE_FILENAME, stateSave, stateLoad } from "../../operations/state.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { toJsonObject } from "../../operations/result-dto.js";
 
 export const stateSaveTool: ToolDefinition = {
   name: "state_save",
@@ -8,10 +10,14 @@ export const stateSaveTool: ToolDefinition = {
     "Save session working state (max 8 KB). Use for session bookmarks: " +
     "current task, files modified, next planned actions.",
   schema: { content: z.string() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
-      const result = await stateSave(args["content"] as string, { graftDir: ctx.graftDir, fs: ctx.fs });
-      return ctx.respond("state_save", result as Record<string, unknown>);
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const result = await stateSave(args["content"] as string, {
+        stateDir: ctx.graftDir,
+        statePath: path.join(ctx.graftDir, STATE_FILENAME),
+        fs: ctx.fs,
+      });
+      return ctx.respond("state_save", toJsonObject(result));
     };
   },
 };
@@ -21,10 +27,13 @@ export const stateLoadTool: ToolDefinition = {
   description:
     "Load previously saved session state. Returns null if no state has " +
     "been saved.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
-      const result = await stateLoad({ graftDir: ctx.graftDir, fs: ctx.fs });
-      return ctx.respond("state_load", result as Record<string, unknown>);
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
+      const result = await stateLoad({
+        statePath: path.join(ctx.graftDir, STATE_FILENAME),
+        fs: ctx.fs,
+      });
+      return ctx.respond("state_load", toJsonObject(result));
     };
   },
 };

package/src/mcp/tools/stats.ts

@@ -1,19 +1,23 @@
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { totalNonReadBytesReturned } from "../burden.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const statsTool: ToolDefinition = {
   name: "stats",
   description:
     "Decision metrics for the current session. Total reads, outlines, " +
-    "refusals, cache hits, and bytes avoided.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return () => {
+    "refusals, cache hits, bytes avoided, and burden by tool kind.",
+  createHandler(): ToolHandler {
+    return (_args, ctx) => {
       const snap = ctx.metrics.snapshot();
       return ctx.respond("stats", {
         totalReads: snap.reads,
         totalOutlines: snap.outlines,
         totalRefusals: snap.refusals,
         totalCacheHits: snap.cacheHits,
+        totalBytesReturned: snap.bytesReturned,
         totalBytesAvoidedByCache: snap.bytesAvoided,
+        totalNonReadBytesReturned: totalNonReadBytesReturned(snap.burdenByKind),
+        burdenByKind: snap.burdenByKind,
       });
     };
   },

package/src/mcp/tools/workspace-authorizations.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const workspaceAuthorizationsTool: ToolDefinition = {
+  name: "workspace_authorizations",
+  description:
+    "List daemon-authorized workspaces, their capability posture, and active bound-session counts.",
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
+      return ctx.respond("workspace_authorizations", {
+        workspaces: await ctx.listWorkspaceAuthorizations(),
+      });
+    };
+  },
+};

package/src/mcp/tools/workspace-authorize.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const workspaceAuthorizeTool: ToolDefinition = {
+  name: "workspace_authorize",
+  description:
+    "Authorize a workspace for daemon binding and optionally change its daemon capability posture.",
+  schema: {
+    cwd: z.string(),
+    runCapture: z.boolean().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("workspace_authorize", { ...await ctx.authorizeWorkspace({
+        cwd: args["cwd"] as string,
+        runCapture: args["runCapture"] as boolean | undefined,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/workspace-bind.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const workspaceBindTool: ToolDefinition = {
+  name: "workspace_bind",
+  description:
+    "Bind the current daemon session to a workspace by resolving repo and worktree identity server-side.",
+  schema: {
+    cwd: z.string(),
+    worktreeRoot: z.string().optional(),
+    gitCommonDir: z.string().optional(),
+    repoId: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const result = await ctx.bindWorkspace({
+        cwd: args["cwd"] as string,
+        worktreeRoot: args["worktreeRoot"] as string | undefined,
+        gitCommonDir: args["gitCommonDir"] as string | undefined,
+        repoId: args["repoId"] as string | undefined,
+      }, "workspace_bind");
+      return ctx.respond("workspace_bind", { ...result });
+    };
+  },
+};

package/src/mcp/tools/workspace-rebind.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const workspaceRebindTool: ToolDefinition = {
+  name: "workspace_rebind",
+  description:
+    "Rebind the current daemon session to a different workspace and start a fresh session-local slice.",
+  schema: {
+    cwd: z.string(),
+    worktreeRoot: z.string().optional(),
+    gitCommonDir: z.string().optional(),
+    repoId: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const result = await ctx.rebindWorkspace({
+        cwd: args["cwd"] as string,
+        worktreeRoot: args["worktreeRoot"] as string | undefined,
+        gitCommonDir: args["gitCommonDir"] as string | undefined,
+        repoId: args["repoId"] as string | undefined,
+      }, "workspace_rebind");
+      return ctx.respond("workspace_rebind", { ...result });
+    };
+  },
+};

package/src/mcp/tools/workspace-revoke.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const workspaceRevokeTool: ToolDefinition = {
+  name: "workspace_revoke",
+  description:
+    "Revoke daemon authorization for a workspace while leaving any already-open sessions visible to the control plane.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("workspace_revoke", { ...await ctx.revokeWorkspace({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/workspace-status.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const workspaceStatusTool: ToolDefinition = {
+  name: "workspace_status",
+  description:
+    "Return the current daemon workspace binding state and resolved capability profile.",
+  createHandler(): ToolHandler {
+    return (_args, ctx) => {
+      return ctx.respond("workspace_status", { ...ctx.getWorkspaceStatus() });
+    };
+  },
+};

package/src/mcp/warp-pool.ts

@@ -0,0 +1,36 @@
+import type { WarpHandle } from "../ports/warp.js";
+import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
+
+export interface WarpPool {
+  getOrOpen(repoId: string, worktreeRoot: string, writerId?: string): Promise<WarpHandle>;
+  size(): number;
+}
+
+export class InMemoryWarpPool implements WarpPool {
+  private readonly opened = new Map<string, Map<string, Promise<WarpHandle>>>();
+
+  constructor(private readonly openWarp: (worktreeRoot: string, writerId: string) => Promise<WarpHandle>) {}
+
+  getOrOpen(repoId: string, worktreeRoot: string, writerId: string = DEFAULT_WARP_WRITER_ID): Promise<WarpHandle> {
+    const repoHandles = this.opened.get(repoId);
+    const cached = repoHandles?.get(writerId);
+    if (cached !== undefined) return cached;
+
+    const nextRepoHandles = repoHandles ?? new Map<string, Promise<WarpHandle>>();
+    const opened = this.openWarp(worktreeRoot, writerId).catch((error: unknown) => {
+      const current = this.opened.get(repoId);
+      current?.delete(writerId);
+      if (current?.size === 0) {
+        this.opened.delete(repoId);
+      }
+      throw error;
+    });
+    nextRepoHandles.set(writerId, opened);
+    this.opened.set(repoId, nextRepoHandles);
+    return opened;
+  }
+
+  size(): number {
+    return this.opened.size;
+  }
+}

package/src/mcp/workspace-read-observation-model.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { JsonObject } from "../contracts/json-object.js";
+
+export const attributedReadArgsSchema = z.object({
+  path: z.string(),
+}).catchall(z.unknown());
+
+const safeReadObservationResultSchema = z.object({
+  projection: z.enum(["content", "outline", "cache_hit", "diff"]),
+  reason: z.string().optional(),
+}).catchall(z.unknown());
+
+const fileOutlineObservationResultSchema = z.object({
+  reason: z.string().optional(),
+  error: z.string().optional(),
+}).catchall(z.unknown());
+
+const readRangeObservationResultSchema = z.object({
+  content: z.string(),
+  startLine: z.number().int(),
+  endLine: z.number().int(),
+  reason: z.string().optional(),
+}).catchall(z.unknown());
+
+export type AttributedReadArgs = z.infer<typeof attributedReadArgsSchema>;
+export type SafeReadObservationResult = z.infer<typeof safeReadObservationResultSchema>;
+export type FileOutlineObservationResult = z.infer<typeof fileOutlineObservationResultSchema>;
+export type ReadRangeObservationResult = z.infer<typeof readRangeObservationResultSchema>;
+
+export function parseAttributedReadArgs(args: JsonObject): AttributedReadArgs | null {
+  const parsed = attributedReadArgsSchema.safeParse(args);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseSafeReadObservationResult(result: JsonObject): SafeReadObservationResult | null {
+  const parsed = safeReadObservationResultSchema.safeParse(result);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseFileOutlineObservationResult(result: JsonObject): FileOutlineObservationResult | null {
+  const parsed = fileOutlineObservationResultSchema.safeParse(result);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseReadRangeObservationResult(result: JsonObject): ReadRangeObservationResult | null {
+  const parsed = readRangeObservationResultSchema.safeParse(result);
+  return parsed.success ? parsed.data : null;
+}