@visual-z/xeno 0.2.1 → 0.4.0

package/src/core/action-defaults.ts

@@ -1,306 +1,58 @@
-/** Adapted from Pi keybindings at 02eed88 (MIT). Platform-neutral defaults; overrides share scoped ownership. */
+/**
+ * xeno's key bindings (D20). One flat namespace:
+ *   app.*     global, handled before the focused component
+ *   editor.*  the composer (submit / newline / history / completion)
+ *   list.*    every list dialog (palette, model, login, resume, tree, …)
+ * Shortcuts that only exist inside one dialog are shown in that dialog's
+ * hint row instead of being configurable globals; the palette (Ctrl+P)
+ * reaches every command, so rarely used actions need no chord at all.
+ */
 export const ACTION_DEFAULTS = {
-  "editor.cursorUp": [
-    "up"
-  ],
-  "editor.cursorDown": [
-    "down"
-  ],
-  "tui.editor.historyPrevious": [],
-  "tui.editor.historyNext": [],
-  "editor.cursorLeft": [
-    "left",
-    "ctrl+b"
-  ],
-  "editor.cursorRight": [
-    "right",
-    "ctrl+f"
-  ],
-  "editor.cursorWordLeft": [
-    "alt+left",
-    "ctrl+left",
-    "alt+b"
-  ],
-  "editor.cursorWordRight": [
-    "alt+right",
-    "ctrl+right",
-    "alt+f"
-  ],
-  "editor.cursorLineStart": [
-    "home",
-    "ctrl+home",
-    "ctrl+a"
-  ],
-  "editor.cursorLineEnd": [
-    "end",
-    "ctrl+end",
-    "ctrl+e"
-  ],
-  "tui.editor.jumpForward": [
-    "ctrl+]"
-  ],
-  "tui.editor.jumpBackward": [
-    "ctrl+alt+]"
-  ],
-  "tui.editor.pageUp": [
-    "pageUp",
-    "ctrl+pageUp"
-  ],
-  "tui.editor.pageDown": [
-    "pageDown",
-    "ctrl+pageDown"
-  ],
-  "editor.deleteCharBackward": [
-    "backspace"
-  ],
-  "editor.deleteCharForward": [
-    "delete",
-    "ctrl+d"
-  ],
-  "editor.deleteWordBackward": [
-    "ctrl+w",
-    "alt+backspace"
-  ],
-  "editor.deleteWordForward": [
-    "alt+d",
-    "alt+delete"
-  ],
-  "editor.deleteToLineStart": [
-    "ctrl+u"
-  ],
-  "editor.deleteToLineEnd": [
-    "ctrl+k"
-  ],
-  "editor.yank": [
-    "ctrl+y"
-  ],
-  "tui.editor.yankPop": [
-    "alt+y"
-  ],
-  "editor.undo": [
-    "ctrl+-",
-    "ctrl+_"
-  ],
-  "editor.newLine": [
-    "shift+enter",
-    "ctrl+j"
-  ],
-  "editor.submit": [
-    "enter"
-  ],
-  "editor.complete": [
-    "tab"
-  ],
-  "tui.input.copy": [
-    "ctrl+c"
-  ],
-  "tui.select.up": [
-    "up"
-  ],
-  "tui.select.down": [
-    "down"
-  ],
-  "tui.select.pageUp": [
-    "pageUp"
-  ],
-  "tui.select.pageDown": [
-    "pageDown"
-  ],
-  "tui.select.confirm": [
-    "enter"
-  ],
-  "tui.select.cancel": [
-    "escape",
-    "ctrl+c"
-  ],
-  "tui.altScreen.pageUp": [
-    "pageUp"
-  ],
-  "tui.altScreen.pageDown": [
-    "pageDown"
-  ],
-  "tui.altScreen.halfPageUp": [],
-  "tui.altScreen.halfPageDown": [],
-  "tui.altScreen.lineUp": [],
-  "tui.altScreen.lineDown": [],
-  "tui.altScreen.previousPrompt": [
-    "ctrl+shift+up",
-    "ctrl+up"
-  ],
-  "tui.altScreen.nextPrompt": [
-    "ctrl+shift+down",
-    "ctrl+down"
-  ],
-  "tui.altScreen.search": [
-    "ctrl+shift+f"
-  ],
-  "tui.altScreen.searchNext": [
-    "enter",
-    "ctrl+g"
-  ],
-  "tui.altScreen.searchPrevious": [
-    "shift+enter",
-    "ctrl+shift+g"
-  ],
-  "tui.altScreen.searchClose": [
-    "escape"
-  ],
-  "tui.altScreen.top": [
-    "home"
-  ],
-  "tui.altScreen.bottom": [
-    "end"
-  ],
-  "app.interrupt": [
-    "escape"
-  ],
-  "app.clear": [
-    "ctrl+c"
-  ],
-  "app.exit": [
-    "ctrl+d"
-  ],
-  "app.suspend": [
-    "ctrl+z"
-  ],
-  "app.cycleThinking": [
-    "shift+tab"
-  ],
-  "app.saveDefault": [
-    "ctrl+s"
-  ],
-  "app.cycleModel": [
-    "ctrl+p"
-  ],
-  "app.cycleModelReverse": [
-    "shift+ctrl+p"
-  ],
-  "app.model": [
-    "ctrl+l"
-  ],
-  "app.toggleTools": [
-    "ctrl+o"
-  ],
-  "app.toggleThinking": [
-    "ctrl+t"
-  ],
-  "app.session.toggleNamedFilter": [
-    "ctrl+n"
-  ],
-  "app.externalEditor": [
-    "ctrl+g"
-  ],
-  "app.message.copy": [
-    "ctrl+x"
-  ],
-  "app.message.followUp": [
-    "alt+enter"
-  ],
-  "app.message.dequeue": [
-    "alt+up"
-  ],
-  "app.clipboard.pasteImage": [
-    "ctrl+v"
-  ],
+  "app.palette": ["ctrl+p"],
+  "app.model": ["ctrl+l"],
+  "app.cycleModel": ["alt+m"],
+  "app.cycleModelReverse": ["alt+shift+m"],
+  "app.cycleThinking": ["shift+tab"],
+  "app.toggleTools": ["ctrl+o"],
+  "app.toggleThinking": ["ctrl+t"],
+  "app.toggleSidebar": ["ctrl+b"],
+  "app.interrupt": ["escape"],
+  "app.clear": ["ctrl+c"],
+  "app.exit": ["ctrl+d"],
+  "app.suspend": ["ctrl+z"],
+  "app.externalEditor": ["ctrl+g"],
+  "app.message.copy": ["ctrl+x"],
+  "app.message.followUp": ["alt+enter"],
+  "app.message.dequeue": ["alt+up"],
+  "app.clipboard.pasteImage": ["ctrl+v"],
+  "app.scroll.pageUp": ["pageup"],
+  "app.scroll.pageDown": ["pagedown"],
+  "app.scroll.top": ["ctrl+home"],
+  "app.scroll.bottom": ["ctrl+end"],
   "app.session.new": [],
   "app.session.tree": [],
   "app.session.fork": [],
   "app.session.resume": [],
-  "app.tree.foldOrUp": [
-    "alt+left",
-    "ctrl+left"
-  ],
-  "app.tree.unfoldOrDown": [
-    "alt+right",
-    "ctrl+right"
-  ],
-  "app.tree.editLabel": [
-    "shift+l"
-  ],
-  "app.tree.toggleLabelTimestamp": [
-    "shift+t"
-  ],
-  "app.session.togglePath": [
-    "ctrl+p"
-  ],
-  "app.session.toggleSort": [
-    "ctrl+s"
-  ],
-  "app.session.rename": [
-    "ctrl+r"
-  ],
-  "app.session.delete": [
-    "ctrl+d"
-  ],
-  "app.session.deleteNoninvasive": [
-    "ctrl+backspace"
-  ],
-  "app.models.save": [
-    "ctrl+s"
-  ],
-  "app.models.enableAll": [
-    "ctrl+a"
-  ],
-  "app.models.clearAll": [
-    "ctrl+x"
-  ],
-  "app.models.toggleProvider": [
-    "ctrl+p"
-  ],
-  "app.models.reorderUp": [
-    "alt+up"
-  ],
-  "app.models.reorderDown": [
-    "alt+down"
-  ],
-  "app.tree.filter.default": [
-    "ctrl+d"
-  ],
-  "app.tree.filter.noTools": [
-    "ctrl+t"
-  ],
-  "app.tree.filter.userOnly": [
-    "ctrl+u"
-  ],
-  "app.tree.filter.labeledOnly": [
-    "ctrl+l"
-  ],
-  "app.tree.filter.all": [
-    "ctrl+a"
-  ],
-  "app.tree.filter.cycleForward": [
-    "ctrl+o"
-  ],
-  "app.tree.filter.cycleBackward": [
-    "shift+ctrl+o"
-  ]
-} as const;
-export const ACTION_ALIASES: Readonly<Record<string,string>> = {
-  "tui.input.submit": "editor.submit",
-  "tui.input.newLine": "editor.newLine",
-  "tui.input.tab": "editor.complete",
+  "app.saveDefault": ["ctrl+s"],
+  "editor.submit": ["enter"],
+  "editor.newLine": ["shift+enter", "ctrl+j"],
+  "editor.complete": ["tab"],
+  "editor.historyPrevious": ["up"],
+  "editor.historyNext": ["down"],
+  "list.up": ["up", "ctrl+k"],
+  "list.down": ["down", "ctrl+j"],
+  "list.pageUp": ["pageup"],
+  "list.pageDown": ["pagedown"],
+  "list.confirm": ["enter"],
+  "list.cancel": ["escape"],
+  "list.toggle": ["space"],
+} as const satisfies Record<string, readonly string[]>;
+
+/** Renamed ids still read from a user's keybindings file. */
+export const ACTION_ALIASES: Readonly<Record<string, string>> = {
   "app.model.select": "app.model",
-  "app.model.cycleForward": "app.cycleModel",
-  "app.model.cycleBackward": "app.cycleModelReverse",
   "app.thinking.cycle": "app.cycleThinking",
   "app.thinking.toggle": "app.toggleThinking",
   "app.tools.expand": "app.toggleTools",
   "app.editor.external": "app.externalEditor",
-  "app.thinking.save": "app.saveDefault",
-  "tui.editor.cursorUp": "editor.cursorUp",
-  "tui.editor.cursorDown": "editor.cursorDown",
-  "tui.editor.cursorLeft": "editor.cursorLeft",
-  "tui.editor.cursorRight": "editor.cursorRight",
-  "tui.editor.cursorWordLeft": "editor.cursorWordLeft",
-  "tui.editor.cursorWordRight": "editor.cursorWordRight",
-  "tui.editor.cursorLineStart": "editor.cursorLineStart",
-  "tui.editor.cursorLineEnd": "editor.cursorLineEnd",
-  "tui.editor.deleteCharBackward": "editor.deleteCharBackward",
-  "tui.editor.deleteCharForward": "editor.deleteCharForward",
-  "tui.editor.deleteWordBackward": "editor.deleteWordBackward",
-  "tui.editor.deleteWordForward": "editor.deleteWordForward",
-  "tui.editor.deleteToLineStart": "editor.deleteToLineStart",
-  "tui.editor.deleteToLineEnd": "editor.deleteToLineEnd",
-  "tui.editor.yank": "editor.yank",
-  "tui.editor.undo": "editor.undo"
 };

