@visual-z/xeno 0.8.2 → 0.8.4

package/src/core/external-effects.ts

@@ -0,0 +1,488 @@
+/**
+ * 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/handoff.ts

@@ -152,8 +152,22 @@ export type UserTurnRecord = {
    * common case, and deleting the turn would rewrite history.
    */
   abandoned?: true;
+  /**
+   * Working set v3 only: the original user event, present exactly when the turn
+   * carried images, so `history(event=ID)` can reattach them.
+   */
+  event?: EventId;
+  /**
+   * Working set v3 only: references to the turn's attached images (D8: digest
+   * and identity, never bytes). Absent from the full derived state, so legacy
+   * projections and frozen replay are unchanged.
+   */
+  images?: readonly UserTurnImage[];
 };
 
+/** Enough for the model to know an image exists and which one; bytes stay in the blob store. */
+export type UserTurnImage = { sha256: Sha256; name: string; width: number; height: number };
+
 export type Handoff = {
   handoff_version: typeof HANDOFF_VERSION | 2;
   working_set?: WorkingSet;
@@ -244,7 +258,8 @@ const ORDER: Record<string, readonly string[]> = {
     "continuation_valid", "budget",
   ],
   predecessor: ["node", "log_ref", "sha256"],
-  user_turns: ["at", "text", "abandoned"],
+  user_turns: ["at", "text", "abandoned", "event", "images"],
+  "user_turns.images": ["sha256", "name", "width", "height"],
   user_turns_truncated: ["dropped", "recover_from"],
   state: ["completed", "unverified_claims", "in_flight", "blocked", "last_activity", "work_items"],
   "state.completed": ["work_id", "what", "evidence", "evidence_superseded"],
@@ -301,6 +316,7 @@ export type Violation = {
     | "INVALID_WORK_STATE"
     | "INVALID_EVIDENCE_LINK"
     | "INVALID_WORKING_SET"
+    | "INVALID_USER_TURN"
     | "INVALID_ACCEPTANCE"
     | "INVALID_SKILL_SOURCE"
     | "INVALID_PROCESS_STATE"
@@ -349,11 +365,11 @@ export function validateHandoff(h: Handoff): Violation[] {
   }
   if (h.working_set) {
     const view = h.working_set;
-    if (![1, 2].includes(view.version) || view.source.node !== h.predecessor?.node || view.source.sha256 !== h.predecessor?.sha256 ||
+    if (![1, 2, 3].includes(view.version) || view.source.node !== h.predecessor?.node || view.source.sha256 !== h.predecessor?.sha256 ||
         !Number.isSafeInteger(view.omitted.work) || view.omitted.work < 0 || !Number.isSafeInteger(view.omitted.references) || view.omitted.references < 0 ||
         new Set(view.work.map(item => item.id)).size !== view.work.length || view.work.some(item => !["active", "blocked"].includes(item.status)) ||
         view.references.some(reference => !reference.event) ||
-        view.version === 2 && (!view.recovery_sections || RECOVERY_SECTIONS.some(section => {
+        view.version >= 2 && (!view.recovery_sections || RECOVERY_SECTIONS.some(section => {
           const range = view.recovery_sections![section], references = view.references.filter(ref => ref.kind === RECOVERY_KINDS[section]);
           return !range || !Number.isSafeInteger(range.total) || !Number.isSafeInteger(range.omitted) || range.omitted < 0 || range.omitted > range.total ||
             range.total - range.omitted !== references.length || new Set(references.map(ref => ref.event)).size !== references.length ||
@@ -363,6 +379,11 @@ export function validateHandoff(h: Handoff): Violation[] {
       v.push({ code: "INVALID_WORKING_SET", detail: "working set must reference its source and explicit active state" });
     }
   }
+  // D8: an image reference must name its blob and the original event that reattaches it.
+  if (h.user_turns.some(turn => turn.event !== undefined && !turn.images?.length ||
+      turn.images !== undefined && (!turn.event || turn.images.length === 0 || turn.images.some(image => !/^[a-f0-9]{64}$/.test(image.sha256))))) {
+    v.push({ code: "INVALID_USER_TURN", detail: "user turn images need their original event and blob digests" });
+  }
   if (h.handoff_version === 2) {
     const history = h.history;
     if (!history || !h.predecessor || history.source.node !== h.predecessor.node ||

package/src/core/history-query.ts

@@ -72,7 +72,7 @@ export function historyEntries(nodes: readonly { node: number; events: readonly
         ...(e.observation.manifest ? { artifact: e.observation.manifest.sha256 } : {}) });
     } else if (e.t === "process_exit") {
       entries.push({ node, event: e.id, kind: e.t, text: canonicalValue(e), artifact: e.output.sha256 });
-    } else if (["work_owner", "work_dependencies", "skill_loaded", "acceptance_contract", "acceptance_decision", "user", "next_action", "decision", "pitfall", "blocked", "question", "claim", "work_status", "evidence_link"].includes(e.t)) {
+    } else if (["work_owner", "work_dependencies", "approval", "skill_loaded", "acceptance_contract", "acceptance_decision", "user", "next_action", "decision", "pitfall", "blocked", "question", "claim", "work_status", "evidence_link"].includes(e.t)) {
       entries.push({ node, event: e.id, kind: e.t, text: e.t === "user" ? e.text : canonicalValue(e),
         ...("work_id" in e && e.work_id ? { work_ids: [e.work_id] } : {}),
         ...(e.t === "evidence_link" ? { work_ids: [e.work], ...(e.resource ? { resources: [resourceKey(e.resource)] } : {}) } : {}) });