@visual-z/xeno 0.1.0

package/src/core/history.ts

@@ -0,0 +1,100 @@
+/** D20: bounded carried state, with deterministic pages rebuilt from the log. */
+import { emitHandoff, type Handoff } from "./handoff.ts";
+import { estimateTokens } from "./tokens.ts";
+
+// A carried handoff must leave room for another segment's work. This budget is
+// the existing 5k work floor, not a new segment threshold or an accuracy claim.
+export const DEFAULT_HANDOFF_TOKENS = 5_000;
+export const HISTORY_SECTIONS = [
+  "user_turns", "state.completed", "state.unverified_claims", "state.in_flight",
+  "state.blocked", "decisions", "pitfalls", "file_anchors", "verification",
+  "branches", "open_questions", "progress_evidence",
+  "state.work_items",
+  "evidence_links",
+] as const;
+export type HistorySection = (typeof HISTORY_SECTIONS)[number];
+
+export function historyItems(h: Handoff, section: HistorySection): readonly unknown[] {
+  switch (section) {
+    case "state.completed": return h.state.completed;
+    case "state.unverified_claims": return h.state.unverified_claims;
+    case "state.in_flight": return h.state.in_flight;
+    case "state.blocked": return h.state.blocked;
+    case "state.work_items": return h.state.work_items ?? [];
+    case "evidence_links": return h.evidence_links ?? [];
+    case "progress_evidence": return h.progress_evidence ?? [];
+    default: return h[section];
+  }
+}
+
+function suffixes(h: Handoff, offsets: Record<HistorySection, number>): Handoff {
+  return {
+    ...h,
+    user_turns: h.user_turns.slice(offsets.user_turns),
+    state: {
+      ...h.state,
+      completed: h.state.completed.slice(offsets["state.completed"]),
+      unverified_claims: h.state.unverified_claims.slice(offsets["state.unverified_claims"]),
+      in_flight: h.state.in_flight.slice(offsets["state.in_flight"]),
+      blocked: h.state.blocked.slice(offsets["state.blocked"]),
+      ...(h.state.work_items !== undefined ? { work_items: h.state.work_items.slice(offsets["state.work_items"] ?? 0) } : {}),
+    },
+    decisions: h.decisions.slice(offsets.decisions),
+    pitfalls: h.pitfalls.slice(offsets.pitfalls),
+    file_anchors: h.file_anchors.slice(offsets.file_anchors),
+    verification: h.verification.slice(offsets.verification),
+    branches: h.branches.slice(offsets.branches),
+    open_questions: h.open_questions.slice(offsets.open_questions),
+    progress_evidence: (h.progress_evidence ?? []).slice(offsets.progress_evidence),
+    ...(h.evidence_links !== undefined ? { evidence_links: h.evidence_links.slice(offsets.evidence_links ?? 0) } : {}),
+  };
+}
+
+export function boundHandoff(full: Handoff, budget = DEFAULT_HANDOFF_TOKENS): Handoff {
+  if (!Number.isFinite(budget) || budget <= 0) throw new RangeError("handoff budget must be positive");
+  const size = (h: Handoff): number => estimateTokens.count([], emitHandoff(h));
+  if (size(full) <= budget) return full;
+  if (full.predecessor === null) throw new Error("history requires an immutable source");
+  // An absent new section must not change legacy projections or frozen replay.
+  const sections = HISTORY_SECTIONS.filter(section => (section !== "state.work_items" || full.state.work_items !== undefined) &&
+    (section !== "evidence_links" || full.evidence_links !== undefined));
+  const offsets = Object.fromEntries(sections.map((s) => [s, historyItems(full, s).length])) as Record<HistorySection, number>;
+  const build = (): Handoff => ({
+    ...suffixes(full, offsets),
+    handoff_version: 2,
+    history: {
+      source: full.predecessor!,
+      sections: Object.fromEntries(sections.map((s) => [s, {
+        total: historyItems(full, s).length, offset: offsets[s],
+      }])),
+    },
+  });
+  let carried = build();
+  // The objective stays verbatim (D2). An oversized objective is an explicit
+  // input problem; repeatedly cutting it would create an infinite cut loop.
+  if (size(carried) > budget) throw new RangeError("handoff scalar fields exceed budget; shorten the objective or frozen input");
+  const active = new Set<HistorySection>(sections);
+  // Round-robin suffix growth prevents one long section starving every other
+  // category. Each retained range is contiguous and independently pageable.
+  while (active.size > 0) {
+    for (const section of active) {
+      if (offsets[section] === 0) { active.delete(section); continue; }
+      offsets[section]--;
+      const candidate = build();
+      if (size(candidate) <= budget) carried = candidate;
+      else { offsets[section]++; active.delete(section); }
+    }
+  }
+  return carried;
+}
+
+export function historyPage(full: Handoff, section: HistorySection, offset: number, limit: number): {
+  total: number; offset: number; next: number | null; items: readonly unknown[];
+} {
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1) {
+    throw new RangeError("history offset and limit must be nonnegative/positive integers");
+  }
+  const items = historyItems(full, section);
+  const end = Math.min(items.length, offset + limit);
+  return { total: items.length, offset, next: end < items.length ? end : null, items: items.slice(offset, end) };
+}