package/src/core/benchmark.ts

@@ -126,7 +126,7 @@ export function benchmarkPrompt(item: BenchmarkItem, chunks: number): string {
     'Format your final response as follows: "The correct answer is (insert answer here)".';
 }
 
-export interface BenchmarkPrice { input: number; output: number; cacheRead: number }
+export interface BenchmarkPrice { input: number; output: number; cacheRead: number; cacheWrite?: number }
 export interface BenchmarkUsage { input_tokens: number; output_tokens: number; cache_read_input_tokens: number; cache_creation_input_tokens: number }
 
 /** A conservative allowance, not a tokenizer: wire bytes plus framing, at uncached peak rates. */
@@ -139,7 +139,7 @@ export function measuredCharge(usage: BenchmarkUsage, price: BenchmarkPrice): nu
   const counts = [usage.input_tokens, usage.output_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens];
   if (counts.some((value) => !Number.isSafeInteger(value) || value < 0) ||
       usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens === 0 || usage.output_tokens === 0) return null;
-  return ((usage.input_tokens + usage.cache_creation_input_tokens) * price.input +
+  return (usage.input_tokens * price.input + usage.cache_creation_input_tokens * (price.cacheWrite ?? price.input) +
     usage.cache_read_input_tokens * price.cacheRead + usage.output_tokens * price.output) / 1_000_000;
 }
 

