@visual-z/xeno 0.8.4 → 0.9.0

package/src/core/external-effects.ts

@@ -1,488 +0,0 @@
-/**
- * What this request's executed commands did outside the workspace
- * (feat-external-effects-summary).
- *
- * The permission design deliberately has no command-danger classifier
- * (permissions.ts): a screen that misses something implies someone is
- * checking. This is the opposite stance -- a statement after the fact, shown
- * to the person when a request ends, never a gate. Its failure mode decides
- * its shape: a missed item is one line fewer; a wrong item teaches the person
- * to ignore the line. So everything here prefers silence to a guess:
- * unparseable commands are skipped whole, and a path containing a variable or
- * a command substitution is never resolved.
- *
- * Only executed commands count: the input is `tool_result` receipts with a
- * `command` effect, which a denied or cancelled call never has. Nothing here
- * is stored; the list is recomputed from the log whenever it is shown (D8).
- *
- * Pure: the home and temporary directories are parameters, never read here.
- */
-import type { LogEvent } from "./events.ts";
-import { normalizePermissionPath } from "./permissions.ts";
-
-export type ExternalCategory = "write" | "process" | "system" | "network" | "push";
-export interface ExternalEffect {
-  readonly category: ExternalCategory;
-  /** The simple command that did it, truncated for display. */
-  readonly command: string;
-  /** The receipt that ran it. */
-  readonly event: string;
-  /** The resolved outside path, for writes. */
-  readonly path?: string;
-}
-export interface ExternalOptions {
-  /** Expands `~` and `$HOME`. Absent: such paths are dynamic and skipped. */
-  readonly home?: string;
-  /** Extra temporary roots (the platform's os.tmpdir()); /tmp and /var/tmp are always temporary. */
-  readonly temp?: readonly string[];
-}
-
-/** Display bound for one item; long heredoc commands would otherwise fill the line. */
-const SNIPPET_CHARS = 60;
-/** Assumed bound on nested `sh -c` analysis; deeper nesting is skipped, not guessed. */
-const MAX_NESTING = 3;
-const ALWAYS_TEMPORARY = ["/tmp", "/private/tmp", "/var/tmp", "/private/var/tmp", "/dev"];
-
-// ---------------------------------------------------------------------------
-// Lexer: a deliberately small subset of POSIX shell. Anything outside it makes
-// the whole command unparseable, which means "report nothing".
-// ---------------------------------------------------------------------------
-
-/** A word with its literal value, or null when part of it is only known at run time. */
-type Word = { text: string; value: string | null; quoted: boolean };
-type Token =
-  | { kind: "word"; word: Word }
-  | { kind: "op"; op: string }
-  | { kind: "redirect"; op: string; fd: string };
-
-const OPERATORS = ["&&", "||", ";;", "|&", ";", "|", "&", "(", ")", "\n"];
-
-/** Tokens, or null when the command does not fit the subset (unclosed quote, unterminated heredoc). */
-function lex(input: string, home: string | undefined): Token[] | null {
-  const tokens: Token[] = [];
-  const heredocs: { delimiter: string; strip: boolean }[] = [];
-  let i = 0;
-  const at = (offset = 0) => input[i + offset] ?? "";
-  while (i < input.length) {
-    const char = at();
-    if (char === "\n") {
-      tokens.push({ kind: "op", op: "\n" }); i++;
-      // Heredoc bodies are data, never commands: skip them line by line.
-      for (const doc of heredocs.splice(0)) {
-        for (;;) {
-          if (i >= input.length) return null;
-          const end = input.indexOf("\n", i);
-          const line = input.slice(i, end < 0 ? input.length : end);
-          i = end < 0 ? input.length : end + 1;
-          if ((doc.strip ? line.replace(/^\t+/, "") : line) === doc.delimiter) break;
-        }
-      }
-      continue;
-    }
-    if (char === " " || char === "\t") { i++; continue; }
-    if (char === "\\" && at(1) === "\n") { i += 2; continue; }
-    if (char === "#") { while (i < input.length && at() !== "\n") i++; continue; }
-    // Redirections, optionally with a leading descriptor (2>, &>).
-    const redirect = /^(\d*|&)(>>|>\||>&|>|<<<|<<-|<<|<>|<&|<)/.exec(input.slice(i));
-    if (redirect && (redirect[1] !== "&" || redirect[2]!.startsWith(">"))) {
-      const op = redirect[2]!;
-      i += redirect[0].length;
-      if (op === "<<" || op === "<<-") {
-        while (at() === " " || at() === "\t") i++;
-        const word = readWord();
-        if (word === null || word.text === "") return null;
-        heredocs.push({ delimiter: word.text, strip: op === "<<-" });
-        continue;
-      }
-      tokens.push({ kind: "redirect", op, fd: redirect[1]! });
-      continue;
-    }
-    const operator = OPERATORS.find(candidate => input.startsWith(candidate, i));
-    if (operator) { tokens.push({ kind: "op", op: operator }); i += operator.length; continue; }
-    const word = readWord();
-    if (word === null) return null;
-    tokens.push({ kind: "word", word });
-  }
-  if (heredocs.length) return null;
-  return tokens;
-
-  /** One word; `text` is the unquoted spelling (heredoc delimiters, display), `value` the resolved literal. */
-  function readWord(): Word | null {
-    let text = "", value: string | null = "", quoted = false;
-    const start = i;
-    const dynamic = () => { value = null; };
-    while (i < input.length) {
-      const char = at();
-      if (" \t\n;&|()<>".includes(char)) break;
-      if (char === "'") {
-        const end = input.indexOf("'", i + 1);
-        if (end < 0) return null;
-        const part = input.slice(i + 1, end);
-        text += part; if (value !== null) value += part; quoted = true; i = end + 1; continue;
-      }
-      if (char === '"') {
-        i++; quoted = true;
-        for (;;) {
-          if (i >= input.length) return null;
-          const inner = at();
-          if (inner === '"') { i++; break; }
-          if (inner === "\\" && '$`"\\\n'.includes(at(1))) { text += at(1); if (value !== null) value += at(1); i += 2; continue; }
-          if (inner === "$" || inner === "`") {
-            const expanded = expansion(true);
-            if (expanded === undefined) return null;
-            text += expanded.text; if (expanded.value === null) dynamic(); else if (value !== null) value += expanded.value;
-            continue;
-          }
-          text += inner; if (value !== null) value += inner; i++;
-        }
-        continue;
-      }
-      if (char === "\\") {
-        if (i + 1 >= input.length) return null;
-        text += at(1); if (value !== null) value += at(1); i += 2; continue;
-      }
-      if (char === "$" || char === "`") {
-        const expanded = expansion(false);
-        if (expanded === undefined) return null;
-        text += expanded.text; if (expanded.value === null) dynamic(); else if (value !== null) value += expanded.value;
-        continue;
-      }
-      if (char === "~" && i === start) {
-        // Only a bare leading ~ or ~/ is the home directory; ~user is not guessed.
-        const next = at(1);
-        if (next === "" || next === "/" || " \t\n;&|()<>".includes(next)) {
-          text += "~"; if (home === undefined) dynamic(); else if (value !== null) value += home; i++; continue;
-        }
-        text += char; dynamic(); i++; continue;
-      }
-      if ("*?[{".includes(char)) { text += char; dynamic(); i++; continue; }
-      text += char; if (value !== null) value += char; i++;
-    }
-    return { text, value, quoted };
-  }
-
-  /** `$HOME` / `${HOME}` expand; every other expansion makes the word dynamic. undefined: unparseable. */
-  function expansion(inDouble: boolean): { text: string; value: string | null } | undefined {
-    const start = i;
-    if (at() === "`") {
-      const end = input.indexOf("`", i + 1);
-      if (end < 0) return undefined;
-      i = end + 1; return { text: input.slice(start, i), value: null };
-    }
-    // $(...) / $((...)): balanced parentheses, quotes inside are skipped coarsely.
-    if (at(1) === "(") {
-      let depth = 0;
-      for (; i < input.length; i++) {
-        const char = at();
-        if (char === "'" && !inDouble) { const end = input.indexOf("'", i + 1); if (end < 0) return undefined; i = end; continue; }
-        if (char === "(") depth++;
-        if (char === ")" && --depth === 0) { i++; return { text: input.slice(start, i), value: null }; }
-      }
-      return undefined;
-    }
-    if (at(1) === "{") {
-      const end = input.indexOf("}", i);
-      if (end < 0) return undefined;
-      const name = input.slice(i + 2, end);
-      i = end + 1;
-      return { text: input.slice(start, i), value: name === "HOME" && home !== undefined ? home : null };
-    }
-    const name = /^[A-Za-z_][A-Za-z0-9_]*|^[0-9@*#?$!-]/.exec(input.slice(i + 1))?.[0];
-    if (!name) { i++; return { text: "$", value: "$" }; }
-    i += 1 + name.length;
-    return { text: input.slice(start, i), value: name === "HOME" && home !== undefined ? home : null };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-
-type Simple = { words: Word[]; redirects: { op: string; fd: string; target: Word | null }[]; text: string };
-type Context = { root: string; options: ExternalOptions; event: string; out: ExternalEffect[]; depth: number };
-
-const WRITE_COMMANDS = new Set(["cp", "mv", "ln", "rm", "rmdir", "mkdir", "touch", "chmod", "chown", "chgrp", "tee", "install", "rsync", "truncate"]);
-/** Words that run the rest of the line as a command; their own options are skipped. */
-const PREFIXES = new Set(["sudo", "doas", "env", "command", "builtin", "exec", "nohup", "time", "nice", "xargs"]);
-
-function inside(path: string, root: string): boolean {
-  return path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
-}
-
-function absolute(path: string, cwd: string): string {
-  return normalizePermissionPath(path.startsWith("/") ? path : `${cwd}/${path}`);
-}
-
-function snippet(text: string): string {
-  const line = text.replace(/\s+/g, " ").trim();
-  return line.length > SNIPPET_CHARS ? `${line.slice(0, SNIPPET_CHARS - 1)}…` : line;
-}
-
-/** The outside path a literal target resolves to, or null (inside, temporary, or dynamic). */
-function outside(target: Word | null, cwd: string | null, ctx: Context): string | null {
-  if (!target || target.value === null || target.value === "" || cwd === null) return null;
-  // `-` is stdout/stdin for tee and friends.
-  if (target.value === "-") return null;
-  const path = absolute(target.value, cwd);
-  const root = normalizePermissionPath(ctx.root);
-  if (inside(path, root)) return null;
-  for (const temp of [...ALWAYS_TEMPORARY, ...ctx.options.temp ?? []]) if (inside(path, normalizePermissionPath(temp))) return null;
-  return path;
-}
-
-/** Splits tokens into simple commands; `cd` state is threaded across `&&`, `;` and newlines, restored by `)`. */
-function analyse(tokens: Token[], cwd: string, ctx: Context): void {
-  const stack: (string | null)[] = [];
-  let current: string | null = cwd;
-  let simple: Simple = { words: [], redirects: [], text: "" };
-  let pendingRedirect: { op: string; fd: string } | null = null;
-  const flush = () => {
-    if (pendingRedirect) { simple.redirects.push({ ...pendingRedirect, target: null }); pendingRedirect = null; }
-    if (simple.words.length || simple.redirects.length) current = command(simple, current, ctx);
-    simple = { words: [], redirects: [], text: "" };
-  };
-  for (const token of tokens) {
-    if (token.kind === "op") {
-      flush();
-      if (token.op === "(") stack.push(current);
-      if (token.op === ")") current = stack.length ? stack.pop()! : current;
-      continue;
-    }
-    if (token.kind === "redirect") {
-      if (pendingRedirect) simple.redirects.push({ ...pendingRedirect, target: null });
-      pendingRedirect = { op: token.op, fd: token.fd };
-      simple.text += `${simple.text ? " " : ""}${token.fd}${token.op}`;
-      continue;
-    }
-    simple.text += `${simple.text && !pendingRedirect ? " " : ""}${token.word.text}`;
-    if (pendingRedirect) { simple.redirects.push({ ...pendingRedirect, target: token.word }); pendingRedirect = null; continue; }
-    simple.words.push(token.word);
-  }
-  flush();
-}
-
-/** One simple command; returns the working directory after it (null: unknown, so later paths are not guessed). */
-function command(simple: Simple, cwd: string | null, ctx: Context): string | null {
-  const add = (category: ExternalCategory, path?: string) => {
-    if (ctx.out.some(item => item.event === ctx.event && item.category === category && item.path === path && item.command === snippet(simple.text))) return;
-    ctx.out.push({ category, command: snippet(simple.text), event: ctx.event, ...(path === undefined ? {} : { path }) });
-  };
-  for (const redirect of simple.redirects) {
-    if (!redirect.op.startsWith(">") && redirect.op !== "<>") continue;
-    // >&2 duplicates a descriptor; it names no file.
-    if (redirect.op === ">&" && redirect.target?.value !== null && /^\d+$|^-$/.test(redirect.target?.value ?? "")) continue;
-    const path = outside(redirect.target, cwd, ctx);
-    if (path) add("write", path);
-  }
-  let words = simple.words;
-  // Leading assignments (FOO=bar cmd) and wrappers (sudo, env -i) are not the command.
-  for (;;) {
-    while (words.length && words[0]!.value !== null && !words[0]!.quoted && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]!.value!)) words = words.slice(1);
-    const head = words[0]?.value;
-    if (head === undefined || head === null || !PREFIXES.has(baseName(head))) break;
-    words = words.slice(1);
-    while (words.length && (words[0]!.value ?? "").startsWith("-")) words = words.slice(1);
-  }
-  if (!words.length) return cwd;
-  const name = words[0]!.value;
-  if (name === null) return cwd;
-  const base = baseName(name);
-  const args = words.slice(1);
-  const values = args.map(word => word.value);
-
-  switch (base) {
-    case "cd": case "pushd": {
-      const target = args.find(word => !(word.value ?? "").startsWith("-") || word.value === "-");
-      if (!target) return ctx.options.home ?? null;
-      if (target.value === null || target.value === "-" || cwd === null) return null;
-      return absolute(target.value, cwd);
-    }
-    case "popd": return null;
-    case "sh": case "bash": case "zsh": case "dash": {
-      const flag = args.findIndex(word => /^-[a-z]*c[a-z]*$/.test(word.value ?? ""));
-      const script = flag >= 0 ? args[flag + 1] : undefined;
-      if (script?.value && ctx.depth < MAX_NESTING) {
-        const tokens = lex(script.value, ctx.options.home);
-        if (tokens && cwd !== null) analyse(tokens, cwd, { ...ctx, depth: ctx.depth + 1 });
-      }
-      return cwd;
-    }
-    case "kill":
-      // kill -0 probes and kill -l lists; neither changes a process.
-      if (values.some(value => value === "-0" || value === "-l" || value === "-L" || value === "-s0")) return cwd;
-      if (args.length) add("process");
-      return cwd;
-    case "killall": case "pkill":
-      if (args.length) add("process");
-      return cwd;
-    case "launchctl": {
-      const sub = values[0];
-      if (sub && ["load", "unload", "bootstrap", "bootout", "kickstart", "kill", "start", "stop", "enable", "disable", "remove", "submit", "setenv", "unsetenv"].includes(sub)) add("system");
-      return cwd;
-    }
-    case "systemctl": {
-      const sub = values.find(value => value !== null && !value.startsWith("-"));
-      if (sub && ["start", "stop", "restart", "reload", "enable", "disable", "mask", "unmask", "kill", "daemon-reload", "set-property", "edit", "isolate", "try-restart", "reload-or-restart"].includes(sub)) add("system");
-      return cwd;
-    }
-    case "defaults": {
-      const sub = values.find(value => value !== null && !value.startsWith("-"));
-      if (sub && ["write", "delete", "import", "rename"].includes(sub)) add("system");
-      return cwd;
-    }
-    case "brew": {
-      const sub = values.find(value => value !== null && !value.startsWith("-"));
-      if (sub && ["install", "upgrade", "uninstall", "reinstall", "remove", "rm", "link", "unlink", "tap", "untap"].includes(sub)) add("system");
-      return cwd;
-    }
-    case "npm": case "pnpm": case "yarn": case "bun": {
-      const global = values.some(value => value === "-g" || value === "--global" || value === "--location=global");
-      const sub = values.find(value => value !== null && !value.startsWith("-"));
-      if (global && sub && ["install", "i", "add", "uninstall", "remove", "rm", "un", "update", "upgrade", "link"].includes(sub)) add("system");
-      if (base === "yarn" && sub === "global") add("system");
-      return cwd;
-    }
-    case "pip": case "pip3": {
-      const sub = values.find(value => value !== null && !value.startsWith("-"));
-      if (sub === "install" || sub === "uninstall") add("system");
-      return cwd;
-    }
-    case "python": case "python3": {
-      const module = values.indexOf("-m");
-      if (module >= 0 && /^pip3?$/.test(values[module + 1] ?? "") && ["install", "uninstall"].includes(values[module + 2] ?? "")) add("system");
-      return cwd;
-    }
-    case "curl":
-      if (curlMutates(values)) add("network");
-      return cwd;
-    case "wget":
-      if (values.some(value => value !== null && /^--(post-data|post-file|body-data|body-file|method)(=|$)/.test(value))) add("network");
-      return cwd;
-    case "git": {
-      // Global options before the subcommand: -C dir, -c k=v, --git-dir=...
-      let index = 0;
-      while (index < values.length && (values[index] ?? "").startsWith("-")) index += ["-C", "-c"].includes(values[index] ?? "") ? 2 : 1;
-      if (values[index] === "push" && !values.slice(index + 1).some(value => value === "--dry-run" || value === "-n")) add("push");
-      return cwd;
-    }
-  }
-  // A dynamic operand could be any path; writeTargets judges only literal ones.
-  if (WRITE_COMMANDS.has(base)) for (const path of writeTargets(base, args, cwd, ctx)) add("write", path);
-  return cwd;
-}
-
-function baseName(path: string): string {
-  return path.slice(path.lastIndexOf("/") + 1);
-}
-
-/** Paths the command writes, among its literal operands, resolved and outside. */
-function writeTargets(base: string, args: Word[], cwd: string | null, ctx: Context): string[] {
-  const operands: Word[] = [];
-  let targetDirectory: Word | null = null;
-  let options = true;
-  for (let index = 0; index < args.length; index++) {
-    const word = args[index]!;
-    const value = word.value;
-    if (options && value === "--") { options = false; continue; }
-    if (options && value !== null && value.startsWith("-") && value !== "-") {
-      if ((base === "cp" || base === "mv" || base === "ln" || base === "install") && (value === "-t" || value === "--target-directory")) { targetDirectory = args[++index] ?? null; continue; }
-      if (value.startsWith("--target-directory=")) { targetDirectory = { ...word, value: value.slice("--target-directory=".length) }; continue; }
-      // Options that take a separate value; the value is not an operand.
-      if ((base === "chmod" || base === "chown" || base === "chgrp") && value === "--reference") { index++; continue; }
-      if (base === "install" && ["-m", "-o", "-g"].includes(value)) { index++; continue; }
-      if (base === "truncate" && (value === "-s" || value === "-r")) { index++; continue; }
-      if (base === "mkdir" && value === "-m") { index++; continue; }
-      continue;
-    }
-    operands.push(word);
-  }
-  let targets: Word[];
-  switch (base) {
-    case "cp": case "mv": case "ln": case "install": case "rsync":
-      // The destination is the last operand (or -t); sources are read, not written.
-      targets = targetDirectory ? [targetDirectory] : operands.length >= 2 ? [operands.at(-1)!] : [];
-      // mv also removes its sources.
-      if (base === "mv") targets = [...targets, ...operands.slice(0, targetDirectory ? operands.length : -1)];
-      break;
-    case "chmod": case "chown": case "chgrp":
-      // The first operand is the mode or owner.
-      targets = operands.slice(1);
-      break;
-    default:
-      targets = operands;
-  }
-  // rsync destinations may be remote (host:path); those are network, not local writes.
-  if (base === "rsync") targets = targets.filter(word => word.value !== null && !/^[^/]*:/.test(word.value));
-  return targets.map(word => outside(word, cwd, ctx)).filter((path): path is string => path !== null);
-}
-
-function curlMutates(values: readonly (string | null)[]): boolean {
-  let get = false, data = false, method: string | null = null;
-  for (let index = 0; index < values.length; index++) {
-    const value = values[index];
-    if (value === null || value === undefined) continue;
-    if (value === "-G" || value === "--get") get = true;
-    else if (value === "-X" || value === "--request") method = (values[++index] ?? "").toUpperCase();
-    else if (value.startsWith("--request=")) method = value.slice("--request=".length).toUpperCase();
-    else if (/^-X./.test(value)) method = value.slice(2).toUpperCase();
-    else if (/^--(data|data-raw|data-binary|data-urlencode|data-ascii|json)(=|$)/.test(value) || /^-d/.test(value)) data = true;
-    else if (/^--(form|form-string|upload-file)(=|$)/.test(value) || /^-[FT]/.test(value)) return true;
-    else if (/^-[a-zA-Z]+$/.test(value) && !value.startsWith("--")) {
-      // Bundled short flags: -sSd ... or -sX POST.
-      const flags = value.slice(1);
-      if (flags.includes("G")) get = true;
-      if (/[FT]/.test(flags)) return true;
-      if (flags.endsWith("X")) method = (values[++index] ?? "").toUpperCase();
-      else if (flags.endsWith("d")) data = true;
-    }
-  }
-  if (method !== null) return method !== "GET" && method !== "HEAD";
-  return data && !get;
-}
-
-/** One command string's effects; exported for the property tests and for single-receipt views. */
-export function commandExternalEffects(cmd: string, event: string, workspaceRoot: string, options: ExternalOptions = {}, cwd = workspaceRoot): ExternalEffect[] {
-  const tokens = lex(cmd, options.home);
-  if (!tokens) return [];
-  const out: ExternalEffect[] = [];
-  analyse(tokens, normalizePermissionPath(cwd), { root: workspaceRoot, options, event, out, depth: 0 });
-  return out;
-}
-
-/**
- * The current request's outside effects, in log order. `events` is the
- * request's own slice (currentRequestEvents); a workdir on the call is
- * honoured when it is a literal relative or absolute path.
- */
-export function externalEffects(events: readonly LogEvent[], workspaceRoot: string, options: ExternalOptions = {}): ExternalEffect[] {
-  const workdirs = new Map<string, string>();
-  for (const event of events) {
-    if (event.t !== "assistant") continue;
-    for (const block of event.blocks) {
-      if (block.type !== "tool_use" || block.input === null || typeof block.input !== "object") continue;
-      const workdir = (block.input as Record<string, unknown>)["workdir"];
-      if (typeof workdir === "string" && workdir !== "") workdirs.set(block.call_id, workdir);
-    }
-  }
-  const root = normalizePermissionPath(workspaceRoot);
-  const out: ExternalEffect[] = [];
-  for (const event of events) {
-    if (event.t !== "tool_result" || event.effect?.kind !== "command") continue;
-    const workdir = workdirs.get(event.call_id);
-    out.push(...commandExternalEffects(event.effect.cmd, event.id, root, options, workdir ? absolute(workdir, root) : root));
-  }
-  return out;
-}
-
-/** Display bound: the line names the first few and counts the rest. */
-export const EXTERNAL_SHOWN = 5;
-
-/** One line for the end of a request, or null when nothing reached outside. */
-export function formatExternalEffects(effects: readonly ExternalEffect[], options: { home?: string } = {}): string | null {
-  if (!effects.length) return null;
-  const tilde = (path: string) => options.home && inside(path, options.home) ? `~${path.slice(options.home.length)}` : path;
-  const label = (effect: ExternalEffect) => effect.category === "write" && effect.path ? `write ${tilde(effect.path)}` : effect.command;
-  const shown = effects.slice(0, EXTERNAL_SHOWN).map(label);
-  const rest = effects.length - shown.length;
-  return `Outside the workspace: ${shown.join(" · ")}${rest > 0 ? ` · and ${rest} more` : ""}`;
-}

package/src/core/failure-recovery.ts

@@ -1,173 +0,0 @@
-/** R5 / D8: replayable failure premises; advice never authorizes or automatically retries a tool. */
-import type { GuidanceEvent, LogEvent, ToolResultEvent } from "./events.ts";
-import type { ToolDiagnostic } from "./tool-contract.ts";
-import { canonicalValue } from "./continuation.ts";
-import { repairToolInput } from "./tool-input.ts";
-import { failureDiagnostic, scopeFailureGuidance } from "./tool-failure.ts";
-
-/** Reuses the existing three-attempt diagnostic hypothesis, not a measured optimum or a stop threshold. */
-export const RECOVERY_FAILURES = 3;
-type Call = { name: string; input: unknown };
-export interface FailureIdentity {
-  family: string;
-  resource: string;
-  version: string;
-  code: ToolDiagnostic["code"];
-  execution: NonNullable<ToolDiagnostic["execution"]>;
-  effects: NonNullable<ToolDiagnostic["effects"]>;
-  premise: string;
-}
-interface FailureRun {
-  identity: FailureIdentity;
-  key: string;
-  count: number;
-  sources: readonly string[];
-  notified: boolean;
-}
-export interface RecoveryState {
-  calls: ReadonlyMap<string, Call>;
-  versions: ReadonlyMap<string, string>;
-  failures: ReadonlyMap<string, FailureRun>;
-  change: number;
-}
-export function emptyRecoveryState(): RecoveryState {
-  return { calls: new Map(), versions: new Map(), failures: new Map(), change: 0 };
-}
-const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
-const digest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
-const fileTools = ["read", "write", "edit", "grep", "find", "ls"];
-const family = (name: string): string => name === "bash" || name === "exec_command" ? "command"
-  : name === "edit" || name === "write" ? "file_change" : name;
-
-function target(call: Call, identify: (path: string) => string): { family: string; resource: string; input: Record<string, unknown> } {
-  const repaired = repairToolInput(call.name, call.input), input = record(repaired) ? repaired : { value: repaired };
-  const kind = family(call.name);
-  return { family: kind, input, resource: fileTools.includes(call.name) && typeof input["path"] === "string" ? identify(input["path"])
-    : kind === "command" ? identify(typeof input["workdir"] === "string" ? input["workdir"] : ".")
-    : call.name === "write_stdin" ? `session:${String(input["session_id"])}` : call.name };
-}
-
-function groupKey(call: Call, result: ToolResultEvent, identify: (path: string) => string): string {
-  const context = target(call, identify);
-  return canonicalValue([context.family, context.resource, context.family === "command"
-    ? result.effect?.kind === "command" ? result.effect.cmd.trim() : String(context.input["command"] ?? context.input["cmd"] ?? "").trim() : null]);
-}
-
-/** Only recorded versions and structured failures are facts; stderr words never identify an error. */
-export function failureIdentity(call: Call, result: ToolResultEvent, state: RecoveryState,
-  identify: (path: string) => string): FailureIdentity | null {
-  const diagnostic = result.diagnostic;
-  if (result.ok || !diagnostic || diagnostic.execution === undefined || diagnostic.effects === undefined) return null;
-  const context = target(call, identify), data = record(result.data) ? result.data : {};
-  const current = data["sha256"];
-  const effect = result.effect;
-  const known = state.versions.get(context.resource);
-  const version = diagnostic.code === "permission_denied" ? "unknown" : current === null ? "absent" : digest(current) ? current
-    : effect?.kind === "command" && effect.workspace_observed !== false && digest(effect.workspace_sha256) ? effect.workspace_sha256
-    : digest(known) ? known : "unknown";
-  const input = context.input;
-  let premise: unknown;
-  if (diagnostic.code === "version_mismatch") {
-    const precondition = record(data["precondition"]) ? data["precondition"] : {};
-    premise = { expected: precondition["expected"] === null ? "absent"
-      : precondition["expected"] ?? input["expected_sha256"] ?? input["read_handle"] ?? "unknown" };
-  } else if (diagnostic.code === "permission_denied") {
-    // Replacement wording and requested shell timeouts cannot change a denied capability.
-    premise = { operation: context.family === "command" ? effect?.kind === "command" ? effect.cmd.trim()
-      : String(input["command"] ?? input["cmd"] ?? "").trim() : context.family };
-  } else if (context.family === "file_change" && ["not_found", "ambiguous_edit"].includes(diagnostic.code)) {
-    const edits = Array.isArray(input["edits"]) ? input["edits"] : [input];
-    premise = edits.map(edit => record(edit) ? { old_string: edit["old_string"], replace_all: edit["replace_all"] === true } : edit);
-  } else if (context.family === "command") {
-    // Shared launch contract equates bash/exec_command; arbitrary shell strings are not parsed as equivalent.
-    premise = { command: effect?.kind === "command" ? effect.cmd.trim() : String(input["command"] ?? input["cmd"] ?? "").trim(),
-      exit: effect?.kind === "command" ? effect.exit : null,
-      timeout: input["timeout"] ?? null, tty: input["tty"] === true, change: state.change };
-  } else {
-    const normalized = { ...input };
-    if (fileTools.includes(call.name) && typeof normalized["path"] === "string") normalized["path"] = context.resource;
-    premise = normalized;
-  }
-  return { family: context.family, resource: context.resource, version, code: diagnostic.code,
-    execution: diagnostic.execution, effects: diagnostic.effects, premise: canonicalValue(premise) };
-}
-
-function changedPremises(state: RecoveryState, changed: boolean, resource?: string, version?: string): RecoveryState {
-  return { ...state, change: state.change + Number(changed), failures: new Map([...state.failures].filter(([, run]) =>
-    run.identity.code === "permission_denied" || !(changed && run.identity.family === "command" ||
-      resource !== undefined && version !== undefined && run.identity.resource === resource && run.identity.version !== version))) };
-}
-
-/** Incremental disposable projection; folding the original ancestry yields exactly the same state. */
-export function advanceRecovery(state: RecoveryState, events: readonly LogEvent[], identify: (path: string) => string): RecoveryState {
-  let current = state;
-  for (const event of events) {
-    if (event.t === "user") { current = { ...current, failures: new Map() }; continue; }
-    if (event.t === "assistant") {
-      const calls = new Map(current.calls);
-      for (const block of event.blocks) if (block.type === "tool_use") calls.set(block.call_id, { name: block.name, input: block.input });
-      current = { ...current, calls }; continue;
-    }
-    if (event.t === "tool_invocation") {
-      if (event.input !== undefined) current = { ...current, calls: new Map(current.calls).set(event.call_id, { name: event.name, input: event.input }) };
-      continue;
-    }
-    if (event.t === "guidance" && event.reason === "churn") {
-      current = { ...current, failures: new Map([...current.failures].map(([group, run]) =>
-        [group, event.sources.includes(run.sources[0]!) ? { ...run, notified: true } : run])) }; continue;
-    }
-    if (event.t === "workspace_observation" && event.changed) {
-      current = changedPremises(current, true); continue;
-    }
-    if (event.t === "checkpoint" && event.phase === "applied") {
-      for (const [path, change] of Object.entries(event.changes))
-        current = changedPremises(current, change.before?.sha256 !== change.after?.sha256 || change.before?.mode !== change.after?.mode,
-          identify(path), change.after === null ? "absent" : change.after.sha256);
-      continue;
-    }
-    if (event.t !== "tool_result") continue;
-    const call = current.calls.get(event.call_id), calls = new Map(current.calls); calls.delete(event.call_id);
-    current = { ...current, calls };
-    const effect = event.effect;
-    if (effect?.kind === "edit" || effect?.kind === "read") {
-      const resource = identify(effect.path), previous = current.versions.get(resource);
-      const version = effect.kind === "edit" ? effect.sha256_after : effect.sha256;
-      const changed = effect.kind === "edit" ? effect.sha256_before !== effect.sha256_after : digest(previous) && previous !== version;
-      current = changedPremises({ ...current, versions: new Map(current.versions).set(resource, version) }, changed,
-        resource, digest(version) ? version : undefined);
-    }
-    if (!call) continue;
-    const group = groupKey(call, event, identify);
-    if (event.ok) {
-      const failures = new Map(current.failures); failures.delete(group);
-      current = { ...current, failures }; continue;
-    }
-    const identity = failureIdentity(call, event, current, identify);
-    if (!identity) continue;
-    const key = canonicalValue(identity), previous = current.failures.get(group);
-    const run: FailureRun = previous?.key === key ? { ...previous, count: previous.count + 1,
-      sources: [...previous.sources.slice(0, 2), event.id] }
-      : { identity, key, count: 1, sources: [event.id], notified: false };
-    current = { ...current, failures: new Map(current.failures).set(group, run) };
-  }
-  return current;
-}
-
-export function recoveryReview(state: RecoveryState, tools?: readonly string[]): Pick<GuidanceEvent, "reason" | "text" | "sources"> | null {
-  for (const run of state.failures.values()) {
-    if (run.count < RECOVERY_FAILURES || run.notified) continue;
-    const identity = run.identity;
-    // Recompute trusted instructions; never promote arbitrary tool error text to harness instructions.
-    const diagnostic = failureDiagnostic(identity.code, "", { execution: identity.execution, effects: identity.effects });
-    const policy = tools === undefined ? diagnostic : scopeFailureGuidance(diagnostic, tools);
-    return { reason: "churn", sources: run.sources,
-      text: `Harness: ${run.count} attempts share an unchanged failure premise in the recorded facts. ` +
-        `Tool family ${JSON.stringify(identity.family)}; resource label (data) ${JSON.stringify(identity.resource.slice(0, 160))}; ` +
-        `code ${identity.code}; version ${identity.version}; execution ${identity.execution}; effects ${identity.effects}. ` +
-        `${policy.next} ` + (policy.retry === "after_inspection" ? "Inspect actual state for partial effects before any replay. " : "") +
-        "Identify which relevant premise changed before another attempt; changing replacement wording is not a new premise. " +
-        (identity.version === "unknown" ? "The resource version is unknown; this notice does not prove external state is unchanged. " : "") +
-        "This is recovery advice, not a task-failure verdict or authorization to replay. Original result references: " + run.sources.join(", ") + "." };
-  }
-  return null;
-}