package/src/core/json-event.ts

@@ -0,0 +1,135 @@
+/**
+ * LoopEvent → one JSON object for `--mode json`.
+ *
+ * Declared here, not imported from runtime, so core stays below the loop
+ * (D13: core does not import a layer above it). The kind union is kept in
+ * lockstep with LoopEvent; a new kind makes the call site in apps fail to
+ * type-check until this switch grows a case.
+ *
+ * Deltas return null. A pipe cannot retract a half-turn, and a retry would
+ * then emit the same prefix twice — the same reason `-p` waits for the
+ * complete block. The caller still sees `assistant_text` / `thinking` once
+ * the turn has a final block.
+ */
+
+import { assertNever } from "./exhaustive.ts";
+import type { ExecutionOutcome } from "./outcome.ts";
+
+export type JsonLoopKind =
+  | "turn_start"
+  | "assistant_text"
+  | "thinking"
+  | "text_delta"
+  | "thinking_delta"
+  | "discard"
+  | "tool_call"
+  | "tool_result"
+  | "usage"
+  | "cut"
+  | "stop_and_ask"
+  | "branch_start"
+  | "branch_done"
+  | "snapshot_failed"
+  | "undeclared_change"
+  | "done";
+
+/**
+ * Structural match for runtime LoopEvent. Copied rather than imported so
+ * this module cannot grow an upward dependency.
+ */
+export interface JsonLoopEvent {
+  kind: JsonLoopKind;
+  text?: string;
+  tool?: { name: string; input: unknown };
+  ok?: boolean;
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+    node: number;
+    ms: number;
+  };
+  prefix?: string;
+  node?: number;
+  reason?: string;
+  at?: number;
+  outcome?: ExecutionOutcome;
+}
+
+/**
+ * `null` means an internal event that must not go on the wire.
+ * `at` is supplied by the caller (ISO from the session clock) so this
+ * function stays free of Date.
+ */
+export function toJsonEvent(e: JsonLoopEvent, at: string): Record<string, unknown> | null {
+  switch (e.kind) {
+    case "text_delta":
+    case "thinking_delta":
+    case "discard":
+      return null;
+    case "assistant_text":
+      return { type: "assistant_text", text: e.text ?? "", at };
+    case "thinking":
+      return { type: "thinking", text: e.text ?? "", at };
+    case "tool_call":
+      return { type: "tool_call", tool: e.tool ?? { name: "", input: {} }, at };
+    case "tool_result":
+      return { type: "tool_result", text: e.text ?? "", ok: e.ok !== false,
+        ...(e.outcome ? { outcome: e.outcome } : {}), at };
+    case "usage":
+      return {
+        type: "usage",
+        ...(e.usage !== undefined
+          ? {
+              usage: {
+                input_tokens: e.usage.input_tokens,
+                output_tokens: e.usage.output_tokens,
+                cache_creation_input_tokens: e.usage.cache_creation_input_tokens,
+                cache_read_input_tokens: e.usage.cache_read_input_tokens,
+                node: e.usage.node,
+                ms: e.usage.ms,
+              },
+            }
+          : {}),
+        ...(e.prefix !== undefined ? { prefix: e.prefix } : {}),
+        ok: e.ok !== false,
+        at,
+      };
+    case "turn_start":
+      return { type: "turn_start", ...(e.node !== undefined ? { node: e.node } : {}), at };
+    case "cut":
+      return {
+        type: "cut",
+        ...(e.node !== undefined ? { node: e.node } : {}),
+        ...(e.reason !== undefined ? { reason: e.reason } : {}),
+        at,
+      };
+    case "stop_and_ask":
+      return { type: "stop_and_ask", ...(e.reason !== undefined ? { reason: e.reason } : {}), at };
+    case "done":
+      return { type: "done", ...(e.reason !== undefined ? { reason: e.reason } : {}),
+        ...(e.outcome ? { outcome: e.outcome } : {}), at };
+    case "branch_start":
+      return {
+        type: "branch_start",
+        ...(e.node !== undefined ? { node: e.node } : {}),
+        ...(e.reason !== undefined ? { reason: e.reason } : {}),
+        at,
+      };
+    case "branch_done":
+      return {
+        type: "branch_done",
+        ...(e.outcome ? { outcome: e.outcome } : {}),
+        ...(e.node !== undefined ? { node: e.node } : {}),
+        ...(e.text !== undefined ? { text: e.text } : {}),
+        at,
+      };
+    case "snapshot_failed":
+      return { type: "snapshot_failed", ...(e.reason !== undefined ? { reason: e.reason } : {}), at };
+    case "undeclared_change":
+      return { type: "undeclared_change", ...(e.reason !== undefined ? { reason: e.reason } : {}), at };
+    default:
+      return assertNever(e.kind, "toJsonEvent");
+  }
+}