package/src/core/branch-receipt.ts

@@ -0,0 +1,24 @@
+/** O.9: references to facts, never a child's self-assessed completion. */
+import type { LogEvent, NodeRef } from "./events.ts";
+import type { Handoff } from "./handoff.ts";
+import type { ExecutionOutcome } from "./outcome.ts";
+
+export function deriveBranchReceipt(input: {
+  source: NodeRef; outcome: ExecutionOutcome; handoff: Handoff;
+  nodes: readonly { node: number; events: readonly LogEvent[] }[];
+}) {
+  const entries = input.nodes.flatMap(part => part.events.map(event => ({ node: part.node, event })));
+  const commands = entries.flatMap(({ node, event }) => event.t === "tool_result" && event.effect?.kind === "command"
+    ? [{ node, event: event.id, exit: event.effect.exit }] : []);
+  const changes = entries.flatMap(({ node, event }) => event.t === "tool_result" && event.effect?.kind === "edit"
+    ? [{ node, event: event.id, path: event.effect.path }] : []);
+  const observations = entries.flatMap(({ node, event }) => event.t === "tool_result" ? [{ node, event: event.id }] : []);
+  const unfinished = (input.handoff.state.work_items ?? []).filter(item => item.status === "active" || item.status === "blocked")
+    .map(item => ({ work_id: item.id, status: item.status, next_action: item.next_action ?? null }));
+  return { version: 1, source: input.source, execution: input.outcome,
+    verification: commands.length === 0 ? "not_recorded" : commands.some(command => command.exit === 0) ? "command_succeeded" : "commands_failed",
+    task_acceptance: "not_assessed", commands, changes, observations, unfinished,
+    ...(input.handoff.processes?.length ? { processes: input.handoff.processes } : {}),
+    unresolved_branches: input.handoff.branches.filter(b => b.resolution === null).map(b => b.node),
+  };
+}

