@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/shared/attachment-zip.ts

@@ -0,0 +1,281 @@
+/**
+ * ZIP validation and decompression for attachment archives — the byte-level
+ * half of an `extract` attachment, shared by every writer of one.
+ *
+ * Security model: attachments are untrusted user uploads. Archives are parsed
+ * from the central directory — the format's authoritative index — via the
+ * shared structural layer (@stigmer/zip-structure; issue #567, which killed
+ * the earlier local-header walk: it silently truncated stored streaming
+ * entries and rejected Go-default archives outright). Every entry is
+ * validated for path traversal, zip bombs, and format integrity BEFORE any
+ * extraction occurs, and because the central directory's sizes are
+ * declarations an attacker controls, decompression re-enforces them: an
+ * entry whose actual output disagrees with its declared size aborts the
+ * extraction.
+ *
+ * Error model: fail-hard through {@link AttachmentValidationError}. An
+ * archive that fails any check aborts the whole attachment resolution and
+ * propagates a descriptive, user-fixable message. This is deliberately the
+ * OPPOSITE policy from the skill-artifact reader (`zip-extract.ts`,
+ * non-fatal empty return): skill artifacts were structurally vouched for by
+ * the push gates, attachments never are.
+ *
+ * Validation and decompression share one record ({@link ValidatedZipEntry},
+ * still carrying its payload slice), so parsing happens exactly once and
+ * "the manifest promised a file extraction cannot find" is unrepresentable.
+ * The WRITE of an extracted entry is the caller's: the attachment resolver
+ * writes under the session's platform dir (`attachment-resolver.ts`), the
+ * one caller since S3 M2b retired the native injector. Moved here from that
+ * injector at S3 M1 (Q-S3-14) so the guards have one home.
+ */
+
+import { createInflateRaw } from "node:zlib";
+import { posix } from "node:path";
+import {
+  EOCD_MIN_SIZE,
+  parseZipStructure,
+  type ZipStructuralEntry,
+} from "@stigmer/zip-structure";
+
+// ── Constants ────────────────────────────────────────────────────────
+
+export const MAX_ZIP_FILES = 1000;
+export const MAX_ZIP_EXTRACTED_SIZE = 100 * 1024 * 1024; // 100 MB
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface ZipEntryInfo {
+  readonly relativePath: string;
+  readonly uncompressedSize: number;
+}
+
+/**
+ * A validated file entry, still carrying its payload slice. Validation and
+ * extraction share these records — parsing happens exactly once, so "the
+ * manifest promised a file extraction cannot find" is unrepresentable
+ * (the old two-walker design silently skipped such entries).
+ */
+export interface ValidatedZipEntry extends ZipEntryInfo {
+  readonly compressionMethod: number;
+  readonly compressedData: Uint8Array;
+}
+
+// ── Errors ───────────────────────────────────────────────────────────
+
+/** An archive the user handed us cannot be safely extracted; the reason is theirs to fix. */
+export class AttachmentValidationError extends Error {
+  readonly attachmentFilename: string;
+  readonly reason: string;
+
+  constructor(attachmentFilename: string, reason: string) {
+    super(`Attachment '${attachmentFilename}': ${reason}`);
+    this.name = "AttachmentValidationError";
+    this.attachmentFilename = attachmentFilename;
+    this.reason = reason;
+  }
+}
+
+// ── ZIP Validation (pure functions) ──────────────────────────────────
+
+/**
+ * Validate a ZIP archive for safe extraction. Returns the manifest of
+ * file entries (directories excluded) if the archive passes all checks.
+ *
+ * Security checks enforced:
+ * 1. Valid ZIP format (readable central directory; fail-hard, see module doc)
+ * 2. No absolute paths (entries starting with / or \)
+ * 3. No path traversal (.. components)
+ * 4. No null bytes in filenames
+ * 5. No duplicate entry paths (a contradictory manifest)
+ * 6. Only supported compression methods (stored, deflate) — checked here
+ *    so an unsupported entry can never abort extraction after earlier
+ *    entries were already written
+ * 7. Non-empty archive (at least one file entry)
+ * 8. File count within limits (max 1000)
+ * 9. Total declared uncompressed size within limits (max 100 MB) —
+ *    declarations are re-enforced against actual output at decompression
+ */
+export function validateZipForExtraction(
+  zipData: Buffer,
+  sourceFilename: string,
+): ZipEntryInfo[] {
+  return parseAndValidateZip(zipData, sourceFilename).map(
+    ({ relativePath, uncompressedSize }) => ({ relativePath, uncompressedSize }),
+  );
+}
+
+/** The same checks as {@link validateZipForExtraction}, keeping each entry's payload for the extraction that follows. */
+export function parseAndValidateZip(
+  zipData: Buffer,
+  sourceFilename: string,
+): ValidatedZipEntry[] {
+  if (zipData.length < EOCD_MIN_SIZE) {
+    throw new AttachmentValidationError(
+      sourceFilename,
+      "not a valid ZIP archive (file too small)",
+    );
+  }
+
+  let structural: ZipStructuralEntry[];
+  try {
+    structural = parseZipStructure(zipData);
+  } catch (err) {
+    throw new AttachmentValidationError(
+      sourceFilename,
+      `not a valid ZIP archive (${err instanceof Error ? err.message : String(err)})`,
+    );
+  }
+
+  const entries: ValidatedZipEntry[] = [];
+  const seenPaths = new Set<string>();
+  let totalUncompressed = 0;
+
+  for (const entry of structural) {
+    if (entry.name.includes("\u0000")) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        "contains a filename with null bytes and cannot be safely extracted",
+      );
+    }
+
+    if (entry.isDirectory) continue;
+
+    if (entry.name.startsWith("/") || entry.name.startsWith("\\")) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `contains an absolute path entry and cannot be safely extracted: ${entry.name}`,
+      );
+    }
+
+    if (hasPathTraversal(entry.name)) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `contains a path traversal entry and cannot be safely extracted: ${entry.name}`,
+      );
+    }
+
+    if (seenPaths.has(entry.name)) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `contains duplicate entry '${entry.name}' and cannot be safely extracted`,
+      );
+    }
+    seenPaths.add(entry.name);
+
+    if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `entry '${entry.name}' uses unsupported compression method ${entry.compressionMethod}`,
+      );
+    }
+
+    entries.push({
+      relativePath: entry.name,
+      uncompressedSize: entry.uncompressedSize,
+      compressionMethod: entry.compressionMethod,
+      compressedData: entry.compressedData,
+    });
+    totalUncompressed += entry.uncompressedSize;
+  }
+
+  if (entries.length === 0) {
+    throw new AttachmentValidationError(
+      sourceFilename,
+      "is an empty ZIP archive (no file entries)",
+    );
+  }
+
+  if (entries.length > MAX_ZIP_FILES) {
+    throw new AttachmentValidationError(
+      sourceFilename,
+      `contains ${entries.length} files (limit: ${MAX_ZIP_FILES})`,
+    );
+  }
+
+  if (totalUncompressed > MAX_ZIP_EXTRACTED_SIZE) {
+    const sizeMb = (totalUncompressed / (1024 * 1024)).toFixed(1);
+    const limitMb = (MAX_ZIP_EXTRACTED_SIZE / (1024 * 1024)).toFixed(0);
+    throw new AttachmentValidationError(
+      sourceFilename,
+      `would extract to ${sizeMb} MB (limit: ${limitMb} MB)`,
+    );
+  }
+
+  return entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+
+// ── Decompression ────────────────────────────────────────────────────
+
+/**
+ * Decompress a validated entry, enforcing its declared uncompressed size.
+ *
+ * The size cap in parseAndValidateZip budgets *declared* sizes, which the
+ * archive author controls — a crafted archive can declare 1 KB and inflate
+ * to gigabytes. Enforcement is therefore two-sided and fail-hard: inflation
+ * aborts the moment output exceeds the declaration, and an undershoot (or a
+ * stored payload whose length disagrees) fails too, because a manifest that
+ * misdescribes its own contents is exactly the corrupt-input class this
+ * module must never extract from.
+ */
+export async function decompressEntry(
+  entry: ValidatedZipEntry,
+  sourceFilename: string,
+): Promise<Buffer> {
+  const declared = entry.uncompressedSize;
+
+  if (entry.compressionMethod === 0) {
+    if (entry.compressedData.length !== declared) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `entry '${entry.relativePath}' payload is ${entry.compressedData.length} bytes ` +
+        `but the archive declares ${declared} — corrupt or crafted archive`,
+      );
+    }
+    return Buffer.from(entry.compressedData);
+  }
+
+  // Deflate — the only other method parseAndValidateZip admits.
+  return new Promise<Buffer>((resolve, reject) => {
+    const inflate = createInflateRaw();
+    const chunks: Buffer[] = [];
+    let produced = 0;
+    inflate.on("data", (chunk: Buffer) => {
+      produced += chunk.length;
+      if (produced > declared) {
+        inflate.destroy();
+        reject(new AttachmentValidationError(
+          sourceFilename,
+          `entry '${entry.relativePath}' decompresses past its declared size of ` +
+          `${declared} bytes — corrupt or crafted archive`,
+        ));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    inflate.on("end", () => {
+      if (produced !== declared) {
+        reject(new AttachmentValidationError(
+          sourceFilename,
+          `entry '${entry.relativePath}' decompressed to ${produced} bytes ` +
+          `but the archive declares ${declared} — corrupt or crafted archive`,
+        ));
+        return;
+      }
+      resolve(Buffer.concat(chunks));
+    });
+    inflate.on("error", reject);
+    inflate.end(Buffer.from(entry.compressedData));
+  });
+}
+
+function hasPathTraversal(filePath: string): boolean {
+  const normalized = posix.normalize(filePath);
+  if (normalized.startsWith("../") || normalized === "..") return true;
+
+  const segments = filePath.split(/[/\\]/);
+  for (const seg of segments) {
+    if (seg === "..") return true;
+  }
+
+  return false;
+}

package/src/shared/connect-backfill.ts

@@ -21,6 +21,7 @@
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
 import { resolveMcpServers } from "./mcp-resolver.js";
 import type { McpTransportPosture } from "./mcp-transport-guard.js";
+import { withTimeout } from "./with-timeout.js";
 import type { StigmerClient } from "../client/stigmer-client.js";
 import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 
@@ -98,17 +99,14 @@ export async function backfillMcpServersIfNeeded(
       );
       onHeartbeat?.();
 
-      const updated = await Promise.race([
-        client.connectMcpServer(serverId, org, runtimeEnv),
-        new Promise<never>((_, reject) =>
-          setTimeout(
-            () => reject(new Error(
-              `Connect timed out after ${CONNECT_TIMEOUT_MS / 1000}s`,
-            )),
-            CONNECT_TIMEOUT_MS,
-          ),
-        ),
-      ]);
+      // Bounded through the shared helper so the timer is cleared when the
+      // connect wins; a bare `setTimeout` in a `Promise.race` stays armed and
+      // holds the event loop open for the full bound (stigmer#1008).
+      const updated = await withTimeout(
+        CONNECT_TIMEOUT_MS,
+        `Connect timed out after ${CONNECT_TIMEOUT_MS / 1000}s`,
+        () => client.connectMcpServer(serverId, org, runtimeEnv),
+      );
 
       const toolCount = updated.status?.discoveredCapabilities?.tools.length ?? 0;
       const approvalCount = updated.status?.toolApprovals?.length ?? 0;

package/src/shared/cost-guard.ts

@@ -13,8 +13,8 @@
  * same clean-cancel pattern the stall watchdog and first-denial stop use.
  * Slightly harsher than native by construction; both harnesses terminate with
  * the same honesty semantics (EXECUTION_TERMINATED, work checkpointed, the
- * conversation continues on the next message — the recursion-limit precedent
- * in execute-deep-agent/streaming-terminal.ts).
+ * conversation continues on the next message — the recursion-limit precedent,
+ * `harness/terminal-table.ts` `toolCallLimitArm`).
  *
  * The running figure is the usage accumulator's local pricing-table estimate
  * (authoritative billing is the BiDi proxy). That is the same estimation
@@ -34,7 +34,7 @@ export function costCapExceeded(maxCostUsd: number, estimatedCostUsd: number): b
 
 /**
  * Stable prefix of the cost-limit terminal error. Mirrors the cross-repo
- * pattern of TOOL_CALL_LIMIT_ERROR_PREFIX (streaming-terminal.ts): consumers
+ * pattern of TOOL_CALL_LIMIT_ERROR_PREFIX (tool-rounds.ts): consumers
  * that need to distinguish "ran out of cost budget" from other TERMINATED
  * causes can match on this prefix, because AgentExecutionStatus carries no
  * structured termination reason. Do not reword without checking consumers.

package/src/shared/execution-status-writer.ts

@@ -2,10 +2,10 @@
  * Shared interface for proto mutation consumed by side-effect classes
  * (InlinePublisher, WriteBackCoordinator) and streaming loops.
  *
- * The deep-agent harness implements it on its v2 StatusBuilder and
- * V3StatusBuilder; the Cursor harness — which mutates a bare status proto
- * with no builder — uses {@link statusProtoWriter}. Side-effect classes
- * depend only on this interface, never on a specific implementation.
+ * The deep-agent harness implements it on its `V3StatusBuilder`; the Cursor
+ * harness — which mutates a bare status proto with no builder — uses
+ * {@link statusProtoWriter}. Side-effect classes depend only on this
+ * interface, never on a specific implementation.
  */
 
 import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
@@ -28,7 +28,7 @@ export interface ExecutionStatusWriter {
  * concern the direct-mutation style has no use for, so it stays `false`.
  *
  * Write-backs upsert by `workspaceEntryName` — the same contract as the
- * deep-agent `StatusBuilder.addWriteBack`: each git-backed workspace entry
+ * deep-agent `V3StatusBuilder.addWriteBack`: each git-backed workspace entry
  * carries at most one record, progressing through phases.
  */
 export function statusProtoWriter(status: AgentExecutionStatus): ExecutionStatusWriter {

package/src/shared/extract-structured-output.ts

@@ -1,19 +1,20 @@
 /**
  * Tier-2 structured-output extraction for a harness turn.
  *
- * Harness-agnostic: the Cursor activity is today's only caller and the turn
- * runtime takes it over in S2 M3 (the native harness has no tier 2 today).
+ * Harness-agnostic, and called from one place: the turn runtime's epilogue
+ * (`harness/run-turn.ts` `extractStructuredOutputFromText`), so both
+ * harnesses have it — Cursor since S2 M3, native since S3 M2a (pinned by the
+ * native hermetic `structured-output` tier-2 arm since M2b, Q-S3-7).
  *
  * When tier-1 text extraction (shared/extract-json.ts) cannot find JSON in
  * the agent's free-text response, this tier asks an economy-tier LLM to
  * extract it via withStructuredOutput (function-calling), which guarantees
  * schema-conformant output through the API's tool-use mechanism.
  *
- * Lives in its own module (rather than inside execute-cursor/index.ts) so
- * the LangChain construction path stays out of the Cursor activity's module
- * graph until a run actually needs tier 2 — index.ts imports this module
- * lazily at the call site, mirroring its tier-1 import, which is what
- * bundle-slim's deferred evaluation preserves.
+ * Lives in its own module so the LangChain construction path stays out of
+ * the runtime's module graph until a run actually needs tier 2 — the
+ * runtime imports this module lazily at the call site, mirroring its tier-1
+ * import, which is what bundle-slim's deferred evaluation preserves.
  */
 
 import type { Config } from "../config.js";

package/src/shared/filereview/__tests__/capture.test.ts

@@ -1,10 +1,12 @@
 /**
  * @regression file-hitl-phase0 — pins file-edit HITL fixes #7, #8, #9 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
  *
- * Tests the harness-agnostic capture orchestration directly with the deep-agent
- * harness id (the Cursor adapter is covered by execute-cursor/capture-flow.test).
- * Confirms producer parity: the deep-agent authors IDENTICAL ledger entries to
- * Cursor through this seam — only `harness_id` differs — and that with no
+ * Tests the harness-agnostic capture orchestration directly, under one
+ * harness id (since S3 M4 the runtime is the ONE caller for every harness,
+ * `harness/capture.ts`; until then each adapter called this seam and the
+ * Cursor side had its own test, `execute-cursor/capture-flow.test.ts`, whose
+ * three reconcile arms no other file carried moved here). Confirms that the
+ * ledger entries depend on nothing but `harness_id` and that with no
  * excludePaths every changed file is captured. Runs against a REAL temp git repo.
  */
 
@@ -333,6 +335,86 @@ function candidateCompleteness(status: AgentExecutionStatus): DiffCompleteness |
     : undefined;
 }
 
+describe("capture reconcile — the decision rules the resume enforces (moved from execute-cursor/capture-flow.test at S3 M4)", () => {
+  async function captureTwoFileTurn(status: AgentExecutionStatus): Promise<void> {
+    const baseline = await captureBaselineToLedger({ status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, harnessId: HARNESS });
+    await write("notes.md", "planton notes\n");
+    await write("src/main.ts", "export const x = 99;\n");
+    await captureCandidateToLedger({ status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, baselineTree: baseline, harnessId: HARNESS });
+  }
+
+  it("reconstructs an approved file from the ref even if the tree was reset (retry-safe)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({ status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, harnessId: HARNESS });
+    await write("notes.md", "planton notes\n");
+    await captureCandidateToLedger({ status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, baselineTree: baseline, harnessId: HARNESS });
+    const changeSet = decidedChangeSet(status, { "notes.md": FileDecisionAction.APPROVE });
+
+    // A tree reset before the resume (a Temporal retry, a sandbox recycle):
+    // the approved bytes are gone from disk, the pinned refs survive.
+    await write("notes.md", "platon notes\n");
+
+    const result = await applyCaptureDecisions({ status, gitRoot: repo, executionId: EXEC_ID, changeSet, harnessId: HARNESS });
+
+    expect(result.approvedPaths).toEqual(["notes.md"]);
+    // Reconcile-from-refs re-asserts the approved "after" bytes whatever the tree holds.
+    expect(await read("notes.md")).toBe("planton notes\n");
+  });
+
+  it("CHANGE_SET-scoped approval covers all files; a FILE decision overrides it (most-specific-wins)", async () => {
+    const status = newStatus();
+    await captureTwoFileTurn(status);
+    const changes = candidateChanges(status);
+    const mainChange = changes.find((c) => c.pathAfter === "src/main.ts")!;
+    const changeSet = create(FileChangeSetSchema, {
+      id: CHANGE_SET_ID,
+      changes,
+      status: FileChangeSetStatus.DECIDED,
+      decisions: [
+        // CHANGE_SET: approve everything…
+        create(FileDecisionSchema, { id: "d-cs", changeSetId: CHANGE_SET_ID, scope: FileDecisionScope.CHANGE_SET, action: FileDecisionAction.APPROVE }),
+        // …but a FILE decision rejects src/main.ts (more specific wins).
+        create(FileDecisionSchema, {
+          id: "d-file",
+          changeSetId: CHANGE_SET_ID,
+          scope: FileDecisionScope.FILE,
+          fileChangeId: mainChange.id,
+          action: FileDecisionAction.REJECT,
+          expectedDigest: mainChange.fileDigest,
+        }),
+      ],
+    });
+
+    const result = await applyCaptureDecisions({ status, gitRoot: repo, executionId: EXEC_ID, changeSet, harnessId: HARNESS });
+
+    expect(result.approvedPaths).toEqual(["notes.md"]);
+    expect(result.rejectedPaths).toEqual(["src/main.ts"]);
+    expect(await read("notes.md")).toBe("planton notes\n");
+    expect(await read("src/main.ts")).toBe("export const x = 1;\n");
+  });
+
+  it("refuses to apply and authors FAILED(HASH_MISMATCH) when on-disk bytes diverge from the approved digest", async () => {
+    const status = newStatus();
+    await captureTwoFileTurn(status);
+    // The reviewer approved both, but the recorded after_sha256 for notes.md no
+    // longer matches the captured bytes (what-you-approve-is-what-applies fails).
+    const changeSet = decidedChangeSet(status, { "notes.md": FileDecisionAction.APPROVE, "src/main.ts": FileDecisionAction.APPROVE });
+    changeSet.changes.find((c) => c.pathAfter === "notes.md")!.afterSha256 = "deadbeef".repeat(8);
+
+    const result = await applyCaptureDecisions({ status, gitRoot: repo, executionId: EXEC_ID, changeSet, harnessId: HARNESS });
+
+    expect(result.failed).toBe(true);
+    expect(result.failureDetail).toContain("notes.md");
+    // NOTHING was applied (a partial apply under a verification failure is
+    // worse than none): src/main.ts still holds its un-reconciled (after) bytes.
+    expect(await read("src/main.ts")).toBe("export const x = 99;\n");
+    const failed = eventsOfType(status, FileReviewEventType.FAILED);
+    expect(failed).toHaveLength(1);
+    if (failed[0]!.payload.case === "failed") expect(failed[0]!.payload.value.detail).toContain("notes.md");
+    expect(eventsOfType(status, FileReviewEventType.RECONCILED)).toHaveLength(0);
+  });
+});
+
 describe("capture orchestration — hybrid git + CAS (Phase 3)", () => {
   it("composes git-tracked and CAS captures into one HYBRID change set", async () => {
     const status = newStatus();

package/src/shared/filereview/__tests__/cas-progress.test.ts

@@ -16,7 +16,8 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { FileChangeKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { createCasProgressSubstrate, type CasTouchedSnapshot } from "../cas-progress.js";
+import { createCasProgressSubstrate } from "../cas-progress.js";
+import type { CasTouchedSnapshot } from "../cas-touched.js";
 import { LINE_COUNT_MAX_BYTES } from "../line-counts.js";
 import type { ProgressEntry } from "../progress.js";
 

package/src/shared/filereview/cas-progress.ts

@@ -43,26 +43,12 @@ import {
   type ProgressSubstrate,
 } from "./progress.js";
 import { partitionIgnoredPathsBySecret } from "./secret-paths.js";
+import type { CasTouchedReader } from "./cas-touched.js";
 
-/**
- * A snapshot of the turn's CAS-observed paths, read on each capture:
- *  - `before`: first-touched paths' pre-turn bytes (`null` = the path did not
- *    exist before → an ADD). The KEYS are the touched-path set.
- *  - `blockedSecretPaths`: paths the gate hard-blocked as secret-like — excluded
- *    from capture.
- *
- * Deep-agent supplies a synchronous copy of its live `CasCaptureObserver`; Cursor
- * supplies a reader over the hook's on-disk sidecar. The reader MUST return an
- * atomic snapshot (copy the live map before any await) so a concurrent sub-agent
- * write cannot mutate it mid-capture.
- */
-export interface CasTouchedSnapshot {
-  readonly before: ReadonlyMap<string, Uint8Array | null>;
-  readonly blockedSecretPaths: ReadonlySet<string>;
-}
-
-/** Produces a {@link CasTouchedSnapshot} for one capture. */
-export type CasTouchedReader = () => CasTouchedSnapshot | Promise<CasTouchedSnapshot>;
+// The snapshot this substrate reads (`CasTouchedSnapshot`) and the reader that
+// produces it live in `cas-touched.ts`, the one home of "what the engine
+// observed touching CAS-owned paths": the turn-boundary capture reads the same
+// snapshot, so neither consumer owns the shape.
 
 /**
  * The CAS progress substrate. Reads the touched set on each capture, computes

package/src/shared/filereview/cas-touched.ts

@@ -0,0 +1,89 @@
+/**
+ * What the engine observed touching CAS-owned paths this turn — the one fact
+ * about a turn's file changes that the runtime cannot read from the tree and
+ * the engine cannot help knowing.
+ *
+ * In a git work tree the tracked changes are a `git diff` against the pinned
+ * baseline; the gitignored ones are invisible to git, and in a non-git
+ * workspace EVERY change is. For those paths the only record of the
+ * pre-turn bytes is the one taken at mutation time, by whatever sits between
+ * the engine and the disk: the deep-agent's `CasCaptureObserver` (fed by its
+ * filesystem backend and its approval gate) or the Cursor hook's on-disk
+ * sidecar. Both produce this one snapshot shape, and both consumers read it:
+ * the mid-run progress slice (`cas-progress.ts`) and the turn-boundary
+ * capture ({@link buildCasTurnCaptures}), which composes it into the
+ * {@link CasPathCapture}s the CAS substrate stores.
+ *
+ * Until S3 M4 each harness carried its own copy of `buildCasTurnCaptures`
+ * beside its observation source; the copies were byte-near-identical
+ * (F-M4-P6) and now live here once. The AFTER bytes are always re-read from
+ * disk at composition time (the authoritative net result of the turn), so
+ * many edits to one path collapse to one before/after.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { FileCaptureClass } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { CasPathCapture } from "./cas-substrate.js";
+import { partitionIgnoredPathsBySecret } from "./secret-paths.js";
+
+/**
+ * The CAS-owned paths touched so far this turn: pre-turn bytes per
+ * first-touched path (`null` = the path did not exist → an ADD) and the paths
+ * the gate hard-blocked as secret-like (never applied, never captured; the
+ * boundary authors a content-less entry for each). Keyed workspace-root-
+ * relative. A reader MUST return an atomic snapshot (copy the live map before
+ * any await) so a concurrent sub-agent write cannot mutate it mid-capture.
+ */
+export interface CasTouchedSnapshot {
+  readonly before: ReadonlyMap<string, Uint8Array | null>;
+  readonly blockedSecretPaths: ReadonlySet<string>;
+}
+
+/** Produces a {@link CasTouchedSnapshot} for one capture. */
+export type CasTouchedReader = () => CasTouchedSnapshot | Promise<CasTouchedSnapshot>;
+
+/**
+ * Compose the turn's CAS captures from what the engine observed: for each
+ * observed path the before-bytes come from the snapshot and the after-bytes
+ * are re-read from disk now (`null` = the file is gone). Secret-like paths are
+ * diverted to `unreviewablePaths` and their before-bytes dropped — the
+ * fail-closed backstop that holds even under the global bypass, where the
+ * gate did not run to block them up front ({@link partitionIgnoredPathsBySecret}
+ * is the one decision; this shell performs only the IO for the capturable
+ * set). `captureClass` is the turn's CAS substrate class — GIT_IGNORED_CAPTURED
+ * for a git work tree's ignored paths, NON_GIT_CAS for a non-git workspace
+ * (where these ARE the whole change set) — so each captured path carries its
+ * true provenance. An empty snapshot yields empty results and leaves the
+ * shared capture unchanged.
+ */
+export async function buildCasTurnCaptures(
+  snapshot: CasTouchedSnapshot,
+  workspaceRoot: string,
+  captureClass: FileCaptureClass,
+): Promise<{ casCaptures: CasPathCapture[]; unreviewablePaths: string[] }> {
+  const { capturablePaths, unreviewablePaths } = partitionIgnoredPathsBySecret(
+    snapshot.before.keys(),
+    snapshot.blockedSecretPaths,
+  );
+  const casCaptures: CasPathCapture[] = [];
+  for (const relPath of capturablePaths) {
+    const after = await readFileOrNull(join(workspaceRoot, relPath));
+    casCaptures.push({
+      path: relPath,
+      before: snapshot.before.get(relPath) ?? null,
+      after,
+      captureClass,
+    });
+  }
+  return { casCaptures, unreviewablePaths: [...unreviewablePaths] };
+}
+
+/** Raw bytes of a file, or `null` when it does not exist (a DELETE, or an ADD since removed). */
+async function readFileOrNull(absolutePath: string): Promise<Uint8Array | null> {
+  try {
+    return await readFile(absolutePath);
+  } catch {
+    return null;
+  }
+}

package/src/shared/filereview/index.ts

@@ -56,11 +56,13 @@ export {
   type ProgressSubstrate,
 } from "./progress.js";
 
+export { createCasProgressSubstrate } from "./cas-progress.js";
+
 export {
-  createCasProgressSubstrate,
+  buildCasTurnCaptures,
   type CasTouchedReader,
   type CasTouchedSnapshot,
-} from "./cas-progress.js";
+} from "./cas-touched.js";
 
 export {
   countLineChanges,