package/src/core/json-pointer.ts

@@ -0,0 +1,46 @@
+/** Parsed-JSON traversal and recoverable diagnostics (research N.5, RFC 6901). */
+// Assumed diagnostic budget, not a data limit: show only complete short keys.
+// Twelve forty-unit keys keep even JSON-escaped control characters below 4 KiB.
+const HINT_KEYS = 12;
+const HINT_KEY_UNITS = 40;
+
+export function validateJsonPointer(pointer: string): void {
+  if ((pointer !== "" && !pointer.startsWith("/")) || /~(?:[^01]|$)/.test(pointer)) {
+    throw new Error('invalid JSON pointer: use "" for the root, / between keys, ~0 for ~ and ~1 for /');
+  }
+}
+
+function arrayIndex(key: string, length: number): boolean {
+  const index = Number(key);
+  return /^(0|[1-9][0-9]*)$/.test(key) && Number.isSafeInteger(index) && index < length;
+}
+
+function missingPointer(parent: unknown, segment: number): Error {
+  const array = Array.isArray(parent);
+  const kind = parent === null ? "null" : array ? "array" : typeof parent;
+  const keys = parent !== null && typeof parent === "object"
+    ? Object.keys(parent).filter((key) => !array || arrayIndex(key, parent.length)) : [];
+  const shown = keys.filter((key) => key.length <= HINT_KEY_UNITS).sort().slice(0, HINT_KEYS);
+  // Segment ordinal identifies the valid prefix without echoing unbounded input
+  // paths or source values. Omitted names remain readable through that prefix.
+  return new Error(`JSON pointer does not exist at segment ${segment}; parent type: ${kind}. ` +
+    `Available keys (${shown.length} of ${keys.length}): ${JSON.stringify(shown)}; ` +
+    `${keys.length - shown.length} omitted (long names or diagnostic budget). ` +
+    `Inspect the pointer prefix before segment ${segment}; use pointer="" for the document root. ` +
+    "The pointer / selects an empty key, not the root.");
+}
+
+export function resolveJsonPointer(document: unknown, pointer: string): unknown {
+  validateJsonPointer(pointer);
+  if (pointer === "") return document;
+  let value = document;
+  for (const [index, raw] of pointer.slice(1).split("/").entries()) {
+    const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (value === null || typeof value !== "object" ||
+        (Array.isArray(value) && !arrayIndex(key, value.length)) || !Object.hasOwn(value, key)) {
+      throw missingPointer(value, index + 1);
+    }
+    value = (value as Record<string, unknown>)[key];
+  }
+  return value;
+}