package/src/core/checkpoints.ts

@@ -0,0 +1,64 @@
+/** P.3: recovery describes observed file transitions, never a complete disk image. */
+export type FileVersion = { sha256: string; mode: number } | null;
+export type FileChange = { before: FileVersion; after: FileVersion };
+export type FileChanges = Record<string, FileChange>;
+export interface CheckpointEvent {
+  t: "checkpoint";
+  id: string;
+  at: string;
+  operation: string;
+  source: "edit" | "git" | "restore";
+  phase: "prepared" | "applied" | "unavailable";
+  changes: FileChanges;
+  tree?: string;
+  reason?: string;
+}
+export interface WorkspaceObservationEvent {
+  t: "workspace_observation";
+  id: string;
+  at: string;
+  /** P.3: this scope excludes ignored/build output and is not a backup. */
+  fingerprint?: string;
+  scope: "source-v1";
+  changed: boolean;
+  reason?: string;
+}
+
+export function sameVersion(a: FileVersion, b: FileVersion): boolean {
+  return a === null || b === null ? a === b : a.sha256 === b.sha256 && a.mode === b.mode;
+}
+export function changedPaths(changes: FileChanges): string[] {
+  return Object.keys(changes).filter(path => !sameVersion(changes[path]!.before, changes[path]!.after)).sort();
+}
+
+/** Undo the abandoned suffix then replay the selected suffix, touching only their paths. */
+export function planFileTransition(from: readonly CheckpointEvent[], to: readonly CheckpointEvent[]): FileChanges {
+  const left = from.filter(event => event.phase === "applied");
+  const right = to.filter(event => event.phase === "applied");
+  let common = 0;
+  while (common < left.length && common < right.length && left[common]!.id === right[common]!.id) common++;
+  const changes: FileChanges = Object.create(null) as FileChanges;
+  const apply = (path: string, before: FileVersion, after: FileVersion) => {
+    const existing = changes[path];
+    if (existing && !sameVersion(existing.after, before)) throw new Error(`discontinuous file history: ${path}; inspect intervening external edits`);
+    changes[path] = { before: existing ? existing.before : before, after };
+  };
+  for (const event of left.slice(common).reverse()) for (const path of changedPaths(event.changes)) {
+    const change = event.changes[path]!;
+    apply(path, change.after, change.before);
+  }
+  for (const event of right.slice(common)) for (const path of changedPaths(event.changes)) {
+    const change = event.changes[path]!;
+    apply(path, change.before, change.after);
+  }
+  return Object.fromEntries(changedPaths(changes).map(path => [path, changes[path]!])) as FileChanges;
+}
+
+export function validFileChanges(value: unknown): value is FileChanges {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const version = (v: unknown): boolean => v === null || typeof v === "object" && !Array.isArray(v) &&
+    typeof (v as Record<string, unknown>)["sha256"] === "string" && /^[a-f0-9]{64}$/.test(String((v as Record<string, unknown>)["sha256"])) &&
+    Number.isInteger((v as Record<string, unknown>)["mode"]) && Number((v as Record<string, unknown>)["mode"]) >= 0 && Number((v as Record<string, unknown>)["mode"]) <= 0o777;
+  return Object.entries(value).every(([path, change]: [string, unknown]) => path.length > 0 && typeof change === "object" && change !== null &&
+    version((change as Record<string, unknown>)["before"]) && version((change as Record<string, unknown>)["after"]));
+}

