@visual-z/xeno 0.2.1 → 0.4.0

package/src/store/search.ts

@@ -18,6 +18,11 @@ import { Worker } from "node:worker_threads";
 import { assertNever } from "../core/exhaustive.ts";
 import { buildFileIndex } from "./file-index.ts";
 import { DEFAULT_IGNORE } from "./workspace.ts";
+import { blobAddress } from "./blobs.ts";
+import { previewSearchObservation, type SearchObservation } from "../core/search-observation.ts";
+import { failureDiagnostic, failureFromError, READ_ATTEMPTED, NOT_STARTED } from "../core/tool-failure.ts";
+import type { ToolDiagnostic } from "../core/tool-contract.ts";
+import { COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
 
 /**
  * Match / entry cap. Assumed, not measured: enough for a model to read in
@@ -64,12 +69,16 @@ export const MATCH_TIMEOUT_MS = 100;
 
 /** Assumed: an rg/fd process that runs longer than this is stuck. */
 export const PROCESS_TIMEOUT_MS = 30_000;
+/** Assumed execution budget, independent of display caps; reaching it makes coverage partial. */
+export const MAX_SEARCH_CAPTURE_BYTES = 32 * 1024 * 1024;
 
 export type SearchEngine = "auto" | "ripgrep" | "walk" | "fd";
 
 export interface SearchResult {
   content: string;
   ok: boolean;
+  observation?: SearchObservation;
+  diagnostic?: ToolDiagnostic;
 }
 
 export interface GrepOpts {
@@ -81,6 +90,10 @@ export interface GrepOpts {
   readonly limit?: number;
   readonly engine?: "auto" | "ripgrep" | "walk";
   readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  /** Trusted harness budgets, not model arguments. */
+  readonly maxCaptureBytes?: number;
+  readonly maxIndexEntries?: number;
 }
 
 export interface FindOpts {
@@ -90,12 +103,25 @@ export interface FindOpts {
   readonly limit?: number;
   readonly engine?: "auto" | "fd" | "walk";
   readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  readonly maxCaptureBytes?: number;
+  readonly maxIndexEntries?: number;
 }
 
 export interface LsOpts {
   readonly root: string;
   readonly path: string;
   readonly limit?: number;
+  readonly signal?: AbortSignal;
+}
+
+function observed(observation: SearchObservation, diagnostic?: ToolDiagnostic): SearchResult {
+  return { ok: diagnostic === undefined, content: previewSearchObservation(observation, "pending-archive", MAX_OUTPUT_BYTES, MAX_LINE_CHARS).text,
+    observation, ...(diagnostic ? { diagnostic } : {}) };
+}
+
+function searchFailure(code: ToolDiagnostic["code"], content: string): SearchResult {
+  return { ok: false, content, diagnostic: failureDiagnostic(code, content, NOT_STARTED) };
 }
 
 export interface MatchLine {
@@ -139,7 +165,7 @@ export function findOnPath(name: string): string | null {
 
 function posixRel(root: string, abs: string): string | null {
   const rel = relative(root, abs);
-  if (rel.startsWith("..") || isAbsolute(rel)) return null;
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
   return rel.split(sep).join("/");
 }
 
@@ -195,71 +221,39 @@ function splitLines(text: string): string[] {
   return trimmed.split("\n");
 }
 
-function truncateLine(text: string): string {
-  const flat = text.replace(/\r/g, "");
-  if (flat.length <= MAX_LINE_CHARS) return flat;
-  return flat.slice(0, MAX_LINE_CHARS) + "…";
-}
-
-function formatMatch(m: MatchLine): string {
-  return `${m.path}:${m.line}: ${truncateLine(m.text)}`;
-}
-
-/**
- * Apply the match-count cap and the byte cap. Overflow is counted, never
- * dropped silently: a test that only asserted "at most N" would pass an
- * implementation that threw the rest away.
- */
-function renderLines(lines: string[], limit: number, extraNotices: string[]): string {
-  const omittedFromCap = Math.max(0, lines.length - limit);
-  let shown = lines.slice(0, limit);
-  let omitted = omittedFromCap;
-
-  let body = shown.join("\n");
-  while (shown.length > 0 && body.length > MAX_OUTPUT_BYTES) {
-    shown = shown.slice(0, -1);
-    omitted += 1;
-    body = shown.join("\n");
-  }
-
-  const notices = [...extraNotices];
-  if (omitted > 0) notices.push(`${omitted} more matches omitted`);
-  if (notices.length === 0) return body;
-  const note = `[${notices.join(". ")}]`;
-  return body.length > 0 ? `${body}\n${note}` : note;
-}
-
-function noMatches(notices: string[]): SearchResult {
-  if (notices.length === 0) return { content: "No matches found", ok: true };
-  return { content: `[${notices.join(". ")}]`, ok: true };
-}
-
 async function inspectTarget(
   root: string,
   abs: string,
-): Promise<{ kind: "file" | "dir"; rel: string } | { error: string }> {
+): Promise<{ kind: "file" | "dir"; rel: string } | { error: string; diagnostic: ToolDiagnostic }> {
   const rel = posixRel(root, abs);
-  if (rel === null) return { error: `path escapes the workspace root: ${abs}` };
-  if (ignoredRel(rel)) return { error: `path is ignored: ${rel}` };
+  const refuse = (message: string) => ({ error: message, diagnostic: failureDiagnostic("permission_denied", message, NOT_STARTED) });
+  if (rel === null) return refuse(`path escapes the workspace root: ${abs}`);
+  if (ignoredRel(rel)) return refuse(`path is ignored: ${rel}`);
 
   let st;
   try {
+    let current = root;
+    for (const part of rel.split("/").slice(0, -1)) {
+      current = join(current, part);
+      if ((await lstat(current)).isSymbolicLink()) return refuse(`refusing to follow a symlink in path: ${rel || "."}`);
+    }
     st = await lstat(abs);
-  } catch {
-    return { error: `path not found: ${rel || "."}` };
+  } catch (error) {
+    return { error: `cannot inspect path: ${rel || "."}`, diagnostic: failureFromError(error, READ_ATTEMPTED) };
   }
   if (st.isSymbolicLink()) {
-    return { error: `refusing to follow a symlink: ${rel || "."}` };
+    return refuse(`refusing to follow a symlink: ${rel || "."}`);
   }
   if (st.isDirectory()) return { kind: "dir", rel };
   if (st.isFile()) return { kind: "file", rel };
-  return { error: `not a file or directory: ${rel || "."}` };
+  const message = `not a file or directory: ${rel || "."}`;
+  return { error: message, diagnostic: failureDiagnostic("invalid_input", message, READ_ATTEMPTED) };
 }
 
-async function listedFiles(abs: string, rel: string, kind: "file" | "dir"): Promise<string[]> {
-  if (kind === "file") return ignoredRel(rel) ? [] : [rel];
-  const index = await buildFileIndex(abs);
-  return index.paths.map((p) => (rel.length === 0 ? p : `${rel}/${p}`));
+async function listedFiles(abs: string, rel: string, kind: "file" | "dir", options: Parameters<typeof buildFileIndex>[1] = {}) {
+  if (kind === "file") return { paths: ignoredRel(rel) ? [] : [rel], issues: [] };
+  const index = await buildFileIndex(abs, options);
+  return { paths: index.paths.map((p) => (rel.length === 0 ? p : `${rel}/${p}`)), issues: [...(index.issues ?? [])] };
 }
 
 interface WorkerMatch {
@@ -278,24 +272,29 @@ class LineMatcher {
     pattern: string,
     flags: string,
     lines: string[],
-  ): Promise<"timeout" | "invalid" | MatchLine[]> {
+    budgetMs = MATCH_TIMEOUT_MS,
+    signal?: AbortSignal,
+  ): Promise<"timeout" | "invalid" | "cancelled" | MatchLine[]> {
+    if (signal?.aborted) return "cancelled";
     if (this.worker === null) this.worker = this.spawn();
     const worker = this.worker;
     return await new Promise((resolve) => {
       let settled = false;
-      const finish = (value: "timeout" | "invalid" | MatchLine[]): void => {
+      const finish = (value: "timeout" | "invalid" | "cancelled" | MatchLine[]): void => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
         worker.off("message", onMessage);
         worker.off("error", onError);
+        signal?.removeEventListener("abort", abort);
         resolve(value);
       };
+      const abort = () => { void worker.terminate(); this.worker = null; finish("cancelled"); };
       const timer = setTimeout(() => {
         void worker.terminate();
         this.worker = null;
         finish("timeout");
-      }, MATCH_TIMEOUT_MS);
+      }, Math.max(0, Math.min(MATCH_TIMEOUT_MS, budgetMs)));
       const onMessage = (msg: WorkerMatch) => {
         if (!msg.ok) {
           finish("invalid");
@@ -310,6 +309,7 @@ class LineMatcher {
       };
       worker.on("message", onMessage);
       worker.on("error", onError);
+      signal?.addEventListener("abort", abort, { once: true });
       worker.postMessage({ pattern, flags, lines });
     });
   }
@@ -326,27 +326,51 @@ function runCommand(
   cmd: string,
   args: readonly string[],
   timeoutMs: number,
-): Promise<{ stdout: string; stderr: string; exit: number | null }> {
+  signal?: AbortSignal,
+  maxBytes = MAX_SEARCH_CAPTURE_BYTES,
+): Promise<{ stdout: string; raw: Uint8Array; rawErrors?: Uint8Array; stderr: string; exit: number | null; diagnostic?: ToolDiagnostic; stopped?: "timeout" | "cancelled" | "output_limit" }> {
+  if (signal?.aborted) return Promise.resolve({ stdout: "", raw: new Uint8Array(), stderr: "", exit: null, stopped: "cancelled" });
   return new Promise((resolve) => {
-    const child = spawn(cmd, [...args], { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk: string) => {
-      stdout += chunk;
+    const child = spawn(cmd, [...args], { stdio: ["ignore", "pipe", "pipe"], detached: true });
+    const stdout: Buffer[] = [], stderr: Buffer[] = [];
+    let size = 0, errorSize = 0, stopped: "timeout" | "cancelled" | "output_limit" | undefined;
+    let escalation: ReturnType<typeof setTimeout> | undefined;
+    const kill = (value: "SIGTERM" | "SIGKILL") => { try {
+      if (child.pid && process.platform !== "win32") process.kill(-child.pid, value); else child.kill(value);
+    } catch { /* the process group already exited */ } };
+    const stop = (reason: "timeout" | "cancelled" | "output_limit") => {
+      if (stopped) return; stopped = reason; kill("SIGTERM");
+      escalation = setTimeout(() => kill("SIGKILL"), COMMAND_TERMINATION_GRACE_MS);
+    };
+    const abort = () => stop("cancelled");
+    child.stdout.on("data", (chunk: Buffer) => {
+      const kept = chunk.subarray(0, Math.max(0, maxBytes - size));
+      if (kept.length) stdout.push(Buffer.from(kept)); size += kept.length;
+      if (kept.length < chunk.length) stop("output_limit");
     });
-    child.stderr.on("data", (chunk: string) => {
-      stderr += chunk;
+    child.stderr.on("data", (chunk: Buffer) => {
+      // Errors are bounded too; stderr is explanatory, never a source of success or completeness.
+      const kept = chunk.subarray(0, Math.max(0, 65536 - errorSize));
+      if (kept.length) stderr.push(Buffer.from(kept)); errorSize += kept.length;
+      if (kept.length < chunk.length) stop("output_limit");
     });
-    const timer = setTimeout(() => child.kill(), timeoutMs);
+    const timer = setTimeout(() => stop("timeout"), timeoutMs);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
     child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve({ stdout, stderr, exit: code });
+      clearTimeout(timer); clearTimeout(escalation); signal?.removeEventListener("abort", abort);
+      if (stopped) kill("SIGKILL");
+      const raw = Buffer.concat(stdout);
+      const rawErrors = Buffer.concat(stderr);
+      resolve({ stdout: raw.toString("utf8"), raw, rawErrors, stderr: rawErrors.toString("utf8"), exit: code, ...(stopped ? { stopped } : {}) });
     });
     child.on("error", (err) => {
-      clearTimeout(timer);
-      resolve({ stdout, stderr: err.message, exit: null });
+      const raw = Buffer.concat(stdout);
+      clearTimeout(timer); clearTimeout(escalation); signal?.removeEventListener("abort", abort);
+      const facts = child.pid ? READ_ATTEMPTED : NOT_STARTED;
+      const os = (err as { code?: string }).code;
+      const diagnostic = !child.pid && (os === "ENOENT" || os === "ENOTDIR") ? failureDiagnostic("environment_missing", err.message, facts) : failureFromError(err, facts);
+      resolve({ stdout: raw.toString("utf8"), raw, stderr: err.message, exit: null, diagnostic, ...(stopped ? { stopped } : {}) });
     });
   });
 }
@@ -381,13 +405,13 @@ function parseRgJson(root: string, stdout: string): MatchLine[] {
     const pathObj = d["path"];
     const pathText =
       typeof pathObj === "object" && pathObj !== null
-        ? String((pathObj as Record<string, unknown>)["text"] ?? "")
+        ? rgText(pathObj as Record<string, unknown>)
         : "";
     const lineNumber = d["line_number"];
     const linesObj = d["lines"];
     const lineText =
       typeof linesObj === "object" && linesObj !== null
-        ? String((linesObj as Record<string, unknown>)["text"] ?? "")
+        ? rgText(linesObj as Record<string, unknown>)
         : "";
     if (pathText.length === 0 || typeof lineNumber !== "number") continue;
     const rel = posixRel(root, pathText) ?? posixRel(root, join(root, pathText));
@@ -401,6 +425,10 @@ function parseRgJson(root: string, stdout: string): MatchLine[] {
   return hits;
 }
 
+function rgText(value: Record<string, unknown>): string {
+  return typeof value["text"] === "string" ? value["text"] : typeof value["bytes"] === "string" ? Buffer.from(value["bytes"], "base64").toString("utf8") : "";
+}
+
 async function grepRipgrep(opts: GrepOpts, abs: string, limit: number): Promise<SearchResult | null> {
   const rg = findOnPath("rg");
   if (rg === null) return null;
@@ -416,17 +444,16 @@ async function grepRipgrep(opts: GrepOpts, abs: string, limit: number): Promise<
   ];
   if (opts.glob !== undefined) args.push("--glob", opts.glob);
   args.push("--", opts.pattern, abs);
-  const ran = await runCommand(rg, args, opts.timeoutMs ?? PROCESS_TIMEOUT_MS);
-  // 0 = matches, 1 = none; anything else is a real failure (bad pattern, etc.).
-  if (ran.exit !== 0 && ran.exit !== 1) {
-    const err = ran.stderr.trim() || `ripgrep exited ${ran.exit ?? "null"}`;
-    return { content: err, ok: false };
-  }
+  const ran = await runCommand(rg, args, opts.timeoutMs ?? PROCESS_TIMEOUT_MS, opts.signal, opts.maxCaptureBytes);
   const hits = parseRgJson(opts.root, ran.stdout);
   hits.sort(compareMatch);
-  const lines = hits.map(formatMatch);
-  if (lines.length === 0) return noMatches([]);
-  return { content: renderLines(lines, limit, []), ok: true };
+  const failed = ran.stopped !== undefined || ran.exit !== 0 && ran.exit !== 1;
+  const reason = ran.stopped ?? "engine_error";
+  const observation: SearchObservation = { engine: "ripgrep", raw: ran.raw, ...(ran.rawErrors ? { rawErrors: ran.rawErrors } : {}), rows: hits.map(hit => ({ prefix: `${hit.path}:${hit.line}: `, text: hit.text })),
+    sources: [], limit, empty: "No matches found", scan: { status: failed ? "partial" : "unknown", examined_files: null, source_versions: "unknown",
+      reasons: [{ code: "engine_does_not_report_all_skipped_files" }, ...(failed ? [{ code: reason }] : [])] } };
+  return observed(observation, ran.diagnostic ?? (failed ? failureDiagnostic(reason === "timeout" || reason === "cancelled" ? reason : "execution_failed",
+    ran.stderr.trim() || `ripgrep ${reason}; exit ${ran.exit ?? "unknown"}`, READ_ATTEMPTED) : undefined));
 }
 
 function compareMatch(a: MatchLine, b: MatchLine): number {
@@ -438,61 +465,80 @@ async function grepWalk(opts: GrepOpts, abs: string, kind: "file" | "dir", rel:
   try {
     new RegExp(opts.pattern);
   } catch (err) {
-    return { content: `invalid regex: ${(err as Error).message}`, ok: false };
+    return searchFailure("invalid_input", `invalid regex: ${(err as Error).message}`);
   }
 
-  const files = await listedFiles(abs, rel, kind);
+  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 glob = opts.glob;
-  const filtered = glob === undefined ? files : files.filter((p) => globMatches(glob, p));
+  const filtered = glob === undefined ? files.paths : files.paths.filter((p) => globMatches(glob, p));
   const matcher = new LineMatcher();
   const hits: MatchLine[] = [];
-  const notices: string[] = [];
+  const reasons: SearchObservation["scan"]["reasons"] = [...files.issues];
+  const sources: SearchObservation["sources"] = [];
+  let examined = 0, capturedBytes = 0;
+  const budget = Math.min(opts.maxCaptureBytes ?? MAX_SEARCH_CAPTURE_BYTES, MAX_SEARCH_CAPTURE_BYTES);
   try {
     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;
       const fileAbs = join(opts.root, fileRel);
       let st;
       try {
         st = await lstat(fileAbs);
       } catch {
+        reasons.push({ code: "unreadable_file", path: fileRel });
         continue;
       }
-      if (st.isSymbolicLink() || !st.isFile()) continue;
-      if (st.size > MAX_FILE_BYTES) continue;
+      if (st.isSymbolicLink() || !st.isFile()) { reasons.push({ code: "changed_file_type", path: fileRel }); continue; }
+      if (st.size > MAX_FILE_BYTES) { reasons.push({ code: "file_size_limit", path: fileRel }); continue; }
       let text: string;
       try {
-        text = await readFile(fileAbs, "utf8");
+        const raw = await readFile(fileAbs);
+        if (raw.length > MAX_FILE_BYTES) { reasons.push({ code: "file_size_limit", path: fileRel }); continue; }
+        text = new TextDecoder("utf-8", { fatal: true }).decode(raw);
+        sources.push({ path: fileRel, sha256: blobAddress(raw) }); examined++;
       } catch {
+        reasons.push({ code: "unreadable_or_non_utf8_file", path: fileRel });
         continue;
       }
-      if (text.includes("\0")) continue;
+      if (text.includes("\0")) { reasons.push({ code: "binary_file", path: fileRel }); continue; }
       const lines = splitLines(text);
-      const matched = await matcher.match(opts.pattern, "", lines);
+      // Reserve the worst-case formatted hits before matching, never discard already observed hits.
+      const reservation = Buffer.byteLength(text) + lines.length * (Buffer.byteLength(fileRel) + String(MAX_FILE_BYTES).length + 3);
+      if (capturedBytes + reservation > budget) { reasons.push({ code: "capture_budget", path: fileRel }); break; }
+      const matched = await matcher.match(opts.pattern, "", lines, deadline - performance.now(), opts.signal);
+      if (matched === "cancelled") { reasons.push({ code: "cancelled", path: fileRel }); break; }
       if (matched === "timeout") {
-        notices.push(`search cut off on ${fileRel} after ${MATCH_TIMEOUT_MS}ms`);
+        reasons.push({ code: "match_timeout", path: fileRel });
         continue;
       }
       if (matched === "invalid") {
-        return { content: `invalid regex: ${opts.pattern}`, ok: false };
+        reasons.push({ code: "matcher_failed", path: fileRel }); break;
+      }
+      for (const hit of matched) {
+        hits.push({ path: fileRel, line: hit.line, text: hit.text });
+        capturedBytes += Buffer.byteLength(`${fileRel}:${hit.line}: ${hit.text}\n`);
       }
-      for (const hit of matched) hits.push({ path: fileRel, line: hit.line, text: hit.text });
     }
   } finally {
     matcher.close();
   }
 
   hits.sort(compareMatch);
-  const formatted = hits.map(formatMatch);
-  if (formatted.length === 0) return noMatches(notices);
-  return { content: renderLines(formatted, limit, notices), ok: true };
+  const stopped = reasons.find(reason => ["timeout", "cancelled"].includes(reason.code));
+  return observed({ engine: "walk", rows: hits.map(hit => ({ prefix: `${hit.path}:${hit.line}: `, text: hit.text })), sources, limit, empty: "No matches found",
+    scan: { status: reasons.length ? "partial" : "complete", reasons, examined_files: examined, source_versions: "recorded" } },
+    stopped ? failureDiagnostic(stopped.code === "cancelled" ? "cancelled" : "timeout", `search ${stopped.code}`, READ_ATTEMPTED) : undefined);
 }
 
 export async function grep(opts: GrepOpts): Promise<SearchResult> {
   const pattern = opts.pattern;
-  if (pattern.length === 0) return { content: "grep needs a pattern", ok: false };
+  if (pattern.length === 0) return searchFailure("invalid_input", "grep needs a pattern");
 
   const target = await inspectTarget(opts.root, opts.path);
-  if ("error" in target) return { content: target.error, ok: false };
+  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";
@@ -502,7 +548,7 @@ export async function grep(opts: GrepOpts): Promise<SearchResult> {
       return grepWalk(opts, opts.path, target.kind, target.rel, limit);
     case "ripgrep": {
       const got = await grepRipgrep(opts, opts.path, limit);
-      if (got === null) return { content: "ripgrep is not on PATH", ok: false };
+      if (got === null) return searchFailure("environment_missing", "ripgrep is not on PATH");
       return got;
     }
     case "auto": {
@@ -532,6 +578,7 @@ async function findFd(opts: FindOpts, abs: string, limit: number): Promise<Searc
     "--hidden",
     "--no-ignore",
     "--absolute-path",
+    "--print0",
     ...fdExcludeArgs(),
   ];
   let pattern = opts.pattern;
@@ -540,36 +587,40 @@ async function findFd(opts: FindOpts, abs: string, limit: number): Promise<Searc
     if (!pattern.startsWith("**/") && pattern !== "**") pattern = `**/${pattern}`;
   }
   args.push("--", pattern, abs);
-  const ran = await runCommand(fd, args, opts.timeoutMs ?? PROCESS_TIMEOUT_MS);
-  if (ran.exit !== 0 && ran.stdout.trim().length === 0) {
-    const err = ran.stderr.trim() || `fd exited ${ran.exit ?? "null"}`;
-    return { content: err, ok: false };
-  }
+  const ran = await runCommand(fd, args, opts.timeoutMs ?? PROCESS_TIMEOUT_MS, opts.signal, opts.maxCaptureBytes);
   const paths: string[] = [];
-  for (const raw of ran.stdout.split("\n")) {
-    const line = raw.replace(/\r$/, "").trim();
+  // A partial final record is not a path. NUL preserves spaces and newlines in real filenames.
+  for (const line of ran.stdout.split("\0").slice(0, -1)) {
     if (line.length === 0) continue;
     const rel = posixRel(opts.root, line);
     if (rel === null || ignoredRel(rel)) continue;
     paths.push(rel);
   }
   paths.sort((a, b) => (a < b ? -1 : 1));
-  if (paths.length === 0) return { content: "No files found matching pattern", ok: true };
-  return { content: renderLines(paths, limit, []), ok: true };
+  const failed = ran.stopped !== undefined || ran.exit !== 0;
+  const reason = ran.stopped ?? "engine_error";
+  return observed({ engine: "fd", raw: ran.raw, ...(ran.rawErrors ? { rawErrors: ran.rawErrors } : {}), rows: paths.map(text => ({ prefix: "", text })), limit, empty: "No files found matching pattern", sources: [],
+    scan: { status: failed ? "partial" : "unknown", examined_files: null, source_versions: "unknown",
+      reasons: [{ code: "engine_does_not_report_all_skipped_files" }, ...(failed ? [{ code: reason }] : [])] } },
+    ran.diagnostic ?? (failed ? failureDiagnostic(reason === "timeout" || reason === "cancelled" ? reason : "execution_failed",
+      ran.stderr.trim() || `fd ${reason}; exit ${ran.exit ?? "unknown"}`, READ_ATTEMPTED) : undefined));
 }
 
 async function findWalk(opts: FindOpts, abs: string, kind: "file" | "dir", rel: string, limit: number): Promise<SearchResult> {
-  const files = await listedFiles(abs, rel, kind);
-  const paths = files.filter((p) => !ignoredRel(p) && globMatches(opts.pattern, p));
+  const files = await listedFiles(abs, rel, kind, { deadline: performance.now() + (opts.timeoutMs ?? PROCESS_TIMEOUT_MS),
+    ...(opts.signal ? { signal: opts.signal } : {}), ...(opts.maxIndexEntries === undefined ? {} : { maxEntries: opts.maxIndexEntries }) });
+  const paths = files.paths.filter((p) => !ignoredRel(p) && globMatches(opts.pattern, p));
   paths.sort((a, b) => (a < b ? -1 : 1));
-  if (paths.length === 0) return { content: "No files found matching pattern", ok: true };
-  return { content: renderLines(paths, limit, []), ok: true };
+  const stopped = files.issues.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" } },
+    stopped ? failureDiagnostic(stopped.code === "cancelled" ? "cancelled" : "timeout", `search ${stopped.code}`, READ_ATTEMPTED) : undefined);
 }
 
 export async function find(opts: FindOpts): Promise<SearchResult> {
-  if (opts.pattern.length === 0) return { content: "find needs a pattern", ok: false };
+  if (opts.pattern.length === 0) return searchFailure("invalid_input", "find needs a pattern");
   const target = await inspectTarget(opts.root, opts.path);
-  if ("error" in target) return { content: target.error, ok: false };
+  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";
   switch (engine) {
@@ -577,7 +628,7 @@ export async function find(opts: FindOpts): Promise<SearchResult> {
       return findWalk(opts, opts.path, target.kind, target.rel, limit);
     case "fd": {
       const got = await findFd(opts, opts.path, limit);
-      if (got === null) return { content: "fd is not on PATH", ok: false };
+      if (got === null) return searchFailure("environment_missing", "fd is not on PATH");
       return got;
     }
     case "auto": {
@@ -593,15 +644,16 @@ export async function find(opts: FindOpts): Promise<SearchResult> {
 }
 
 export async function ls(opts: LsOpts): Promise<SearchResult> {
+  if (opts.signal?.aborted) return searchFailure("cancelled", "directory listing cancelled");
   const target = await inspectTarget(opts.root, opts.path);
-  if ("error" in target) return { content: target.error, ok: false };
-  if (target.kind !== "dir") return { content: `not a directory: ${target.rel || "."}`, ok: false };
+  if ("error" in target) return { content: target.error, ok: false, diagnostic: target.diagnostic };
+  if (target.kind !== "dir") return searchFailure("invalid_input", `not a directory: ${target.rel || "."}`);
 
   let entries;
   try {
     entries = await readdir(opts.path, { withFileTypes: true });
   } catch (err) {
-    return { content: `cannot list ${target.rel || "."}: ${(err as Error).message}`, ok: false };
+    return { content: `cannot list ${target.rel || "."}: ${(err as Error).message}`, ok: false, diagnostic: failureFromError(err, READ_ATTEMPTED) };
   }
 
   const names: string[] = [];
@@ -626,19 +678,6 @@ export async function ls(opts: LsOpts): Promise<SearchResult> {
   });
 
   const limit = opts.limit !== undefined && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_LS_LIMIT;
-  if (names.length === 0) return { content: "(empty directory)", ok: true };
-  const omitted = Math.max(0, names.length - limit);
-  const shown = names.slice(0, limit);
-  let body = shown.join("\n");
-  let extra = omitted;
-  while (shown.length > 0 && body.length > MAX_OUTPUT_BYTES) {
-    shown.pop();
-    extra += 1;
-    body = shown.join("\n");
-  }
-  if (extra > 0) {
-    const note = `[${extra} more matches omitted]`;
-    body = body.length > 0 ? `${body}\n${note}` : note;
-  }
-  return { content: body, ok: true };
+  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" } });
 }

package/src/store/session-archive.ts

@@ -40,6 +40,10 @@ async function referencedBlobs(dir: string, fallback?: string): Promise<Map<stri
     const add = (sha: string) => { refs.set(sha, [...new Set([...(refs.get(sha) ?? []), ...roots])]); };
     for (const event of read.events) {
       if (event.t === "snapshot") for (const sha of [...Object.values(event.added), ...Object.values(event.changed)]) add(sha);
+      if (event.t === "checkpoint") for (const change of Object.values(event.changes)) {
+        if (change.before) add(change.before.sha256);
+        if (change.after) add(change.after.sha256);
+      }
       if (event.t === "user" || event.t === "tool_result") for (const image of event.images ?? []) { add(image.sha256); if (image.original) add(image.original.sha256); }
     }
   }

package/src/store/source-cancellation.ts

@@ -0,0 +1,6 @@
+/** D11: cancelled source capture never becomes a partial successful observation. */
+import { ToolFault, READ_ATTEMPTED } from "../core/tool-failure.ts";
+
+export function checkSourceCancellation(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new ToolFault("cancelled", "source capture cancelled", READ_ATTEMPTED);
+}

package/src/store/update-cache.ts

@@ -0,0 +1,36 @@
+/**
+ * The last update check, kept in the config directory (docs/tasks/feat-update-check.md).
+ *
+ * `{ checkedAt, latest? }` and nothing else: no identifiers, no history. A
+ * missing or unreadable file means "never checked"; it is rewritten whole.
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { UpdateCache } from "../core/update-check.ts";
+import { atomicWrite } from "./atomic.ts";
+import { configDir } from "./config.ts";
+
+export function updateCachePath(): string { return join(configDir(), "update-check.json"); }
+
+export async function readUpdateCache(): Promise<UpdateCache | null> {
+  try {
+    const value = JSON.parse(await readFile(updateCachePath(), "utf8")) as Record<string, unknown>;
+    if (typeof value["checkedAt"] !== "number") return null;
+    return { checkedAt: value["checkedAt"], ...(typeof value["latest"] === "string" ? { latest: value["latest"] } : {}) };
+  } catch { return null; }
+}
+
+export async function writeUpdateCache(cache: UpdateCache): Promise<void> {
+  try { await atomicWrite(updateCachePath(), JSON.stringify(cache) + "\n"); } catch { /* a read-only config dir only means checking again next time */ }
+}
+
+/** This copy's package root, resolved through symlinks, and whether it is a git checkout. */
+export function packageLocation(): { root: string; git: boolean } {
+  // src/store/update-cache.ts → the package root two directories up.
+  const here = dirname(fileURLToPath(import.meta.url));
+  let root = join(here, "..", "..");
+  try { root = realpathSync(root); } catch { /* keep the unresolved path */ }
+  return { root, git: existsSync(join(root, ".git")) };
+}