package/src/core/keymap.ts

@@ -0,0 +1,241 @@
+/**
+ * Action id ↔ key chord. Pure: the file is read in store; this module
+ * parses, reports conflicts by name, and lets the last definition win.
+ *
+ * Silent drop of one side of a conflict is how a shortcut "just stops
+ * working" with no trail (feat-theming design). Namespaced ids follow
+ * pi's scheme; the action list is ours.
+ */
+
+export const ACTION_IDS = [
+  "editor.cursorLeft",
+  "editor.cursorRight",
+  "editor.cursorWordLeft",
+  "editor.cursorWordRight",
+  "editor.cursorLineStart",
+  "editor.cursorLineEnd",
+  "editor.cursorUp",
+  "editor.cursorDown",
+  "editor.deleteCharBackward",
+  "editor.deleteCharForward",
+  "editor.deleteWordBackward",
+  "editor.deleteToLineStart",
+  "editor.deleteToLineEnd",
+  "editor.submit",
+  "editor.newLine",
+  "editor.undo",
+  "editor.yank",
+  "editor.deleteWordForward",
+  "editor.complete",
+  "app.toggleTools",
+  "app.toggleThinking",
+  "app.interrupt",
+  "app.exit",
+  "app.message.followUp",
+  "app.message.dequeue",
+  "app.model",
+  "app.cycleModel",
+  "app.cycleModelReverse",
+  "app.cycleThinking",
+  "app.saveDefault",
+  "app.externalEditor",
+] as const;
+
+export type ActionId = (typeof ACTION_IDS)[number];
+
+export interface Chord {
+  readonly ctrl: boolean;
+  readonly alt: boolean;
+  readonly shift: boolean;
+  readonly super: boolean;
+  readonly key: string;
+}
+
+export interface Keymap {
+  readonly byKey: Readonly<Record<string, ActionId>>;
+  readonly byAction: Readonly<Record<string, readonly string[]>>;
+  readonly diagnostics: readonly string[];
+}
+
+const ACTION_SET = new Set<string>(ACTION_IDS);
+
+const NAMED_KEYS = new Set([
+  "escape",
+  "esc",
+  "enter",
+  "return",
+  "tab",
+  "space",
+  "backspace",
+  "delete",
+  "insert",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "up",
+  "down",
+  "left",
+  "right",
+]);
+
+export function parseKey(spec: string): Chord | { error: string } {
+  const raw = spec.trim();
+  if (raw.length === 0) return { error: `unparseable key: ${JSON.stringify(spec)}` };
+  const parts = raw.split("+").map((p) => p.trim()).filter((p) => p.length > 0);
+  if (parts.length === 0) return { error: `unparseable key: ${JSON.stringify(spec)}` };
+  let ctrl = false;
+  let alt = false;
+  let shift = false;
+  let superKey = false;
+  const last = parts[parts.length - 1]!;
+  for (const part of parts.slice(0, -1)) {
+    const m = part.toLowerCase();
+    if (m === "ctrl" || m === "control") ctrl = true;
+    else if (m === "alt" || m === "option") alt = true;
+    else if (m === "shift") shift = true;
+    else if (m === "super" || m === "cmd" || m === "meta") superKey = true;
+    else return { error: `unparseable key: ${JSON.stringify(spec)}` };
+  }
+  const key = normalizeKeyName(last);
+  if (key === null) return { error: `unparseable key: ${JSON.stringify(spec)}` };
+  return { ctrl, alt, shift, super: superKey, key };
+}
+
+export function formatKey(chord: Chord): string {
+  const parts: string[] = [];
+  if (chord.ctrl) parts.push("ctrl");
+  if (chord.alt) parts.push("alt");
+  if (chord.shift) parts.push("shift");
+  if (chord.super) parts.push("super");
+  parts.push(chord.key);
+  return parts.join("+");
+}
+
+export function resolveAction(map: Keymap, spec: string): ActionId | undefined {
+  const parsed = parseKey(spec);
+  if ("error" in parsed) return undefined;
+  return map.byKey[formatKey(parsed)];
+}
+
+export function defaultKeymap(): Keymap {
+  return parseKeymap(
+    {
+      "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+a"],
+      "editor.cursorLineEnd": ["end", "ctrl+e"],
+      "editor.cursorUp": ["up"],
+      "editor.cursorDown": ["down"],
+      "editor.deleteCharBackward": ["backspace"],
+      "editor.deleteCharForward": ["delete", "ctrl+d"],
+      "editor.deleteWordBackward": ["ctrl+w", "alt+backspace"],
+      "editor.deleteWordForward": ["alt+d"],
+      "editor.deleteToLineStart": ["ctrl+u"],
+      "editor.deleteToLineEnd": ["ctrl+k"],
+      "editor.submit": ["enter"],
+      "editor.newLine": ["shift+enter", "ctrl+j"],
+      "editor.undo": ["ctrl+-", "ctrl+z", "ctrl+_"],
+      "editor.yank": ["ctrl+y"],
+      "editor.complete": ["tab"],
+      "app.toggleTools": ["ctrl+o"],
+      "app.toggleThinking": ["ctrl+t"],
+      "app.interrupt": ["escape"],
+      "app.exit": ["ctrl+c"],
+      "app.message.followUp": ["alt+enter"],
+      "app.message.dequeue": ["alt+up"],
+      "app.model": ["ctrl+l"],
+      "app.cycleModel": ["ctrl+p"],
+      "app.cycleModelReverse": ["ctrl+shift+p"],
+      "app.cycleThinking": ["shift+tab"],
+      "app.saveDefault": ["ctrl+s"],
+      "app.externalEditor": ["ctrl+g"],
+    },
+    emptyKeymap(),
+  );
+}
+
+export function parseKeymap(json: unknown, base?: Keymap): Keymap {
+  const diagnostics: string[] = [];
+  const byKey: { [k: string]: ActionId } = { ...(base?.byKey ?? {}) };
+
+  if (json === undefined || json === null) {
+    return finish(byKey, base?.diagnostics ?? []);
+  }
+  if (typeof json !== "object" || Array.isArray(json)) {
+    return finish(byKey, [...(base?.diagnostics ?? []), "keybindings is not an object"]);
+  }
+
+  const rec = json as { readonly [k: string]: unknown };
+  for (const [action, raw] of Object.entries(rec)) {
+    if (!ACTION_SET.has(action)) {
+      diagnostics.push(`unknown action: ${action}`);
+      continue;
+    }
+    const specs = keySpecs(raw);
+    if (specs === null) {
+      diagnostics.push(`${action}: bindings must be a string or array of strings`);
+      continue;
+    }
+    // User (or this file) replaces the previous chords for this action.
+    for (const [k, a] of Object.entries(byKey)) {
+      if (a === action) delete byKey[k];
+    }
+    for (const spec of specs) {
+      const parsed = parseKey(spec);
+      if ("error" in parsed) {
+        diagnostics.push(`${parsed.error} (action ${action})`);
+        continue;
+      }
+      const id = formatKey(parsed);
+      const prev = byKey[id];
+      if (prev !== undefined && prev !== action) {
+        diagnostics.push(`key ${id} is bound to both ${prev} and ${action}; ${action} wins`);
+      }
+      byKey[id] = action as ActionId;
+    }
+  }
+
+  return finish(byKey, [...(base?.diagnostics ?? []), ...diagnostics]);
+}
+
+export function listBindings(map: Keymap): { action: string; keys: readonly string[] }[] {
+  return ACTION_IDS.filter((a) => (map.byAction[a] ?? []).length > 0).map((action) => ({
+    action,
+    keys: map.byAction[action] ?? [],
+  }));
+}
+
+function emptyKeymap(): Keymap {
+  return { byKey: {}, byAction: {}, diagnostics: [] };
+}
+
+function finish(byKey: { readonly [k: string]: ActionId }, diagnostics: readonly string[]): Keymap {
+  const byAction: { [k: string]: string[] } = {};
+  for (const [key, action] of Object.entries(byKey)) {
+    const list = byAction[action] ?? [];
+    list.push(key);
+    byAction[action] = list;
+  }
+  return { byKey, byAction, diagnostics };
+}
+
+function keySpecs(raw: unknown): string[] | null {
+  if (typeof raw === "string") return [raw];
+  if (Array.isArray(raw) && raw.every((x) => typeof x === "string")) return raw as string[];
+  return null;
+}
+
+function normalizeKeyName(raw: string): string | null {
+  const lower = raw.toLowerCase();
+  if (lower === "esc") return "escape";
+  if (lower === "return") return "enter";
+  if (lower === "pageup") return "pageup";
+  if (lower === "pagedown") return "pagedown";
+  if (NAMED_KEYS.has(lower)) return lower === "esc" ? "escape" : lower === "return" ? "enter" : lower;
+  if (/^f([1-9]|1[0-2])$/.test(lower)) return lower;
+  if (raw.length === 1) return lower;
+  return null;
+}