package/src/core/churn.ts

@@ -34,6 +34,8 @@ export function churnReview(events: readonly LogEvent[]): Pick<GuidanceEvent, "r
     if (event.t !== "tool_result" || event.effect === undefined) continue;
     const effect = event.effect;
     if (effect.kind === "command") {
+      // R5 handles structured failures with version/change premises; keep this path for legacy logs.
+      if (event.diagnostic?.execution !== undefined) continue;
       const key = effect.cmd.trim();
       if (effect.exit === 0) { failures.delete(key); continue; }
       const seen = { count: (failures.get(key)?.count ?? 0) + 1, last: event.id };

package/src/core/command-artifacts.ts

@@ -0,0 +1,94 @@
+/** R8 / D8 / D11: an explicit observation scope is not a claim of build causality. */
+import type { ArtifactRef } from "./events.ts";
+import { isObservationArtifact } from "./observation-view.ts";
+
+// Assumed observation budgets keep a model-supplied plan bounded before execution.
+export const MAX_COMMAND_ARTIFACTS = 16;
+export const MAX_ARTIFACT_PLAN_BYTES = 16 * 1024;
+export const MAX_COMMAND_ARTIFACT_BYTES = 512 * 1024 * 1024;
+export const COMMAND_ARTIFACT_SCOPE = "source-v1-minus-artifacts";
+export type CommandArtifactPlan = { paths: string[]; output_roots: string[] };
+export type ArtifactFileIdentity = { device: string; inode: string; mtime_ns: string; ctime_ns: string; mode: number };
+export type ArtifactFile = { state: "observed"; sha256: string; bytes: number; identity: ArtifactFileIdentity } |
+  { state: "missing" | "unsafe" | "changed" | "unknown"; reason: string };
+export type ArtifactChange = "created" | "modified" | "unchanged" | "unknown";
+export type CommandArtifactOutput = { path: string; before: ArtifactFile; after: ArtifactFile; change: ArtifactChange };
+export type CommandArtifactReceipt = {
+  kind: "command_artifacts"; version: 1;
+  state: "pending" | "observed" | "changed" | "unknown";
+  plan: CommandArtifactPlan;
+  source: { host: string; workspace: string; cwd: string; runtime: string };
+  command: string; exit: number | null;
+  started_at: string; observed_at: string | null;
+  inputs: { scope: typeof COMMAND_ARTIFACT_SCOPE; exclusions: string[]; before: string | null; after: string | null };
+  outputs: CommandArtifactOutput[];
+  reasons: string[];
+  manifest?: ArtifactRef;
+};
+
+const object = (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 covers = (root: string, path: string) => root === path || path.startsWith(root + "/");
+export function validArtifactPath(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && new TextEncoder().encode(value).length <= 4096 &&
+    !/[\x00-\x1f\x7f\\:]/.test(value) && value.split("/").every(part => part !== "" && part !== "." && part !== ".." && part !== ".git" && part !== ".xeno");
+}
+export function parseCommandArtifactPlan(value: unknown): CommandArtifactPlan {
+  if (!object(value) || Object.keys(value).some(key => !["paths", "output_roots"].includes(key))) throw new Error("artifacts needs paths and optional output_roots only");
+  const paths = value["paths"], roots = value["output_roots"] ?? paths;
+  for (const list of [paths, roots]) {
+    if (!Array.isArray(list) || list.length < 1 || list.length > MAX_COMMAND_ARTIFACTS || !list.every(validArtifactPath) || new Set(list).size !== list.length)
+      throw new Error("artifacts needs 1..16 unique workspace-relative file paths; no traversal or protected paths");
+  }
+  const plan = { paths: [...paths as string[]].sort(), output_roots: [...roots as string[]].sort() };
+  if (new TextEncoder().encode(JSON.stringify(plan)).length > MAX_ARTIFACT_PLAN_BYTES) throw new Error("artifact plan exceeds 16 KiB");
+  if (plan.paths.some((path, i) => plan.paths.some((other, j) => i !== j && covers(path, other)))) throw new Error("artifact file paths cannot contain one another");
+  if (plan.output_roots.some((root, i) => !plan.paths.some(path => covers(root, path)) || plan.output_roots.some((other, j) => i !== j && covers(root, other))) ||
+    plan.paths.some(path => !plan.output_roots.some(root => covers(root, path)))) throw new Error("output_roots must be nonoverlapping and cover exactly the requested artifact paths");
+  return plan;
+}
+export function artifactChange(before: ArtifactFile, after: ArtifactFile): ArtifactChange {
+  if (after.state !== "observed") return "unknown";
+  if (before.state === "missing") return "created";
+  if (before.state !== "observed") return "unknown";
+  return before.sha256 === after.sha256 && before.bytes === after.bytes && sameArtifactIdentity(before.identity, after.identity) ? "unchanged" : "modified";
+}
+export function sameArtifactIdentity(a: ArtifactFileIdentity, b: ArtifactFileIdentity): boolean {
+  return a.device === b.device && a.inode === b.inode && a.mtime_ns === b.mtime_ns && a.ctime_ns === b.ctime_ns && a.mode === b.mode;
+}
+export function commandArtifactState(receipt: Pick<CommandArtifactReceipt, "exit" | "inputs" | "outputs" | "reasons">): CommandArtifactReceipt["state"] {
+  if (receipt.exit === null) return "pending";
+  if (receipt.inputs.before !== null && receipt.inputs.after !== null && receipt.inputs.before !== receipt.inputs.after ||
+    receipt.outputs.some(output => output.after.state === "changed")) return "changed";
+  if (receipt.exit !== 0 || receipt.reasons.length > 0 || receipt.inputs.before === null || receipt.inputs.after === null ||
+    receipt.outputs.length === 0 || receipt.outputs.some(output => output.after.state !== "observed")) return "unknown";
+  return "observed";
+}
+export function isArtifactFile(value: unknown): value is ArtifactFile {
+  if (!object(value)) return false;
+  if (value["state"] !== "observed") return ["missing", "unsafe", "changed", "unknown"].includes(String(value["state"])) && typeof value["reason"] === "string" && value["reason"].length > 0;
+  const id = value["identity"];
+  return digest(value["sha256"]) && Number.isSafeInteger(value["bytes"]) && Number(value["bytes"]) >= 0 && Number(value["bytes"]) <= MAX_COMMAND_ARTIFACT_BYTES &&
+    object(id) && ["device", "inode", "mtime_ns", "ctime_ns"].every(key => typeof id[key] === "string" && /^-?\d+$/.test(id[key])) &&
+    Number.isInteger(id["mode"]) && Number(id["mode"]) >= 0 && Number(id["mode"]) <= 0o777;
+}
+export function isCommandArtifactReceipt(value: unknown): value is CommandArtifactReceipt {
+  if (!object(value) || value["kind"] !== "command_artifacts" || value["version"] !== 1 || typeof value["command"] !== "string" || !value["command"].trim() ||
+    typeof value["started_at"] !== "string" || (value["exit"] !== null && !Number.isInteger(value["exit"]))) return false;
+  let plan: CommandArtifactPlan;
+  try { plan = parseCommandArtifactPlan(value["plan"]); } catch { return false; }
+  if (!object(value["plan"]) || JSON.stringify(value["plan"]["paths"]) !== JSON.stringify(plan.paths) ||
+    JSON.stringify(value["plan"]["output_roots"]) !== JSON.stringify(plan.output_roots)) return false;
+  const source = value["source"], inputs = value["inputs"], outputs = value["outputs"], reasons = value["reasons"];
+  if (!object(source) || !["host", "workspace", "cwd", "runtime"].every(key => typeof source[key] === "string" && source[key] !== "") ||
+    !object(inputs) || inputs["scope"] !== COMMAND_ARTIFACT_SCOPE || !Array.isArray(inputs["exclusions"]) ||
+    !inputs["exclusions"].every(path => typeof path === "string" && path.length > 0) || new Set(inputs["exclusions"]).size !== inputs["exclusions"].length ||
+    !plan.output_roots.every(root => (inputs["exclusions"] as unknown[]).includes(root)) ||
+    !["before", "after"].every(key => inputs[key] === null || digest(inputs[key])) || !Array.isArray(outputs) ||
+    !Array.isArray(reasons) || !reasons.every(reason => typeof reason === "string" && reason.length > 0)) return false;
+  if (value["exit"] === null) return value["state"] === "pending" && value["observed_at"] === null && inputs["after"] === null && outputs.length === 0 && value["manifest"] === undefined;
+  if (typeof value["observed_at"] !== "string" || !value["observed_at"] || outputs.length !== plan.paths.length || !outputs.every((item, index) =>
+    object(item) && item["path"] === plan.paths[index] && isArtifactFile(item["before"]) && isArtifactFile(item["after"]) && item["change"] === artifactChange(item["before"], item["after"]))) return false;
+  if (value["manifest"] !== undefined && !isObservationArtifact(value["manifest"])) return false;
+  return value["state"] === commandArtifactState(value as CommandArtifactReceipt) && (value["state"] !== "observed" || isObservationArtifact(value["manifest"]));
+}

package/src/core/command-contract.ts

@@ -0,0 +1,35 @@
+/** R1 / D11: all command entrances agree on invocation and observed termination. */
+import { executionOutcome } from "./outcome.ts";
+import type { ToolDiagnostic } from "./tool-contract.ts";
+
+/** Operational grace, not a measured optimum: ignored SIGTERM cannot defeat cancellation. */
+export const COMMAND_TERMINATION_GRACE_MS = 200;
+
+/** A fresh login Bash per command; interactive stdin does not change shell success semantics. */
+export function commandArgv(command: string): string[] {
+  return ["bash", "-o", "pipefail", "-lc", command];
+}
+
+/** Preserve inherited values except documented noninteractive defaults; never mutate the host. */
+export function commandEnvironment(base: Readonly<Record<string, string | undefined>>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(base)) if (value !== undefined) env[key] = value;
+  Object.assign(env, {
+    TERM: "dumb", PAGER: "cat", GIT_PAGER: "cat", NO_COLOR: "1",
+    GIT_TERMINAL_PROMPT: "0", DEBIAN_FRONTEND: "noninteractive",
+  });
+  if (env["LANG"] === undefined || env["LANG"] === "") env["LANG"] = "C.UTF-8";
+  return env;
+}
+
+/** Model seconds and host milliseconds meet once; a yield is never a command deadline. */
+export function commandTimeout(requestedSeconds: number | undefined, defaultMs: number, maximumMs = defaultMs): number {
+  return Math.min(requestedSeconds === undefined ? defaultMs : requestedSeconds * 1000, maximumMs);
+}
+
+/** A trap can exit zero after cancellation: successful exit alone does not erase the stop. */
+export function commandCompletion(exit: number, stopped?: "cancelled" | "timeout", cleanup?: ToolDiagnostic) {
+  return { ok: stopped === undefined && exit === 0 && cleanup === undefined,
+    outcome: executionOutcome(stopped ?? (exit === 0 && cleanup === undefined ? "tool_completed" : "tool_failed")),
+    ...(cleanup ? { warnings: [cleanup] } : {}) };
+}

package/src/core/completion-action.ts

@@ -0,0 +1,20 @@
+import { assertNever } from "./exhaustive.ts";
+
+/** D19: confirmation follows the selected completion, never the unfinished draft. */
+export function completionAction(kind: "command" | "argument" | "path", key: "enter" | "tab", requiresArgument: boolean): "insert" | "submit" {
+  if (key === "tab") return "insert";
+  switch (kind) {
+    case "command": return requiresArgument ? "insert" : "submit";
+    case "argument": return "submit";
+    case "path": return "insert";
+    default: return assertNever(kind, "completion kind");
+  }
+}
+
+/** Match the parser's exact identity before discoverable prefixes and substrings. */
+export function commandCompletionRank(name: string, query: string): number {
+  const canonical = name.toLowerCase(), typed = query.toLowerCase();
+  if (canonical === typed) return 0;
+  if (canonical.startsWith(typed)) return 1;
+  return typed.length > 1 && canonical.includes(typed) ? 2 : Number.POSITIVE_INFINITY;
+}