@visual-z/xeno 0.2.1 → 0.3.0

package/src/store/file-checkpoints.ts

@@ -0,0 +1,104 @@
+/** P.3: bounded path operations with durable before-images and conflict checks. */
+import { lstat, readFile, mkdir, open, rename, rm } from "node:fs/promises";
+import { resolve, relative, dirname, join, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { blobAddress, putBlob, getBlobBytes, verifyBlob } from "./blobs.ts";
+import { sameVersion, changedPaths, type FileVersion, type FileChanges } from "../core/checkpoints.ts";
+import { ToolFault, NOT_STARTED, READ_ATTEMPTED, failureFromError } from "../core/tool-failure.ts";
+
+export async function editablePath(root: string, path: string): Promise<string> {
+  const base = resolve(root), absolute = resolve(base, path), rel = relative(base, absolute);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || resolve(rel) === rel ||
+      rel.split(sep).some(part => part === ".git" || part === ".xeno")) throw new ToolFault("permission_denied", `unsafe file checkpoint path: ${path}`, NOT_STARTED);
+  let current = base;
+  for (const part of rel.split(sep)) {
+    current = join(current, part);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink() || current !== absolute && !info.isDirectory() || current === absolute && (!info.isFile() || info.nlink > 1))
+        throw new ToolFault("permission_denied", `unsupported file checkpoint path: ${path}`, NOT_STARTED);
+    } catch (error) { if ((error as { code?: string }).code !== "ENOENT") throw error; }
+  }
+  return absolute;
+}
+
+export async function readEditableFile(root: string, path: string): Promise<{ bytes: Uint8Array | null; version: FileVersion }> {
+  const absolute = await editablePath(root, path);
+  try {
+    const info = await lstat(absolute);
+    const bytes = await readFile(absolute);
+    return { bytes, version: { sha256: blobAddress(bytes), mode: info.mode & 0o777 } };
+  } catch (error) {
+    if ((error as { code?: string }).code === "ENOENT") return { bytes: null, version: null };
+    const diagnostic = failureFromError(error, READ_ATTEMPTED);
+    throw new ToolFault(diagnostic.code, diagnostic.message, READ_ATTEMPTED);
+  }
+}
+
+/** The prepared record is durable before rename; cancellation and conflicts leave bytes untouched. */
+export async function replaceFile(root: string, path: string, expected: FileVersion, bytes: Uint8Array | null,
+  mode: number, signal?: AbortSignal): Promise<void> {
+  const absolute = await editablePath(root, path);
+  if (signal?.aborted) throw new ToolFault("cancelled", "file operation cancelled", NOT_STARTED);
+  if (!sameVersion((await readEditableFile(root, path)).version, expected)) throw new ToolFault("version_mismatch", `file conflict: ${path}; read it again before editing`, READ_ATTEMPTED, { recover: { tool: "read", input: { path } } });
+  if (bytes === null) {
+    if (expected === null) return;
+    await rm(absolute);
+    const directory = await open(dirname(absolute), "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+    return;
+  }
+  await mkdir(dirname(absolute), { recursive: true });
+  const temporary = join(dirname(absolute), `.xeno-edit-${randomUUID()}`);
+  try {
+    const file = await open(temporary, "wx", mode);
+    try { await file.writeFile(bytes); await file.chmod(mode); await file.sync(); } finally { await file.close(); }
+    await editablePath(root, path);
+    if (signal?.aborted) throw new ToolFault("cancelled", "file operation cancelled", READ_ATTEMPTED);
+    if (!sameVersion((await readEditableFile(root, path)).version, expected)) throw new ToolFault("version_mismatch", `file conflict: ${path}; read it again before editing`, READ_ATTEMPTED, { recover: { tool: "read", input: { path } } });
+    await rename(temporary, absolute);
+    const directory = await open(dirname(absolute), "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  } finally { await rm(temporary, { force: true }); }
+}
+
+export async function archiveEdit(blobs: string, before: Uint8Array | null, after: Uint8Array): Promise<void> {
+  if (before !== null) await putBlob(blobs, before);
+  await putBlob(blobs, after);
+}
+
+export async function preflightChanges(root: string, blobs: string, changes: FileChanges): Promise<void> {
+  for (const path of changedPaths(changes)) {
+    const change = changes[path]!;
+    if (!sameVersion((await readEditableFile(root, path)).version, change.before)) throw new Error(`file conflict: ${path}; external changes were preserved`);
+    if (change.after && !await verifyBlob(blobs, change.after.sha256)) throw new Error(`missing checkpoint object: ${path}`);
+    if (change.before && !await verifyBlob(blobs, change.before.sha256)) throw new Error(`missing recovery object: ${path}`);
+  }
+}
+
+/** Preflight the complete plan, then compensate partial writes if an individual replacement fails. */
+export async function applyFileChanges(root: string, blobs: string, changes: FileChanges): Promise<void> {
+  await preflightChanges(root, blobs, changes);
+  const applied: string[] = [];
+  try {
+    for (const path of changedPaths(changes)) {
+      const { before, after } = changes[path]!;
+      const bytes = after === null ? null : await getBlobBytes(blobs, after.sha256);
+      if (after && bytes === null) throw new Error(`missing checkpoint object: ${path}`);
+      await replaceFile(root, path, before, bytes, after?.mode ?? 0o644);
+      applied.push(path);
+    }
+  } catch (error) {
+    const failures: string[] = [];
+    for (const path of applied.reverse()) {
+      const { before, after } = changes[path]!;
+      try {
+        const bytes = before === null ? null : await getBlobBytes(blobs, before.sha256);
+        if (before && bytes === null) throw new Error("missing recovery object");
+        await replaceFile(root, path, after, bytes, before?.mode ?? 0o644);
+      } catch { failures.push(path); }
+    }
+    if (failures.length) throw new Error(`restore interrupted; inspect partially applied paths: ${failures.join(", ")}; ${String(error)}`);
+    throw error;
+  }
+}

package/src/store/file-index.ts

@@ -23,11 +23,14 @@ export const MAX_INDEX_ENTRIES = 20_000;
 export interface FileIndex {
   readonly paths: readonly string[];
   readonly truncated: boolean;
+  readonly issues?: readonly { code: string; path?: string }[];
 }
 
 export interface IndexOptions {
   readonly ignore?: readonly string[];
   readonly maxEntries?: number;
+  readonly deadline?: number;
+  readonly signal?: AbortSignal;
 }
 
 function isIgnored(rel: string, ignore: readonly string[]): boolean {
@@ -40,17 +43,25 @@ export async function buildFileIndex(root: string, opts: IndexOptions = {}): Pro
   const max = opts.maxEntries ?? MAX_INDEX_ENTRIES;
   const paths: string[] = [];
   let truncated = false;
+  const issues: { code: string; path?: string }[] = [];
 
   async function walk(dir: string): Promise<void> {
     if (truncated) return;
+    if (opts.signal?.aborted || opts.deadline !== undefined && performance.now() >= opts.deadline) {
+      truncated = true; issues.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); return;
+    }
     let entries: Dirent[];
     try {
       entries = await readdir(dir, { withFileTypes: true });
     } catch {
+      issues.push({ code: "unreadable_directory", path: relative(root, dir) || "." });
       return;
     }
     for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
       if (truncated) return;
+      if (opts.signal?.aborted || opts.deadline !== undefined && performance.now() >= opts.deadline) {
+        truncated = true; issues.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); return;
+      }
       // Do not follow symlinks: a link to / walks the disk, and
       // node_modules/.bin is nothing but links. Same judgment as
       // feat-workspace-snapshots, which also skips them via isFile().
@@ -65,6 +76,7 @@ export async function buildFileIndex(root: string, opts: IndexOptions = {}): Pro
       if (!entry.isFile()) continue;
       if (paths.length >= max) {
         truncated = true;
+        issues.push({ code: "file_index_limit" });
         return;
       }
       paths.push(rel.split(sep).join("/"));
@@ -72,7 +84,7 @@ export async function buildFileIndex(root: string, opts: IndexOptions = {}): Pro
   }
 
   await walk(root);
-  return { paths, truncated };
+  return { paths, truncated, ...(issues.length ? { issues } : {}) };
 }
 
 export function indexTruncationNote(index: FileIndex): string | null {

package/src/store/git-checkpoints.ts

@@ -0,0 +1,67 @@
+/** P.3/OpenCode v2: retained private index, scoped capture, path-only CAS export. */
+import { mkdir, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { blobAddress, putBlob } from "./blobs.ts";
+import { gitBytes, sourceInventory } from "./workspace-observation.ts";
+import type { FileChanges, FileVersion } from "../core/checkpoints.ts";
+import { atomicWrite } from "./atomic.ts";
+
+const text = (bytes: Uint8Array) => new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+export interface GitCheckpoint { tree: string; modes: ReadonlyMap<string, number>; }
+export class GitCheckpoints {
+  readonly root: string;
+  private readonly ownedPaths: readonly string[];
+  private initialized = false;
+  readonly directory: string;
+  constructor(root: string, storage: string, ownedPaths: readonly string[] = []) {
+    this.root = root; this.directory = join(storage, "git-checkpoints", blobAddress(root)); this.ownedPaths = ownedPaths;
+  }
+  private git(args: readonly string[], input?: Uint8Array, signal?: AbortSignal) {
+    return gitBytes(this.root, ["--literal-pathspecs", "-c", "core.autocrlf=false", "-c", "core.safecrlf=false", "-c", "core.attributesFile=/dev/null", "-c", "core.hooksPath=/dev/null", "-c", "gc.auto=0", ...args], input, signal,
+      { GIT_DIR: this.directory, GIT_WORK_TREE: this.root, GIT_INDEX_FILE: join(this.directory, "index"), GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_ATTR_NOSYSTEM: "1" });
+  }
+  async capture(signal?: AbortSignal): Promise<GitCheckpoint> {
+    const inventory = await sourceInventory(this.root, signal, true, this.ownedPaths);
+    if (!this.initialized) {
+      await mkdir(this.directory, { recursive: true });
+      await gitBytes(this.root, ["init", "--bare", "--quiet", this.directory], undefined, signal);
+      // Git's highest-precedence attributes keep checkpoint bytes exact, even if the project uses LFS, encoding or EOL conversion.
+      await atomicWrite(join(this.directory, "info", "attributes"), "* -text -crlf -ident -filter -working-tree-encoding -eol\n");
+      this.initialized = true;
+    }
+    // Git trees retain only the executable bit; recovery needs the observed POSIX permissions as well.
+    const modes = new Map<string, number>();
+    for (const path of inventory.paths) {
+      const info = await lstat(join(this.root, path));
+      if (!info.isFile() || info.nlink > 1) throw new Error(`unsupported Git checkpoint path: ${path}`);
+      modes.set(path, info.mode & 0o777);
+    }
+    const previous = text(await this.git(["ls-files", "-z"], undefined, signal)).split("\0").filter(Boolean);
+    const present = new Set(inventory.paths);
+    const removed = previous.filter(path => !present.has(path));
+    if (removed.length) await this.git(["update-index", "--force-remove", "-z", "--stdin"], Buffer.from(removed.join("\0") + "\0"), signal);
+    // Feeding explicit paths avoids scanning ignored descendants and preserves names with newlines or leading dashes.
+    if (inventory.paths.length) await this.git(["add", "--force", "--pathspec-from-file=-", "--pathspec-file-nul"], Buffer.from(inventory.paths.join("\0") + "\0"), signal);
+    const tree = text(await this.git(["write-tree"], undefined, signal)).trim();
+    // Durable reachability is owned by Xeno, independent of the user's Git GC/index/HEAD.
+    await this.git(["update-ref", `refs/checkpoints/${tree}`, tree], undefined, signal);
+    return { tree, modes };
+  }
+  async changes(before: GitCheckpoint, after: GitCheckpoint, blobs: string, signal?: AbortSignal): Promise<FileChanges> {
+    const paths = new Set(before.tree === after.tree ? [] : text(await this.git(["diff-tree", "--no-renames", "--name-only", "-r", "-z", before.tree, after.tree], undefined, signal)).split("\0").filter(Boolean));
+    for (const [path, mode] of before.modes) if (mode !== after.modes.get(path)) paths.add(path);
+    for (const path of after.modes.keys()) if (!before.modes.has(path)) paths.add(path);
+    const version = async (snapshot: GitCheckpoint, path: string): Promise<FileVersion> => {
+      const entry = text(await this.git(["ls-tree", "-z", snapshot.tree, "--", path], undefined, signal));
+      if (!entry) return null;
+      const match = /^(100644|100755) blob ([a-f0-9]+)\t/.exec(entry);
+      const mode = snapshot.modes.get(path);
+      if (!match || mode === undefined) throw new Error(`unsupported Git checkpoint entry: ${path}`);
+      const bytes = await this.git(["cat-file", "blob", match[2]!], undefined, signal);
+      return { sha256: await putBlob(blobs, bytes), mode };
+    };
+    const changes: FileChanges = Object.create(null) as FileChanges;
+    for (const path of paths) changes[path] = { before: await version(before, path), after: await version(after, path) };
+    return changes;
+  }
+}

package/src/store/observations.ts

@@ -53,41 +53,72 @@ const EXIT_DRAIN_MS = 1_000;
 async function spoolMerged(
   dir: string, streams: readonly ReadableStream<Uint8Array>[], exited: Promise<number>,
   onOutput?: (chunk: Uint8Array) => void,
-): Promise<string> {
+  separate = false,
+  limitBytes?: number,
+): Promise<{ path: string; channels: string[]; complete: boolean }> {
   await mkdir(dir, { recursive: true });
   const path = join(dir, `.${randomUUID()}.stream`);
   const file = await open(path, "wx", 0o600);
+  const channels: string[] = [];
+  const channelFiles: Awaited<ReturnType<typeof open>>[] = [];
+  try {
+    if (separate) for (let i = 0; i < streams.length; i++) {
+      const channel = `${path}.${i}`;
+      channelFiles.push(await open(channel, "wx", 0o600)); channels.push(channel);
+    }
+  } catch (error) {
+    await Promise.allSettled([file.close(), ...channelFiles.map(item => item.close())]);
+    await Promise.all([path, ...channels].map(item => rm(item, { force: true })));
+    throw error;
+  }
   const readers = streams.map((stream) => stream.getReader());
   let queue: Promise<unknown> = Promise.resolve();
   let exitedAt: number | undefined;
   let idle: ReturnType<typeof setTimeout> | undefined;
   let drain: ReturnType<typeof setTimeout> | undefined;
-  const stop = () => { for (const reader of readers) reader.cancel().catch(() => {}); };
+  let finished = false, complete = true, capturedBytes = 0;
+  const stop = () => { if (finished) return; complete = false; for (const reader of readers) reader.cancel().catch(() => {}); };
   const armIdle = () => {
-    if (exitedAt === undefined) return;
+    if (finished || exitedAt === undefined) return;
     clearTimeout(idle);
     idle = setTimeout(stop, EXIT_IDLE_MS);
   };
-  void exited.then(() => { exitedAt = performance.now(); armIdle(); drain = setTimeout(stop, EXIT_DRAIN_MS); }, () => {});
+  void exited.then(() => { if (finished) return; exitedAt = performance.now(); armIdle(); drain = setTimeout(stop, EXIT_DRAIN_MS); }, () => {});
   try {
-    const drained = await Promise.allSettled(readers.map(async (reader) => {
-      for (;;) {
-        const result = await reader.read();
-        if (result.done) return;
-        armIdle();
-        queue = queue.then(async () => { await file.writeFile(result.value); onOutput?.(result.value); });
-        await queue;
-      }
+    const drained = await Promise.allSettled(readers.map(async (reader, index) => {
+      try {
+        for (;;) {
+          const result = await reader.read();
+          if (result.done) return;
+          armIdle();
+          queue = queue.then(async () => {
+            await file.writeFile(result.value);
+            await channelFiles[index]?.writeFile(result.value);
+            onOutput?.(result.value);
+            capturedBytes += result.value.byteLength;
+            // Retain every delivered chunk, then cancel both readers. At most
+            // the in-flight crossing chunks exceed the bound; SIGTERM grace
+            // cannot turn an output limit into unlimited spool growth (R6).
+            if (limitBytes !== undefined && capturedBytes > limitBytes) stop();
+          });
+          await queue;
+        }
+      } catch (error) { stop(); throw error; }
     }));
     await queue;
     for (const result of drained) if (result.status === "rejected") throw result.reason;
-  } catch (error) { await file.close(); await rm(path, { force: true }); throw error; }
+  } catch (error) {
+    await Promise.allSettled([file.close(), ...channelFiles.map(item => item.close())]);
+    await Promise.all([path, ...channels].map(item => rm(item, { force: true })));
+    throw error;
+  }
   finally {
+    finished = true;
     clearTimeout(idle); clearTimeout(drain);
     for (const reader of readers) reader.releaseLock();
   }
-  await file.close();
-  return path;
+  await Promise.all([file.close(), ...channelFiles.map(item => item.close())]);
+  return { path, channels, complete };
 }
 
 /** Last `limit` bytes of a stream, in O(limit) memory however long it runs. */
@@ -167,17 +198,27 @@ export async function captureCommandObservation(
   dir: string, stdout: ReadableStream<Uint8Array>, stderr: ReadableStream<Uint8Array>,
   exited: Promise<number>, previewBytes: number,
   onOutput?: (chunk: Uint8Array) => void,
-): Promise<ArchivedObservation & { exit: number; prefixBytes: number }> {
-  const merged = await spoolMerged(dir, [stdout, stderr], exited, onOutput);
+  separate = false,
+  limitBytes?: number,
+): Promise<ArchivedObservation & { exit: number; prefixBytes: number; channels: ArtifactRef[]; capture: "complete" | "partial" }> {
+  const merged = await spoolMerged(dir, [stdout, stderr], exited, onOutput, separate, limitBytes);
   try {
     const exit = await exited;
     const prefix = new TextEncoder().encode(`exit ${exit}\n`);
     async function* combined(): AsyncGenerator<Uint8Array> {
       yield prefix;
-      for await (const chunk of createReadStream(merged)) yield chunk as Uint8Array;
+      for await (const chunk of createReadStream(merged.path)) yield chunk as Uint8Array;
+    }
+    async function* channel(path: string): AsyncGenerator<Uint8Array> {
+      for await (const chunk of createReadStream(path)) yield chunk as Uint8Array;
     }
-    return { ...await archiveObservation(dir, combined(), previewBytes), exit, prefixBytes: prefix.byteLength };
+    // Drain all archive attempts before removing their source files, including failures.
+    const attempts = await Promise.allSettled([archiveObservation(dir, combined(), previewBytes),
+      ...merged.channels.map(path => archiveObservation(dir, channel(path), 0))]);
+    const stored = attempts.map(result => { if (result.status === "rejected") throw result.reason; return result.value; });
+    return { ...stored[0]!, exit, prefixBytes: prefix.byteLength, channels: stored.slice(1).map(item => item.ref),
+      capture: merged.complete ? "complete" : "partial" };
   } finally {
-    await rm(merged, { force: true });
+    await Promise.all([merged.path, ...merged.channels].map(path => rm(path, { force: true })));
   }
 }

package/src/store/process-receipts.ts

@@ -0,0 +1,34 @@
+/** R7/R8: data_ref is the original receipt, not permission to substitute current process/file state. */
+import type { LogEvent } from "../core/events.ts";
+import { isLogEvent } from "../core/event-validation.ts";
+import { readObservation } from "./observations.ts";
+
+// Assumed per-query metadata budget. Exhaustion is explicit unknown, never fallback to older success.
+export const PROCESS_RECEIPT_READ_BYTES = 8 * 1024 * 1024;
+export async function hydrateProcessReceipts(nodes: readonly { node: number; events: readonly LogEvent[] }[], archive: string):
+  Promise<{ node: number; events: LogEvent[] }[]> {
+  const calls = new Map<string, string>();
+  for (const part of nodes) for (const event of part.events) {
+    if (event.t === "tool_invocation") calls.set(event.call_id, event.name);
+    if (event.t === "assistant") for (const block of event.blocks) if (block.type === "tool_use") calls.set(block.call_id, block.name);
+  }
+  let remaining = PROCESS_RECEIPT_READ_BYTES;
+  const result: { node: number; events: LogEvent[] }[] = [];
+  for (const part of nodes) {
+    const events: LogEvent[] = [];
+    for (const event of part.events) {
+      if (event.t !== "tool_result" || !event.data_ref || !["exec_command", "write_stdin", "target"].includes(calls.get(event.call_id) ?? "")) { events.push(event); continue; }
+      const ref = event.data_ref;
+      if (ref.bytes > remaining) throw new Error("process receipt metadata exceeds observation budget; state remains unknown");
+      remaining -= ref.bytes;
+      const page = await readObservation(archive, ref.sha256, 0, Math.max(1, ref.bytes));
+      if (page.bytes !== ref.bytes || page.next !== null) throw new Error("process receipt metadata length mismatch");
+      const { data_ref: _ref, ...original } = event;
+      const restored: unknown = { ...original, data: JSON.parse(page.text) };
+      if (!isLogEvent(restored)) throw new Error("archived process receipt contradicts its original event");
+      events.push(restored);
+    }
+    result.push({ node: part.node, events });
+  }
+  return result;
+}

package/src/store/query-source.ts

@@ -3,38 +3,43 @@ import { lstat, open } from "node:fs/promises";
 import { constants } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
+import { ToolFault, NOT_STARTED, READ_ATTEMPTED } from "../core/tool-failure.ts";
+import { checkSourceCancellation } from "./source-cancellation.ts";
 
 // Assumed working-memory safety budget for the synchronous pure query engine.
 // Exceeding it is an explicit refusal, never a truncated calculation.
 export const MAX_QUERY_SOURCE_BYTES = 32 * 1024 * 1024;
-export async function readQuerySources(root: string, paths: unknown): Promise<{
+export async function readQuerySources(root: string, paths: unknown, signal?: AbortSignal): Promise<{
   text: string; sources: { path: string; sha256: string; bytes: number }[];
 }> {
-  if (!Array.isArray(paths) || paths.length === 0 || paths.length > 1024 || paths.some((p) => typeof p !== "string" || !p)) throw new Error("query paths must contain 1..1024 file paths in concatenation order");
+  if (!Array.isArray(paths) || paths.length === 0 || paths.length > 1024 || paths.some((p) => typeof p !== "string" || !p)) throw new ToolFault("invalid_input", "query paths must contain 1..1024 file paths in concatenation order", NOT_STARTED);
   const sources: { path: string; sha256: string; bytes: number }[] = [];
   const chunks: Uint8Array[] = [];
   let bytes = 0;
   for (const path of paths as string[]) {
+    checkSourceCancellation(signal);
     const absolute = resolve(root, path), rel = relative(root, absolute);
-    if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) throw new Error("query path escapes workspace");
+    if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) throw new ToolFault("permission_denied", "query path escapes workspace", READ_ATTEMPTED);
     let current = resolve(root);
     for (const part of rel.split(sep)) {
       current = resolve(current, part);
-      if ((await lstat(current)).isSymbolicLink()) throw new Error("query does not follow symbolic links");
+      if ((await lstat(current)).isSymbolicLink()) throw new ToolFault("permission_denied", "query does not follow symbolic links", READ_ATTEMPTED);
     }
-    const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
     try {
       const info = await file.stat();
-      if (!info.isFile()) throw new Error("query source must be a regular file");
-      if (bytes + info.size > MAX_QUERY_SOURCE_BYTES) throw new Error("query source exceeds 32 MiB resource budget; use a smaller input");
+      if (!info.isFile()) throw new ToolFault("invalid_input", "query source must be a regular file", READ_ATTEMPTED);
+      if (bytes + info.size > MAX_QUERY_SOURCE_BYTES) throw new ToolFault("invalid_input", "query source exceeds 32 MiB resource budget; use a smaller input", READ_ATTEMPTED);
       const hash = createHash("sha256");
       let sourceBytes = 0;
       for (;;) {
+        checkSourceCancellation(signal);
         const buffer = Buffer.alloc(Math.min(65536, MAX_QUERY_SOURCE_BYTES - bytes + 1));
         const result = await file.read(buffer, 0, buffer.length, null);
+        checkSourceCancellation(signal);
         if (result.bytesRead === 0) break;
         bytes += result.bytesRead; sourceBytes += result.bytesRead;
-        if (bytes > MAX_QUERY_SOURCE_BYTES) throw new Error("query source grew past resource budget");
+        if (bytes > MAX_QUERY_SOURCE_BYTES) throw new ToolFault("invalid_input", "query source grew past resource budget", READ_ATTEMPTED);
         const data = buffer.subarray(0, result.bytesRead); hash.update(data); chunks.push(data);
       }
       sources.push({ path: rel.split(sep).join("/"), sha256: hash.digest("hex"), bytes: sourceBytes });

package/src/store/recovery.ts

@@ -1,9 +1,8 @@
 /** Complete an explicitly logged cut; never infer a user's chosen branch. */
 import type { Cursor } from "./log.ts";
 import { closeNode, digestNode, initNode, listNodes, nodePath, readNode, readManifest, writeCursor } from "./log.ts";
-import { replayContext } from "./replay.ts";
+import { replayContext, carriedHandoff } from "./replay.ts";
 import { deriveHandoff } from "../core/derive.ts";
-import { boundHandoff } from "../core/history.ts";
 
 export async function recoverCut(dir: string, cursor: Cursor): Promise<Cursor> {
   const source = await readNode(dir, cursor.node);
@@ -18,7 +17,7 @@ export async function recoverCut(dir: string, cursor: Cursor): Promise<Cursor> {
       self: { node: cursor.node, log_ref: nodePath(dir, cursor.node), sha256: await digestNode(dir, cursor.node) },
     });
     await closeNode(dir, cursor.node,
-      cut.handoff_tokens === undefined ? handoff : boundHandoff(handoff, cut.handoff_tokens), source.events.length, cut.at);
+      await carriedHandoff(dir, cursor.node, handoff, cut, manifest), source.events.length, cut.at);
   }
   const successor = await readNode(dir, cut.next_node);
   if (successor.header === null) {

package/src/store/replay.ts

@@ -6,10 +6,11 @@
  */
 import { deriveHandoff } from "../core/derive.ts";
 import type { Handoff } from "../core/handoff.ts";
-import type { LogEvent } from "../core/events.ts";
-import { boundHandoff } from "../core/history.ts";
+import type { CutEvent, LogEvent } from "../core/events.ts";
+import { boundHandoff, boundWorkingHandoff, boundRecoveryHandoff } from "../core/history.ts";
 import { retainedContext } from "../core/context-window.ts";
 import { digestNode, nodePath, readAncestry, readManifest, type Manifest } from "./log.ts";
+import { readNodeHistory } from "./restore.ts";
 
 export interface ReplayedContext {
   /** Events not already included in fullHandoff; use these for derivation. */
@@ -22,6 +23,18 @@ export interface ReplayedContext {
   depth: number;
 }
 
+/** A live cut, cold replay and interrupted-cut repair must select the same version. */
+export async function carriedHandoff(dir: string, node: number, full: Handoff,
+  policy: Pick<CutEvent, "handoff_tokens" | "working_set_version" | "guidance_tools">, manifest?: Manifest): Promise<Handoff> {
+  if (policy.handoff_tokens === undefined) return full;
+  if (policy.working_set_version === 2) {
+    const history = await readNodeHistory(dir, node, manifest, "context");
+    if (!history.ok) throw new Error(history.error);
+    return boundRecoveryHandoff(full, history.nodes, policy.handoff_tokens, policy.guidance_tools);
+  }
+  return (policy.working_set_version === 1 ? boundWorkingHandoff : boundHandoff)(full, policy.handoff_tokens);
+}
+
 export async function replayContext(
   dir: string, node: number, manifest?: Manifest,
 ): Promise<ReplayedContext> {
@@ -54,8 +67,7 @@ export async function replayContext(
       self: { node: part.node, log_ref: nodePath(dir, part.node), sha256: await digestNode(dir, part.node) },
     });
     const tail = part.events.at(-1);
-    carried = tail?.t === "cut" && tail.handoff_tokens !== undefined
-      ? boundHandoff(handoff, tail.handoff_tokens) : handoff;
+    carried = tail?.t === "cut" ? await carriedHandoff(dir, part.node, handoff, tail, index) : handoff;
     retained = tail?.t === "cut" && tail.retained_from !== undefined
       ? retainedContext(contextEvents, tail.retained_from) : [];
   }

package/src/store/runtime-target.ts

@@ -0,0 +1,64 @@
+/** R8: OS inspection is confined to the exact owned PID; never discover a target by its name or port. */
+import { realpath, readlink, stat } from "node:fs/promises";
+import { dirname, basename, resolve, relative, sep } from "node:path";
+import { connect } from "node:net";
+import { observeArgvCommand } from "./command.ts";
+import { readObservation } from "./observations.ts";
+import { observeArtifactFiles, archiveCommandArtifacts } from "./command-artifacts.ts";
+import { lsofOwnsImage, lsofOwnsPort } from "../core/runtime-target.ts";
+import type { ArtifactRef } from "../core/events.ts";
+
+// Assumed probe limits. Output beyond the budget and unavailable OS fields remain unknown.
+const PROBE_BYTES = 64 * 1024;
+const PROBE_MS = 2_000;
+export async function targetDirectory(root: string, path: string): Promise<string> {
+  const base = await realpath(root), cwd = await realpath(resolve(base, path)), rel = relative(base, cwd);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || rel.startsWith(sep) || !(await stat(cwd)).isDirectory()) throw Error("target workdir escapes the workspace or is not a directory");
+  return cwd;
+}
+export async function targetProgram(path: string, signal?: AbortSignal) {
+  const absolute = await realpath(path);
+  const [file] = await observeArtifactFiles(dirname(absolute), [basename(absolute)], signal);
+  if (file?.state !== "observed") throw Error("target executable cannot be observed as a stable ordinary file");
+  return { path: absolute, sha256: file.sha256, device: file.identity.device, inode: file.identity.inode };
+}
+export async function observeRuntimeIdentity(pid: number, program: { path: string; device: string; inode: string }, port: number | undefined,
+  outputStore: string, signal?: AbortSignal): Promise<{ image: boolean; port: boolean | null; known: boolean; raw: ArtifactRef[]; reason: string }> {
+  const raw: ArtifactRef[] = [];
+  const lsof = process.platform === "darwin" ? "/usr/sbin/lsof" : "/usr/bin/lsof";
+  const probe = async (args: string[]) => {
+    const result = await observeArgvCommand({ argv: [lsof, ...args], cwd: "/", outputStore, maxOutputBytes: PROBE_BYTES,
+      timeoutMs: PROBE_MS, outputLimitBytes: PROBE_BYTES, ...(signal ? { signal } : {}) });
+    raw.push(result.stdout, result.stderr);
+    raw.push(await archiveCommandArtifacts(outputStore, { argv: [lsof, ...args], cwd: "/", exit: result.exit, capture: result.capture,
+      stdout: result.stdout, stderr: result.stderr, stopped: result.stopped ?? null, cleanup: result.cleanup ?? null }));
+    if (result.stopped || result.cleanup || result.capture !== "complete" || result.stdout.bytes > PROBE_BYTES || ![0, 1].includes(result.exit)) throw Error("OS target observation was incomplete");
+    return (await readObservation(outputStore, result.stdout.sha256, 0, PROBE_BYTES)).text;
+  };
+  try {
+    let image: boolean;
+    if (process.platform === "darwin") image = lsofOwnsImage(await probe(["-a", "-p", String(pid), "-d", "txt", "-F0pftDin"]), pid, program.device, program.inode);
+    else if (process.platform === "linux") {
+      const path = `/proc/${pid}/exe`, observed = await stat(path, { bigint: true });
+      const link = await readlink(path), device = String(observed.dev), inode = String(observed.ino);
+      raw.push(await archiveCommandArtifacts(outputStore, { path, link, device, inode }));
+      image = link === program.path && device === program.device && inode === program.inode;
+    } else return { image: false, port: port === undefined ? null : false, known: false, raw, reason: "OS executable identity is unsupported on this platform" };
+    const ownsPort = port === undefined ? null : lsofOwnsPort(await probe(["-nP", "-a", "-p", String(pid), `-iTCP:${port}`, "-sTCP:LISTEN", "-F0pftPnT"]), pid, port);
+    const reachable = port === undefined ? null : ownsPort && await loopbackReady(port, signal);
+    return { image, port: reachable, known: true, raw, reason: !image ? "owned process executable does not match the launch observation" : reachable === false ? "the owned PID does not serve the declared IPv4 loopback port" : "owned executable and declared endpoint observed" };
+  } catch { return { image: false, port: port === undefined ? null : false, known: false, raw, reason: "OS target identity could not be established" }; }
+}
+
+async function loopbackReady(port: number, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted) return false;
+  return new Promise(resolve => {
+    const socket = connect({ host: "127.0.0.1", port });
+    const done = (ok: boolean) => { signal?.removeEventListener("abort", abort); socket.destroy(); resolve(ok); };
+    const abort = () => done(false);
+    socket.setTimeout(PROBE_MS, () => done(false));
+    socket.once("connect", () => done(true)); socket.once("error", () => done(false));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+  });
+}