package/src/core/observation-view.ts

@@ -0,0 +1,87 @@
+/**
+ * How a bounded observation is presented to the model.
+ *
+ * The complete bytes always live in a blob (D8: reference, never inline), so
+ * this is only a view -- but it is the view the model reasons from. Keeping
+ * only the head, as this module's predecessor did, cuts exactly the part a
+ * failing build or test run prints last: the error and the summary. Codex
+ * keeps half of each end (`utils/string/src/truncate.rs`); so does this.
+ */
+
+/** A UTF-8 continuation byte: cutting before one would split a character. */
+const continuation = (byte: number | undefined) => byte !== undefined && (byte & 0xc0) === 0x80;
+
+/**
+ * Head and tail of an observation within `limit` bytes.
+ *
+ * `head` is the first bytes and `tail` the last bytes of an observation of
+ * `total` bytes; each need only be as long as `limit`. When the whole
+ * observation fits, it is returned unchanged. Otherwise the marker, which is
+ * given the omitted byte count and the byte offset where the gap starts (so
+ * the model can page the missing middle back), sits between the two ends.
+ * Cuts land on character boundaries, which is why a view can come out a few
+ * bytes under budget but never over it for valid UTF-8 input.
+ */
+export function headTailView(
+  head: Uint8Array,
+  tail: Uint8Array,
+  total: number,
+  limit: number,
+  marker: (omitted: number, offset: number) => string,
+): string {
+  const decoder = new TextDecoder();
+  if (total <= limit && head.length >= total) return decoder.decode(head.subarray(0, total));
+  // Digits of the real numbers never exceed digits of `total`, so this bounds
+  // the marker before the cut points that decide its numbers are known.
+  const reserve = new TextEncoder().encode(marker(total, total)).length;
+  const budget = Math.max(0, limit - reserve);
+  let headEnd = Math.min(Math.floor(budget / 2), head.length);
+  while (headEnd > 0 && continuation(head[headEnd])) headEnd--;
+  let tailStart = tail.length - Math.min(budget - headEnd, tail.length);
+  while (tailStart < tail.length && continuation(tail[tailStart])) tailStart++;
+  const kept = tail.length - tailStart;
+  return decoder.decode(head.subarray(0, headEnd)) +
+    marker(total - headEnd - kept, headEnd) +
+    decoder.decode(tail.subarray(tailStart));
+}
+
+/** Signals a shell reports as 128+n; the common ones a model can act on. */
+const SIGNALS: Readonly<Record<number, string>> = {
+  1: "SIGHUP", 2: "SIGINT", 6: "SIGABRT", 9: "SIGKILL", 11: "SIGSEGV", 13: "SIGPIPE", 15: "SIGTERM",
+};
+
+const seconds = (ms: number) => `${Number((ms / 1000).toFixed(1))}s`;
+
+/**
+ * First line of a command result.
+ *
+ * `exit N` stays first because both the TUI and the log readers key on it.
+ * What follows states facts the exit code alone hides: a timeout reads as
+ * `exit 143`, which a model otherwise takes for the program's own failure and
+ * reruns unchanged (codex puts wall time and exit in the same header,
+ * `core/src/tools/context.rs`).
+ */
+export function commandHeader(input: {
+  exit: number;
+  wallMs: number;
+  stopped?: "timeout" | "cancelled";
+  /** The timeout actually applied. */
+  timeoutMs: number;
+  /** What the model asked for, when that differs from what was applied. */
+  requestedMs?: number;
+}): string {
+  const parts = [`exit ${input.exit}`, `${(input.wallMs / 1000).toFixed(1)}s`];
+  if (input.stopped === "timeout") {
+    const requested = input.requestedMs !== undefined && input.requestedMs !== input.timeoutMs
+      ? ` (requested ${seconds(input.requestedMs)}, capped)` : "";
+    // Say what to do differently: the same command with the same timeout
+    // will time out the same way.
+    parts.push(`timed out after ${seconds(input.timeoutMs)}${requested}; process group terminated; ` +
+      "rerun with a larger timeout, or start long-lived work in the background with output redirected to a file and poll it");
+  } else if (input.stopped === "cancelled") {
+    parts.push("cancelled; process group terminated");
+  } else if (input.exit > 128 && SIGNALS[input.exit - 128] !== undefined) {
+    parts.push(`128+${input.exit - 128}: likely terminated by ${SIGNALS[input.exit - 128]}`);
+  }
+  return parts.join(" · ");
+}

