@visual-z/xeno 0.4.0 → 0.6.0

package/src/store/file-checkpoints.ts

@@ -67,8 +67,9 @@ export async function archiveEdit(blobs: string, before: Uint8Array | null, afte
   await putBlob(blobs, after);
 }
 
-export async function preflightChanges(root: string, blobs: string, changes: FileChanges): Promise<void> {
+export async function preflightChanges(root: string, blobs: string, changes: FileChanges, signal?: AbortSignal): Promise<void> {
   for (const path of changedPaths(changes)) {
+    if (signal?.aborted) throw new ToolFault("cancelled", "file operation cancelled", NOT_STARTED);
     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}`);
@@ -77,15 +78,15 @@ export async function preflightChanges(root: string, blobs: string, changes: Fil
 }
 
 /** 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);
+export async function applyFileChanges(root: string, blobs: string, changes: FileChanges, signal?: AbortSignal): Promise<void> {
+  await preflightChanges(root, blobs, changes, signal);
   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);
+      await replaceFile(root, path, before, bytes, after?.mode ?? 0o644, signal);
       applied.push(path);
     }
   } catch (error) {

package/src/store/foundation-config.ts

@@ -0,0 +1,24 @@
+/** Trusted executable configuration follows the same user/project boundary as extensions. */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function readFoundationConfig(configDirectory: string, workspace: string, trusted: boolean): Promise<Record<string, unknown>> {
+  let value: Record<string, unknown> = {};
+  for (const path of [join(configDirectory, "foundation.json"), ...(trusted ? [join(workspace, ".xeno", "foundation.json")] : [])]) {
+    let text: string;
+    try { text = await readFile(path, "utf8"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw error; }
+    const parsed: unknown = JSON.parse(text);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw Error(`${path}: expected an object`);
+    const allowed = ["mcp", "webSearch", "formatters", "lsp", "permissions"];
+    if (Object.keys(parsed).some(key => !allowed.includes(key))) throw Error(`${path}: unknown foundation setting`);
+    value = { ...value, ...parsed };
+  }
+  return value;
+}
+
+export async function readOutputSchema(path: string): Promise<unknown> {
+  const text = await readFile(path, "utf8");
+  if (Buffer.byteLength(text) > 1_048_576) throw Error("output schema exceeds 1 MiB");
+  return JSON.parse(text) as unknown;
+}

package/src/store/lsp-document.ts

@@ -0,0 +1,30 @@
+import { editablePath } from "./file-checkpoints.ts";
+import { open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { blobAddress } from "./blobs.ts";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+// Operational memory ceiling: a language server is optional and must not read arbitrarily large files.
+const MAX_LSP_DOCUMENT = 2 * 1024 * 1024;
+export async function readLspDocument(root: string, path: string, signal?: AbortSignal): Promise<{ uri: string; text: string; sha256: string }> {
+  signal?.throwIfAborted();
+  const absolute = await editablePath(root, path);
+  const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.nlink > 1) throw Error("LSP requires an existing ordinary workspace file");
+    if (info.size > MAX_LSP_DOCUMENT) throw Error("LSP document exceeds 2 MiB");
+    const bytes = new Uint8Array(MAX_LSP_DOCUMENT + 1); let length = 0;
+    for (;;) {
+      signal?.throwIfAborted();
+      const result = await file.read(bytes, length, bytes.length - length, null);
+      if (!result.bytesRead) break;
+      length += result.bytesRead;
+      if (length > MAX_LSP_DOCUMENT) throw Error("LSP document exceeds 2 MiB");
+    }
+    signal?.throwIfAborted();
+    const content = bytes.subarray(0, length);
+    return { uri: pathToFileURL(resolve(root, path)).href, text: new TextDecoder("utf8", { fatal: true }).decode(content), sha256: blobAddress(content) };
+  } finally { await file.close(); }
+}

package/src/store/mcp-credentials.ts

@@ -0,0 +1,85 @@
+/** Credential storage is separate from append-only observations: secrets must never become log evidence. */
+import { mkdir, open, rename, rm, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { isJsonValue, type JsonValue } from "../core/tool-contract.ts";
+
+export interface McpCredentials {
+  version: 1; serverUrl: string; redirectUrl: string;
+  clientIdentity?: string;
+  clients: Record<string, JsonValue>; tokens: Record<string, JsonValue>; expiresAt: Record<string, number>; activeIssuer: string | null;
+}
+export interface McpCredentialsStore {
+  read(serverUrl: string, clientIdentity?: string): Promise<McpCredentials | undefined>;
+  write(credentials: McpCredentials): Promise<void>;
+  remove(serverUrl: string, clientIdentity?: string): Promise<void>;
+}
+// Assumed bound prevents a replaced credential file from becoming an unbounded JSON allocation.
+const MAX_CREDENTIAL_BYTES = 1024 * 1024;
+function filename(dir: string, url: string, clientIdentity = "") { return join(dir, createHash("sha256").update(JSON.stringify([url, clientIdentity])).digest("hex") + ".json"); }
+function record(value: unknown): value is Record<string, JsonValue> {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && isJsonValue(value);
+}
+function validate(value: unknown, serverUrl: string, clientIdentity = ""): McpCredentials {
+  if (!record(value) || value["version"] !== 1 || value["serverUrl"] !== serverUrl || typeof value["redirectUrl"] !== "string"
+    || (value["clientIdentity"] ?? "") !== clientIdentity
+    || !record(value["clients"]) || !record(value["tokens"]) || !record(value["expiresAt"])
+    || Object.values(value["expiresAt"]).some(time => typeof time !== "number" || !Number.isFinite(time))
+    || value["activeIssuer"] !== null && typeof value["activeIssuer"] !== "string") throw Error("MCP credential record is invalid");
+  return { version: 1, serverUrl, redirectUrl: value["redirectUrl"], clients: value["clients"], tokens: value["tokens"],
+    expiresAt: Object.fromEntries(Object.entries(value["expiresAt"]).map(([issuer, time]) => [issuer, Number(time)])), activeIssuer: value["activeIssuer"],
+    ...(typeof value["clientIdentity"] === "string" ? { clientIdentity: value["clientIdentity"] } : {}) };
+}
+/** Explicit restricted-file backend, compatible with Codex's fallback; applications may provide an OS vault adapter. */
+export class FileMcpCredentialsStore implements McpCredentialsStore {
+  private readonly dir: string;
+  private writes = Promise.resolve();
+  constructor(dir: string) { this.dir = dir; }
+  private async directory(): Promise<void> {
+    const stat = await lstat(this.dir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) throw Error("MCP credential directory permissions are invalid");
+  }
+  async read(serverUrl: string, clientIdentity?: string): Promise<McpCredentials | undefined> {
+    const path = filename(this.dir, serverUrl, clientIdentity);
+    try {
+      await this.directory();
+      const stat = await lstat(path);
+      if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.size > MAX_CREDENTIAL_BYTES) throw Error("MCP credential file permissions or size are invalid");
+      const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const opened = await file.stat();
+        if (!opened.isFile() || opened.size > MAX_CREDENTIAL_BYTES || (opened.mode & 0o077) !== 0) throw Error("Unsafe credential handle");
+        return validate(JSON.parse(await file.readFile("utf8")), serverUrl, clientIdentity);
+      } finally { await file.close(); }
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return undefined;
+      throw Error("MCP credential store could not be read safely");
+    }
+  }
+  write(credentials: McpCredentials): Promise<void> {
+    const serialized = JSON.stringify(validate(credentials, credentials.serverUrl, credentials.clientIdentity));
+    const target = filename(this.dir, credentials.serverUrl, credentials.clientIdentity);
+    if (Buffer.byteLength(serialized) > MAX_CREDENTIAL_BYTES) return Promise.reject(Error("MCP credential record exceeds size limit"));
+    const operation = this.writes.then(async () => {
+      await mkdir(this.dir, { recursive: true, mode: 0o700 });
+      await this.directory();
+      const temporary = join(this.dir, `.${randomUUID()}.tmp`);
+      try {
+        const file = await open(temporary, "wx", 0o600);
+        try { await file.writeFile(serialized); await file.sync(); } finally { await file.close(); }
+        await rename(temporary, target);
+      } finally { await rm(temporary, { force: true }); }
+    });
+    this.writes = operation.catch(() => {});
+    return operation;
+  }
+  async remove(serverUrl: string, clientIdentity?: string): Promise<void> {
+    await this.writes;
+    try { await this.directory(); await rm(filename(this.dir, serverUrl, clientIdentity), { force: true }); }
+    catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return;
+      throw Error("MCP credential store could not be removed safely");
+    }
+  }
+}

package/src/store/patch.ts

@@ -0,0 +1,92 @@
+/** R4 / P.3: one fully prepared plan shares the existing confined checkpoint CAS. */
+import { relative, resolve } from "node:path";
+import { parsePatch, applyPatchChunks, patchPaths, PatchError, type PatchOperation } from "../core/patch.ts";
+import { sameVersion, changedPaths, type FileChanges } from "../core/checkpoints.ts";
+import { unifiedFileDiff } from "../core/review.ts";
+import { isFileDigest } from "../core/file-precondition.ts";
+import { ToolFault, NOT_STARTED, READ_ATTEMPTED } from "../core/tool-failure.ts";
+import { editablePath, readEditableFile, applyFileChanges } from "./file-checkpoints.ts";
+import { putBlob } from "./blobs.ts";
+
+export interface PreparedPatch {
+  root: string;
+  changes: FileChanges;
+  operations: readonly PatchOperation[];
+  diffs: readonly { path: string; destination?: string; kind: "add" | "update" | "move" | "delete"; diff: string }[];
+}
+export interface PreparePatchOptions {
+  observedFileVersion?: (absolute: string) => Promise<string | undefined>;
+  expectedSha256?: Readonly<Record<string, string>>;
+  signal?: AbortSignal;
+}
+const decode = (bytes: Uint8Array) => {
+  try { return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+  catch { throw new ToolFault("invalid_input", "patch requires valid UTF-8 files; use a trusted command for binary data", READ_ATTEMPTED); }
+};
+
+/** No workspace write occurs until every source, destination and hunk passes. */
+export async function preparePatch(root: string, blobs: string, text: string, options: PreparePatchOptions = {}): Promise<PreparedPatch> {
+  let operations: PatchOperation[];
+  try { operations = parsePatch(text); }
+  catch (error) { if (error instanceof PatchError) throw new ToolFault(error.code, error.message, NOT_STARTED); throw error; }
+  const names = new Map<string, string>();
+  const targets = new Set<string>();
+  for (const path of patchPaths(operations)) {
+    const absolute = await editablePath(root, path), canonical = relative(resolve(root), absolute);
+    if (targets.has(canonical) || [...targets].some(existing => existing.startsWith(canonical + "/") || canonical.startsWith(existing + "/")))
+      throw new ToolFault("invalid_input", `patch has duplicate or overlapping targets: ${path}`, NOT_STARTED);
+    names.set(path, canonical); targets.add(canonical);
+  }
+  const canonical = (path: string) => names.get(path)!;
+  const observed = new Map<string, Awaited<ReturnType<typeof readEditableFile>>>();
+  for (const path of targets) {
+    if (options.signal?.aborted) throw new ToolFault("cancelled", "patch preparation cancelled", NOT_STARTED);
+    observed.set(path, await readEditableFile(root, path));
+  }
+  const changes: FileChanges = Object.create(null) as FileChanges;
+  const diffs: PreparedPatch["diffs"][number][] = [];
+  for (const operation of operations) {
+    const path = canonical(operation.path), source = observed.get(path)!;
+    if (operation.kind !== "add") {
+      if (source.bytes === null || source.version === null) throw new ToolFault("not_found", `patch source is missing: ${path}`, READ_ATTEMPTED);
+      const explicit = options.expectedSha256?.[operation.path] ?? options.expectedSha256?.[path];
+      const expected = explicit ?? await options.observedFileVersion?.(resolve(root, path));
+      if (!isFileDigest(expected) || expected !== source.version.sha256)
+        throw new ToolFault("version_mismatch", `patch source version was not observed or changed: ${path}; read it before editing`, READ_ATTEMPTED, { recover: { tool: "read", input: { path } } });
+    } else if (source.version !== null) {
+      throw new ToolFault("version_mismatch", `patch add requires an absent destination: ${path}; existing bytes were preserved`, READ_ATTEMPTED);
+    }
+    let destination = path, content: string | null;
+    const before = source.bytes === null ? null : decode(source.bytes);
+    if (operation.kind === "delete") content = null;
+    else if (operation.kind === "add") content = operation.content;
+    else {
+      try { content = applyPatchChunks(before!, operation.chunks); }
+      catch (error) { if (error instanceof PatchError) throw new ToolFault(error.code, `${path}: ${error.message}`, READ_ATTEMPTED); throw error; }
+      if (operation.movePath !== undefined) {
+        destination = canonical(operation.movePath);
+        if (observed.get(destination)!.version !== null) throw new ToolFault("version_mismatch", `patch move requires an absent destination: ${destination}`, READ_ATTEMPTED);
+      }
+    }
+    if (source.bytes !== null) await putBlob(blobs, source.bytes);
+    const after = content === null ? null : { sha256: await putBlob(blobs, content), mode: source.version?.mode ?? (0o666 & ~process.umask()) };
+    if (destination !== path) {
+      changes[path] = { before: source.version, after: null };
+      changes[destination] = { before: null, after };
+    } else changes[path] = { before: source.version, after };
+    diffs.push({ path, ...(destination === path ? {} : { destination }), kind: destination !== path ? "move" : operation.kind,
+      diff: unifiedFileDiff(path, before, content, destination) });
+  }
+  return { root: resolve(root), operations, changes, diffs };
+}
+
+/** The caller persists prepared/applied checkpoint phases around this operation. */
+export async function applyPreparedPatch(root: string, blobs: string, prepared: PreparedPatch, signal?: AbortSignal): Promise<void> {
+  if (resolve(root) !== prepared.root) throw new ToolFault("invalid_input", "prepared patch names another workspace", NOT_STARTED);
+  if (signal?.aborted) throw new ToolFault("cancelled", "patch application cancelled", NOT_STARTED);
+  await applyFileChanges(root, blobs, prepared.changes, signal);
+  for (const path of changedPaths(prepared.changes)) {
+    if (!sameVersion((await readEditableFile(root, path)).version, prepared.changes[path]!.after))
+      throw new Error(`file changed concurrently after patch: ${path}; inspect the prepared checkpoint`);
+  }
+}

package/src/store/permission-paths.ts

@@ -0,0 +1,34 @@
+/** R13 / D13: path policy sees aliases and actual resources; confinement remains separate. */
+import { realpath } from "node:fs/promises";
+import { dirname, basename, resolve, relative, isAbsolute } from "node:path";
+import { permissionRequest, normalizePermissionPath, type PermissionRequest } from "../core/permissions.ts";
+
+async function canonicalPath(path: string): Promise<string> {
+  try { return await realpath(path); }
+  catch (error) {
+    if (!error || typeof error !== "object" || !("code" in error) || !["ENOENT", "ENOTDIR"].includes(String(error.code))) throw error;
+    const parent = dirname(path);
+    if (parent === path) throw error;
+    // New files have no realpath yet; existing ancestors still reveal aliases.
+    return resolve(await canonicalPath(parent), basename(path));
+  }
+}
+function resource(root: string, absolute: string): string {
+  const path = relative(root, absolute);
+  return normalizePermissionPath(path === ".." || path.startsWith("../") || isAbsolute(path) ? absolute : path || ".");
+}
+
+export async function permissionPaths(root: string, paths: readonly string[]): Promise<string[]> {
+  const absoluteRoot = resolve(root), canonicalRoot = await canonicalPath(absoluteRoot), resources: string[] = [];
+  for (const path of paths) {
+    const absolute = resolve(absoluteRoot, path);
+    resources.push(resource(absoluteRoot, absolute), resource(canonicalRoot, await canonicalPath(absolute)));
+  }
+  return [...new Set(resources)];
+}
+
+/** Models never supply the root or canonical target; the current runtime does. */
+export async function canonicalPermissionRequest(root: string, name: string, input: unknown): Promise<PermissionRequest> {
+  const request = permissionRequest(name, input);
+  return request.paths ? { ...request, paths: await permissionPaths(root, request.paths) } : request;
+}

package/src/store/resources.ts

@@ -2,8 +2,8 @@
  * Discover and read UI resources: settings, theme, keybindings, skills,
  * prompt templates.
  *
- * I/O lives here; validation is core. A corrupt file is a diagnostic plus
- * a fallback, never a throw -- startup has to survive a missing comma.
+ * I/O lives here; validation is core. Reads diagnose corrupt files and fall
+ * back so startup survives a missing comma. Writes preserve them and report failure.
  *
  * Project-level files follow the same trust rule as `.xeno/settings.json`.
  * Theme and keymap are UI state and are not logged.
@@ -12,7 +12,9 @@
 import { readdir, readFile } from "node:fs/promises";
 import { watch } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { configDir, readJsonFile, writeJsonFile, settingsPath } from "./config.ts";
+import { configDir, readJsonFile } from "./config.ts";
+import { editUserSettings } from "./user-settings.ts";
+import { mergePreferenceJson } from "../core/model-preferences.ts";
 import { discoverResources, themeResourcePath, type ResourceIndex } from "./resource-index.ts";
 import { parseSkill, type Skill } from "../core/skills.ts";
 import { parsePromptTemplate, type PromptTemplate } from "../core/prompts.ts";
@@ -29,7 +31,6 @@ import {
 import {
   defaultSettings,
   mergeSettings,
-  settingsToWrite,
   type Settings,
 } from "../core/settings.ts";
 
@@ -90,28 +91,18 @@ export function selectedThemePath(index: ResourceIndex, name: string, noThemes =
 }
 
 export async function writeUserSettings(overrides: Partial<Settings>): Promise<void> {
-  const { value, error } = await readJsonFile<unknown>(settingsPath());
-  const prev =
-    error === null && typeof value === "object" && value !== null && !Array.isArray(value)
-      ? (value as { readonly [k: string]: unknown })
-      : {};
-  const next = { ...prev, ...settingsToWrite(overrides),
-    ...(overrides.terminal ? { terminal: { ...(typeof prev["terminal"] === "object" ? prev["terminal"] : {}), ...overrides.terminal } } : {}),
-    ...(overrides.modelThinkingLevels ? { modelThinkingLevels: { ...(typeof prev["modelThinkingLevels"] === "object" ? prev["modelThinkingLevels"] : {}), ...overrides.modelThinkingLevels } } : {}),
-    ...Object.fromEntries((["images", "markdown"] as const).filter(key => overrides[key]).map(key => [key, { ...(typeof prev[key] === "object" ? prev[key] : {}), ...overrides[key] }])),
-  };
-  await writeJsonFile(settingsPath(), next, false);
+  const patch = structuredClone(overrides);
+  await editUserSettings(previous => mergePreferenceJson(previous, patch));
 }
 
 /** Remove only the user's override; project defaults and unrelated keys retain their ownership. */
 export async function removeModelThinkingOverride(identity: string): Promise<void> {
-  const { value, error } = await readJsonFile<Record<string, unknown>>(settingsPath());
-  if (error) throw new Error(error);
-  if (!value || typeof value !== "object" || Array.isArray(value)) return;
-  const levels = value["modelThinkingLevels"];
-  if (!levels || typeof levels !== "object" || Array.isArray(levels)) return;
-  const next = Object.fromEntries(Object.entries(levels).filter(([key]) => key !== identity));
-  await writeJsonFile(settingsPath(), { ...value, modelThinkingLevels: next }, false);
+  await editUserSettings(previous => {
+    const levels = previous["modelThinkingLevels"];
+    if (!levels || typeof levels !== "object" || Array.isArray(levels)) return null;
+    const next = Object.fromEntries(Object.entries(levels).filter(([key]) => key !== identity));
+    return { ...previous, modelThinkingLevels: next };
+  });
 }
 
 export async function resolveTheme(spec: string, diagnostics: string[]): Promise<Theme> {

package/src/store/review.ts

@@ -0,0 +1,109 @@
+/** Read-only Git review with fixed argv; project diff drivers cannot execute code. */
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import type { FileChanges } from "../core/checkpoints.ts";
+import { changedPaths } from "../core/checkpoints.ts";
+import { ToolFault, READ_ATTEMPTED } from "../core/tool-failure.ts";
+import { unifiedFileDiff, type ReviewScope, type ReviewSnapshot } from "../core/review.ts";
+import { gitBytes, MAX_UNTRACKED_BYTES } from "./workspace-observation.ts";
+import { readEditableFile } from "./file-checkpoints.ts";
+import { getBlobBytes, blobAddress } from "./blobs.ts";
+
+// Assumed bounded review memory. Exceeding it is unavailable, never silently partial.
+export const MAX_REVIEW_BYTES = 16 * 1024 * 1024;
+const decode = (bytes: Uint8Array) => new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+const flags = ["--no-pager", "--literal-pathspecs", "-c", "core.hooksPath=/dev/null"];
+const diffFlags = ["--no-ext-diff", "--no-textconv", "--no-renames", "--relative"];
+const checkedText = (bytes: Uint8Array) => {
+  if (bytes.byteLength > MAX_REVIEW_BYTES) throw new Error("review exceeds the byte budget; choose a narrower scope");
+  return decode(bytes);
+};
+const ordinaryText = (bytes: Uint8Array): string | null => {
+  if (bytes.includes(0)) return null;
+  try { return decode(bytes); } catch { return null; }
+};
+
+export async function readReview(root: string, scope: Exclude<ReviewScope, { kind: "last-turn" }>, signal?: AbortSignal, canRead?: (path: string) => Promise<boolean>): Promise<ReviewSnapshot> {
+  const git = (args: readonly string[], input?: Uint8Array) => gitBytes(root, [...flags, ...args], input, signal);
+  const revision = async (value: string) => {
+    if (!value || value.includes("\0") || value.startsWith("-")) throw new Error("review revision must name a commit or branch");
+    const sha = decode(await git(["rev-parse", "--verify", "--end-of-options", value + "^{commit}"])).trim();
+    if (!/^[a-f0-9]{40,64}$/.test(sha)) throw new Error("review revision did not resolve to a commit");
+    return sha;
+  };
+  const emptyTree = async () => decode(await git(["hash-object", "-t", "tree", "--stdin"], new Uint8Array())).trim();
+  let base: string, end: string | undefined, label: string;
+  if (scope.kind === "commit") {
+    end = await revision(scope.commit);
+    const parents = decode(await git(["rev-list", "--parents", "-n", "1", end])).trim().split(" ");
+    base = parents[1] ?? await emptyTree();
+    label = `commit ${end.slice(0, 12)}${parents.length > 2 ? " against its first parent" : ""}`;
+  } else if (scope.kind === "branch") {
+    const branch = await revision(scope.base), head = await revision("HEAD");
+    base = decode(await git(["merge-base", head, branch])).trim();
+    label = `changes against ${scope.base} (merge base ${base.slice(0, 12)})`;
+  } else {
+    try { base = await revision("HEAD"); }
+    catch {
+      // An unborn branch has no HEAD; a corrupt/missing existing HEAD stays unavailable.
+      const heads = decode(await git(["rev-list", "--all", "--count"])).trim();
+      if (heads !== "0") throw new Error("working review cannot resolve HEAD");
+      base = await emptyTree();
+    }
+    label = "current staged, unstaged and untracked changes";
+  }
+  const range = [base, ...(end === undefined ? [] : [end])];
+  const paths = decode(await git(["diff", ...diffFlags, "--name-only", "-z", ...range, "--", "."])).split("\0").filter(Boolean);
+  const untracked = scope.kind === "commit" ? [] : decode(await git(["ls-files", "--others", "--exclude-standard", "-z", "--", "."])).split("\0").filter(Boolean);
+  for (const path of [...new Set([...paths, ...untracked])]) if (canRead && !await canRead(path))
+    throw new ToolFault("permission_denied", `diff resource access denied: ${path}`, READ_ATTEMPTED);
+  // Freeze the authorized path set in the actual collection argv. A concurrent
+  // change to a different path must not widen this observation after admission.
+  const diff = paths.length ? checkedText(await git(["diff", ...diffFlags, ...range, "--", ...paths])) : "";
+  const parts = [diff], limitations: string[] = [];
+  let bytes = Buffer.byteLength(diff);
+  if (scope.kind !== "commit") {
+    for (const path of untracked.sort()) {
+      if (signal?.aborted) throw new Error("review cancelled");
+      const info = await lstat(join(root, path));
+      if (info.size > MAX_UNTRACKED_BYTES) { limitations.push(`Untracked file ${JSON.stringify(path)} exceeds ${MAX_UNTRACKED_BYTES} bytes and is unavailable.`); continue; }
+      let source: Awaited<ReturnType<typeof readEditableFile>>;
+      try { source = await readEditableFile(root, path); }
+      catch { limitations.push(`Untracked file ${JSON.stringify(path)} is not an ordinary confined file.`); continue; }
+      if (source.bytes === null) throw new Error(`untracked file disappeared during review: ${path}`);
+      const text = ordinaryText(source.bytes);
+      const addition = text === null ? `Binary untracked file ${JSON.stringify(path)}: ${source.bytes.byteLength} bytes, sha256 ${source.version!.sha256}\n`
+        : unifiedFileDiff(path, null, text);
+      bytes += Buffer.byteLength(addition);
+      if (bytes > MAX_REVIEW_BYTES) throw new Error("review exceeds the byte budget; choose a narrower scope");
+      parts.push(addition); paths.push(path);
+      if (text === null) limitations.push(`Binary untracked content is identified but cannot be reviewed as text: ${JSON.stringify(path)}.`);
+    }
+  }
+  return { scope, label, diff: parts.join("\n"), paths: [...new Set(paths)].sort(), limitations, base };
+}
+
+/** Build last-turn review from verified checkpoint blobs, independent of present disk bytes. */
+export async function readCheckpointReview(blobs: string, changes: FileChanges, limitations: readonly string[] = [], canRead?: (path: string) => Promise<boolean>): Promise<ReviewSnapshot> {
+  const parts: string[] = [], notices = [...limitations], paths = changedPaths(changes);
+  for (const path of paths) if (canRead && !await canRead(path))
+    throw new ToolFault("permission_denied", `diff resource access denied: ${path}`, READ_ATTEMPTED);
+  let bytes = 0;
+  for (const path of paths) {
+    const firstPart = parts.length;
+    const { before, after } = changes[path]!;
+    const source = before === null ? null : await getBlobBytes(blobs, before.sha256);
+    const target = after === null ? null : await getBlobBytes(blobs, after.sha256);
+    if (before && (source === null || blobAddress(source) !== before.sha256) || after && (target === null || blobAddress(target) !== after.sha256))
+      throw new Error(`missing or corrupt last-turn checkpoint object: ${path}`);
+    const oldText = source === null ? null : ordinaryText(source), newText = target === null ? null : ordinaryText(target);
+    if (source !== null && oldText === null || target !== null && newText === null) {
+      parts.push(`Binary checkpoint change ${JSON.stringify(path)}: ${before?.sha256 ?? "absent"} -> ${after?.sha256 ?? "absent"}\n`);
+      notices.push(`Binary checkpoint content cannot be reviewed as text: ${JSON.stringify(path)}.`);
+    } else parts.push(unifiedFileDiff(path, oldText, newText));
+    if (before && after && before.mode !== after.mode) parts.push(`mode ${JSON.stringify(path)}: ${before.mode.toString(8)} -> ${after.mode.toString(8)}\n`);
+    bytes += parts.slice(firstPart).reduce((total, part) => total + Buffer.byteLength(part), 0);
+    if (bytes > MAX_REVIEW_BYTES) throw new Error("last-turn review exceeds the byte budget");
+  }
+  return { scope: { kind: "last-turn" }, label: "captured file changes in the last user turn", diff: parts.join("\n"), paths, limitations: notices };
+}

package/src/store/search.ts

@@ -94,6 +94,8 @@ export interface GrepOpts {
   /** Trusted harness budgets, not model arguments. */
   readonly maxCaptureBytes?: number;
   readonly maxIndexEntries?: number;
+  /** Trusted admission for each POSIX workspace-relative resource, before content is read. */
+  readonly canRead?: (path: string) => Promise<boolean>;
 }
 
 export interface FindOpts {
@@ -106,6 +108,7 @@ export interface FindOpts {
   readonly signal?: AbortSignal;
   readonly maxCaptureBytes?: number;
   readonly maxIndexEntries?: number;
+  readonly canRead?: (path: string) => Promise<boolean>;
 }
 
 export interface LsOpts {
@@ -113,6 +116,7 @@ export interface LsOpts {
   readonly path: string;
   readonly limit?: number;
   readonly signal?: AbortSignal;
+  readonly canRead?: (path: string) => Promise<boolean>;
 }
 
 function observed(observation: SearchObservation, diagnostic?: ToolDiagnostic): SearchResult {
@@ -256,6 +260,29 @@ async function listedFiles(abs: string, rel: string, kind: "file" | "dir", optio
   return { paths: index.paths.map((p) => (rel.length === 0 ? p : `${rel}/${p}`)), issues: [...(index.issues ?? [])] };
 }
 
+/** Denied filenames cannot reappear in scan diagnostics or archived observations. */
+function policyIssues(issues: SearchObservation["scan"]["reasons"], canRead: GrepOpts["canRead"]): SearchObservation["scan"]["reasons"] {
+  return canRead ? issues.map(issue => ({ code: issue.code })) : [...issues];
+}
+async function resourceAdmitted(path: string, canRead: GrepOpts["canRead"], reasons: SearchObservation["scan"]["reasons"],
+  signal?: AbortSignal, deadline?: number): Promise<boolean> {
+  if (!canRead) return true;
+  let allowed: boolean | undefined = false, abort = () => {};
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const stopped = new Promise<undefined>(resolve => {
+    abort = () => resolve(undefined); signal?.addEventListener("abort", abort, { once: true });
+    if (deadline !== undefined) timer = setTimeout(abort, Math.max(0, deadline - performance.now()));
+    if (signal?.aborted) abort();
+  });
+  try { allowed = await Promise.race([Promise.resolve().then(() => canRead(path)).catch(() => false), stopped]); }
+  finally { clearTimeout(timer); signal?.removeEventListener("abort", abort); }
+  if (allowed === undefined || signal?.aborted || deadline !== undefined && performance.now() >= deadline) {
+    reasons.push({ code: signal?.aborted ? "cancelled" : "timeout" }); return false;
+  }
+  if (!allowed && !reasons.some(reason => reason.code === "permission_omitted")) reasons.push({ code: "permission_omitted" });
+  return allowed;
+}
+
 interface WorkerMatch {
   readonly ok: boolean;
   readonly hits?: ReadonlyArray<{ readonly line: number; readonly text: string }>;
@@ -475,7 +502,7 @@ async function grepWalk(opts: GrepOpts, abs: string, kind: "file" | "dir", rel:
   const filtered = glob === undefined ? files.paths : files.paths.filter((p) => globMatches(glob, p));
   const matcher = new LineMatcher();
   const hits: MatchLine[] = [];
-  const reasons: SearchObservation["scan"]["reasons"] = [...files.issues];
+  const reasons: SearchObservation["scan"]["reasons"] = policyIssues(files.issues, opts.canRead);
   const sources: SearchObservation["sources"] = [];
   let examined = 0, capturedBytes = 0;
   const budget = Math.min(opts.maxCaptureBytes ?? MAX_SEARCH_CAPTURE_BYTES, MAX_SEARCH_CAPTURE_BYTES);
@@ -483,6 +510,7 @@ async function grepWalk(opts: GrepOpts, abs: string, kind: "file" | "dir", rel:
     for (const fileRel of filtered) {
       if (opts.signal?.aborted || performance.now() >= deadline) { reasons.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); break; }
       if (ignoredRel(fileRel)) continue;
+      if (!await resourceAdmitted(fileRel, opts.canRead, reasons, opts.signal, deadline)) continue;
       const fileAbs = join(opts.root, fileRel);
       let st;
       try {
@@ -541,7 +569,9 @@ export async function grep(opts: GrepOpts): Promise<SearchResult> {
   if ("error" in target) return { content: target.error, ok: false, diagnostic: target.diagnostic };
 
   const limit = opts.limit !== undefined && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_MATCH_LIMIT;
-  const engine = opts.engine ?? "auto";
+  // External search captures bytes before the runtime can inspect each
+  // resource. A policy callback therefore always uses the admitted walk.
+  const engine = opts.canRead ? "walk" : opts.engine ?? "auto";
 
   switch (engine) {
     case "walk":
@@ -607,13 +637,18 @@ async function findFd(opts: FindOpts, abs: string, limit: number): Promise<Searc
 }
 
 async function findWalk(opts: FindOpts, abs: string, kind: "file" | "dir", rel: string, limit: number): Promise<SearchResult> {
-  const files = await listedFiles(abs, rel, kind, { deadline: performance.now() + (opts.timeoutMs ?? PROCESS_TIMEOUT_MS),
+  const deadline = performance.now() + (opts.timeoutMs ?? PROCESS_TIMEOUT_MS);
+  const files = await listedFiles(abs, rel, kind, { deadline,
     ...(opts.signal ? { signal: opts.signal } : {}), ...(opts.maxIndexEntries === undefined ? {} : { maxEntries: opts.maxIndexEntries }) });
-  const paths = files.paths.filter((p) => !ignoredRel(p) && globMatches(opts.pattern, p));
+  const reasons = policyIssues(files.issues, opts.canRead), paths: string[] = [];
+  for (const path of files.paths) {
+    if (opts.signal?.aborted || performance.now() >= deadline) { reasons.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); break; }
+    if (!ignoredRel(path) && globMatches(opts.pattern, path) && await resourceAdmitted(path, opts.canRead, reasons, opts.signal, deadline)) paths.push(path);
+  }
   paths.sort((a, b) => (a < b ? -1 : 1));
-  const stopped = files.issues.find(reason => ["timeout", "cancelled"].includes(reason.code));
+  const stopped = reasons.find(reason => ["timeout", "cancelled"].includes(reason.code));
   return observed({ engine: "walk", rows: paths.map(text => ({ prefix: "", text })), sources: [], limit, empty: "No files found matching pattern",
-    scan: { status: files.issues.length ? "partial" : "complete", reasons: files.issues, examined_files: files.paths.length, source_versions: "unknown" } },
+    scan: { status: reasons.length ? "partial" : "complete", reasons, examined_files: files.paths.length, source_versions: "unknown" } },
     stopped ? failureDiagnostic(stopped.code === "cancelled" ? "cancelled" : "timeout", `search ${stopped.code}`, READ_ATTEMPTED) : undefined);
 }
 
@@ -622,7 +657,7 @@ export async function find(opts: FindOpts): Promise<SearchResult> {
   const target = await inspectTarget(opts.root, opts.path);
   if ("error" in target) return { content: target.error, ok: false, diagnostic: target.diagnostic };
   const limit = opts.limit !== undefined && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_FIND_LIMIT;
-  const engine = opts.engine ?? "auto";
+  const engine = opts.canRead ? "walk" : opts.engine ?? "auto";
   switch (engine) {
     case "walk":
       return findWalk(opts, opts.path, target.kind, target.rel, limit);
@@ -656,11 +691,14 @@ export async function ls(opts: LsOpts): Promise<SearchResult> {
     return { content: `cannot list ${target.rel || "."}: ${(err as Error).message}`, ok: false, diagnostic: failureFromError(err, READ_ATTEMPTED) };
   }
 
-  const names: string[] = [];
+  const names: string[] = [], reasons: SearchObservation["scan"]["reasons"] = [];
+  const deadline = performance.now() + PROCESS_TIMEOUT_MS;
   for (const entry of entries) {
     if (DEFAULT_IGNORE.includes(entry.name)) continue;
     const childRel = target.rel.length === 0 ? entry.name : `${target.rel}/${entry.name}`;
     if (ignoredRel(childRel)) continue;
+    if (opts.signal?.aborted || performance.now() >= deadline) { reasons.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); break; }
+    if (!await resourceAdmitted(childRel, opts.canRead, reasons, opts.signal, deadline)) continue;
     // Do not follow: a symlink is listed as a name, never as the directory
     // it points at, so a link to / cannot walk the disk.
     if (entry.isSymbolicLink()) {
@@ -679,5 +717,6 @@ export async function ls(opts: LsOpts): Promise<SearchResult> {
 
   const limit = opts.limit !== undefined && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_LS_LIMIT;
   return observed({ engine: "directory", rows: names.map(text => ({ prefix: "", text })), sources: [], limit, empty: "(empty directory)",
-    scan: { status: "complete", reasons: [], examined_files: names.length, source_versions: "unknown" } });
+    scan: { status: reasons.length ? "partial" : "complete", reasons, examined_files: names.length, source_versions: "unknown" } },
+    reasons.some(reason => reason.code === "cancelled" || reason.code === "timeout") ? failureDiagnostic(opts.signal?.aborted ? "cancelled" : "timeout", "directory listing stopped", READ_ATTEMPTED) : undefined);
 }