package/src/core/outcome.ts

@@ -0,0 +1,45 @@
+/** O.1 / D11: execution termination is a fact, distinct from verified work. */
+const STATUS = {
+  model_end: "completed",
+  tool_completed: "completed",
+  cancelled: "cancelled",
+  not_started: "cancelled",
+  max_turns: "stopped",
+  context_budget: "stopped",
+  stalled: "stopped",
+  no_progress: "stopped",
+  output_limit: "stopped",
+  timeout: "stopped",
+  model_refusal: "failed",
+  provider_error: "failed",
+  execution_error: "failed",
+  projection_invalid: "failed",
+  snapshot_failed: "failed",
+  tool_failed: "failed",
+  unknown: "unknown",
+} as const;
+
+export type ExecutionReason = keyof typeof STATUS;
+export type ExecutionOutcome = {
+  status: (typeof STATUS)[ExecutionReason];
+  reason: ExecutionReason;
+};
+
+export function executionOutcome(reason: ExecutionReason): ExecutionOutcome {
+  return { status: STATUS[reason], reason };
+}
+
+/** Unknown/legacy provider reasons never silently turn into success. */
+export function modelOutcome(reason: string | null): ExecutionOutcome {
+  if (reason === "end_turn" || reason === "stop" || reason === "stop_sequence") return executionOutcome("model_end");
+  if (reason === "max_tokens" || reason === "length") return executionOutcome("output_limit");
+  if (reason === "refusal" || reason === "content_filter") return executionOutcome("model_refusal");
+  if (reason === "error") return executionOutcome("provider_error");
+  return executionOutcome("unknown");
+}
+
+export function isExecutionOutcome(value: unknown): value is ExecutionOutcome {
+  if (value === null || typeof value !== "object" || !("reason" in value) || !("status" in value)) return false;
+  return typeof value.reason === "string" && Object.hasOwn(STATUS, value.reason) &&
+    value.status === STATUS[value.reason as ExecutionReason];
+}