@visual-z/xeno 0.2.1 → 0.3.0

package/src/core/theme.ts

@@ -37,7 +37,7 @@ export const THEME_TOKENS = [
 export type ThemeToken = (typeof THEME_TOKENS)[number];
 
 export type ThemeColors = { readonly [K in ThemeToken]: string } & Readonly<Record<string, string>>;
-const PI_THEME_TOKENS: readonly string[] = ["accent","border","borderAccent","borderMuted","success","error","warning","muted","dim","text","thinkingText","scrollbarTrack","scrollbarThumb","searchMatchText","userMessageText","customMessageText","customMessageLabel","toolTitle","toolOutput","mdHeading","mdLink","mdLinkUrl","mdCode","mdCodeBlock","mdCodeBlockBorder","mdQuote","mdQuoteBorder","mdHr","mdListBullet","toolDiffAdded","toolDiffRemoved","toolDiffContext","syntaxComment","syntaxKeyword","syntaxFunction","syntaxVariable","syntaxString","syntaxNumber","syntaxType","syntaxOperator","syntaxPunctuation","thinkingOff","thinkingMinimal","thinkingLow","thinkingMedium","thinkingHigh","thinkingXhigh","thinkingMax","bashMode","selectedBg","searchMatchBg","userMessageBg","customMessageBg","toolPendingBg","toolSuccessBg","toolErrorBg"];
+const PI_THEME_TOKENS: readonly string[] = ["background","accent","border","borderAccent","borderMuted","success","error","warning","muted","dim","text","thinkingText","scrollbarTrack","scrollbarThumb","searchMatchText","userMessageText","customMessageText","customMessageLabel","toolTitle","toolOutput","mdHeading","mdLink","mdLinkUrl","mdCode","mdCodeBlock","mdCodeBlockBorder","mdQuote","mdQuoteBorder","mdHr","mdListBullet","toolDiffAdded","toolDiffRemoved","toolDiffContext","syntaxComment","syntaxKeyword","syntaxFunction","syntaxVariable","syntaxString","syntaxNumber","syntaxType","syntaxOperator","syntaxPunctuation","thinkingOff","thinkingMinimal","thinkingLow","thinkingMedium","thinkingHigh","thinkingXhigh","thinkingMax","bashMode","selectedBg","searchMatchBg","userMessageBg","customMessageBg","toolPendingBg","toolSuccessBg","toolErrorBg"];
 
 export interface Theme {
   readonly name: string;
@@ -50,64 +50,33 @@ export interface ThemeParse {
 }
 
 /**
- * Palette adapted from pi (earendil-works/pi, MIT), coding-agent theme/dark.json
- * and light.json at 3390bd93630965a12a0a1a5c36ce890ec22f7e1d. Existing custom
- * tokens remain accepted; missing presentation tokens inherit these defaults.
+ * Built-in appearances own no colours of their own: every token is one of the
+ * terminal's 16 slots or its default (empty), and no token paints a
+ * background (docs/tasks/refactor-tui-terminal-colors.md). The interactive
+ * view derives finer greys from the terminal's reported palette; these
+ * tokens are what line mode and an unreporting terminal get.
+ *
+ * `dark` and `light` differ only in which half of the palette stays legible:
+ * bright slots on a dark ground, normal slots on a light one. Muted text is a
+ * grey slot, never SGR faint (faint made muted arguments unreadable).
  */
-const DARK_COLORS: ThemeColors = {
-  "text": "38;2;212;212;212",
-  "thinkingText": "38;2;128;128;128",
-  "toolTitle": "38;2;212;212;212",
-  "toolOutput": "38;2;128;128;128",
-  "error": "38;2;204;102;102",
-  "toolDiffAdded": "38;2;181;189;104",
-  "toolDiffRemoved": "38;2;204;102;102",
-  "status": "38;2;128;128;128",
-  "prompt": "38;2;212;212;212",
-  "selectedBg": "48;2;58;58;74",
-  "muted": "38;2;128;128;128",
-  "warning": "38;2;255;255;0",
-  "mdHeading": "38;2;240;198;116",
-  "mdCode": "38;2;138;190;183",
-  "mdLink": "38;2;129;162;190",
-  "userMessageBg": "48;2;52;53;65",
-  "toolPendingBg": "48;2;40;40;50",
-  "toolSuccessBg": "48;2;40;50;40",
-  "toolErrorBg": "48;2;60;40;40",
-  "thinkingLow": "38;2;95;135;175",
-  "thinkingMedium": "38;2;129;162;190",
-  "thinkingHigh": "38;2;178;148;187",
-  "thinkingXhigh": "38;2;209;131;232",
-  "thinkingMax": "38;2;255;95;255"
-};
+const DARK_COLORS: ThemeColors = terminalTokens({ muted: "37", red: "91", green: "92", yellow: "93", blue: "94", magenta: "95", cyan: "96", rule: "90" });
+const LIGHT_COLORS: ThemeColors = terminalTokens({ muted: "90", red: "31", green: "32", yellow: "33", blue: "34", magenta: "35", cyan: "36", rule: "37" });
 
-/** Distinct from dark so `--theme light` is visible without OSC 11 probing. */
-const LIGHT_COLORS: ThemeColors = {
-  "text": "38;2;31;35;40",
-  "thinkingText": "38;2;108;108;108",
-  "toolTitle": "38;2;31;35;40",
-  "toolOutput": "38;2;108;108;108",
-  "error": "38;2;170;85;85",
-  "toolDiffAdded": "38;2;88;132;88",
-  "toolDiffRemoved": "38;2;170;85;85",
-  "status": "38;2;108;108;108",
-  "prompt": "38;2;31;35;40",
-  "selectedBg": "48;2;208;208;224",
-  "muted": "38;2;108;108;108",
-  "warning": "38;2;154;115;38",
-  "mdHeading": "38;2;154;115;38",
-  "mdCode": "38;2;90;128;128",
-  "mdLink": "38;2;84;125;167",
-  "userMessageBg": "48;2;232;232;232",
-  "toolPendingBg": "48;2;232;232;240",
-  "toolSuccessBg": "48;2;232;240;232",
-  "toolErrorBg": "48;2;240;232;232",
-  "thinkingLow": "38;2;84;125;167",
-  "thinkingMedium": "38;2;90;128;128",
-  "thinkingHigh": "38;2;135;95;135",
-  "thinkingXhigh": "38;2;139;0;139",
-  "thinkingMax": "38;2;175;0;95"
-};
+function terminalTokens(slot: { muted: string; red: string; green: string; yellow: string; blue: string; magenta: string; cyan: string; rule: string }): ThemeColors {
+  return {
+    text: "", prompt: "", background: "",
+    thinkingText: slot.magenta, toolTitle: "", toolOutput: slot.muted,
+    error: slot.red, toolDiffAdded: slot.green, toolDiffRemoved: slot.red,
+    status: slot.muted, muted: slot.muted, dim: slot.muted, warning: slot.yellow, success: slot.green, accent: slot.blue,
+    mdHeading: slot.blue, mdCode: slot.cyan, mdLink: slot.blue,
+    selectedBg: "", userMessageBg: "", toolPendingBg: "", toolSuccessBg: "", toolErrorBg: "",
+    border: slot.rule, borderMuted: slot.rule,
+    thinkingOff: slot.muted, thinkingMinimal: slot.magenta, thinkingLow: slot.magenta, thinkingMedium: slot.magenta,
+    thinkingHigh: slot.magenta, thinkingXhigh: slot.magenta, thinkingMax: slot.magenta,
+    syntaxKeyword: slot.magenta, syntaxString: slot.green, syntaxNumber: slot.yellow, syntaxFunction: slot.blue, syntaxComment: slot.muted,
+  };
+}
 
 export function builtinTheme(name: "dark" | "light"): Theme {
   return name === "light"
@@ -115,6 +84,15 @@ export function builtinTheme(name: "dark" | "light"): Theme {
     : { name: "dark", colors: DARK_COLORS };
 }
 
+/**
+ * A built-in appearance (dark, light, or system/auto, which reuse them) as
+ * opposed to a theme file. Identity, not name: a file may call itself "dark",
+ * and parseTheme always copies colours into a new object.
+ */
+export function isBuiltinTheme(theme: Theme): boolean {
+  return theme.colors === DARK_COLORS || theme.colors === LIGHT_COLORS;
+}
+
 export function parseTheme(json: unknown): ThemeParse {
   const fallback = builtinTheme("dark");
   if (typeof json !== "object" || json === null || Array.isArray(json)) {
@@ -153,7 +131,7 @@ export function parseTheme(json: unknown): ThemeParse {
       diagnostics.push(`invalid colour for ${token}; using built-in`);
       continue;
     }
-    colors[token] = token.endsWith("Bg") ? parsed.replace(/^38;/, "48;") : parsed;
+    colors[token] = (token.endsWith("Bg") || token === "background") ? parsed.replace(/^38;/, "48;") : parsed;
   }
 
   if (!("status" in src) && "dim" in colors) colors.status = colors["dim"]!;

package/src/core/tool-contract.ts

@@ -1,9 +1,17 @@
 /** O.3: one declarative input contract serves model schemas and runtime admission. */
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };
 export type ToolDiagnostic = {
-  code: "invalid_input" | "version_mismatch" | "not_found" | "ambiguous_edit" | "permission_denied" | "execution_failed";
+  code: "invalid_input" | "version_mismatch" | "not_found" | "ambiguous_edit" | "permission_denied" | "execution_failed" |
+    "environment_missing" | "transient" | "cancelled" | "timeout" | "unknown_effect" | "command_failed";
   message: string;
   recover?: { tool: string; input: { readonly [key: string]: JsonValue } };
+  /** R3: optional only for legacy records; supplied together by current failure owners. */
+  execution?: "not_started" | "started" | "unknown";
+  effects?: "none" | "possible";
+  retry?: "never" | "after_change" | "after_inspection" | "backoff";
+  next?: string;
+  /** A schema-valid shape with placeholders, never an automatically executable recovery. */
+  example?: { readonly [key: string]: JsonValue };
 };
 
 export function isJsonValue(value: unknown): value is JsonValue {
@@ -15,7 +23,17 @@ export function isJsonValue(value: unknown): value is JsonValue {
 export function isToolDiagnostic(value: unknown): value is ToolDiagnostic {
   if (value === null || typeof value !== "object") return false;
   const item = value as Record<string, unknown>;
-  if (!["invalid_input", "version_mismatch", "not_found", "ambiguous_edit", "permission_denied", "execution_failed"].includes(String(item["code"])) || typeof item["message"] !== "string") return false;
+  if (!["invalid_input", "version_mismatch", "not_found", "ambiguous_edit", "permission_denied", "execution_failed",
+    "environment_missing", "transient", "cancelled", "timeout", "unknown_effect", "command_failed"].includes(String(item["code"])) || typeof item["message"] !== "string") return false;
+  if (["execution", "effects", "retry", "next"].some(key => item[key] !== undefined)) {
+    if (!["not_started", "started", "unknown"].includes(String(item["execution"])) ||
+      !["none", "possible"].includes(String(item["effects"])) ||
+      !["never", "after_change", "after_inspection", "backoff"].includes(String(item["retry"])) || typeof item["next"] !== "string") return false;
+    if (item["retry"] === "backoff" && (item["code"] !== "transient" || item["effects"] !== "none")) return false;
+    if (item["code"] === "permission_denied" && (item["retry"] !== "never" || item["recover"] !== undefined)) return false;
+    if (item["code"] === "unknown_effect" && item["retry"] !== "after_inspection") return false;
+  }
+  if (item["example"] !== undefined && (item["example"] === null || typeof item["example"] !== "object" || Array.isArray(item["example"]) || !isJsonValue(item["example"]))) return false;
   const recover = item["recover"];
   if (recover === undefined) return true;
   if (recover === null || typeof recover !== "object") return false;
@@ -24,6 +42,37 @@ export function isToolDiagnostic(value: unknown): value is ToolDiagnostic {
     typeof recovery["input"] === "object" && !Array.isArray(recovery["input"]) && isJsonValue(recovery["input"]);
 }
 
+/** Required fields only; examples express a valid shape, not permission or a safe command. */
+export function minimalInput(schema: unknown): JsonValue | undefined {
+  if (schema === null || typeof schema !== "object") return undefined;
+  const s = schema as Record<string, unknown>;
+  if (Array.isArray(s["enum"]) && s["enum"].length && isJsonValue(s["enum"][0])) return s["enum"][0];
+  switch (s["type"]) {
+    case "string": return "<value>".padEnd(typeof s["minLength"] === "number" ? Math.min(4096, s["minLength"]) : 0, "x");
+    case "number": case "integer": return typeof s["minimum"] === "number" ? s["minimum"] : 0;
+    case "boolean": return false;
+    case "array": return [];
+    case "object": {
+      const value: { [key: string]: JsonValue } = {};
+      const properties = s["properties"];
+      for (const key of Array.isArray(s["required"]) ? s["required"] : []) {
+        if (typeof key !== "string" || properties === null || typeof properties !== "object") return undefined;
+        const item = minimalInput((properties as Record<string, unknown>)[key]);
+        if (item === undefined) return undefined;
+        value[key] = item;
+      }
+      return value;
+    }
+    default: return null;
+  }
+}
+
+/** Diagnostics are projected as tool data; they never become trusted system instructions. */
+export function diagnosticContent(content: string, diagnostic?: ToolDiagnostic): string {
+  if (diagnostic?.execution === undefined) return content;
+  return content + "\nTool diagnostic: " + JSON.stringify(diagnostic);
+}
+
 import { editDistance } from "./text-normalize.ts";
 
 /**

package/src/core/tool-discovery.ts

@@ -0,0 +1,87 @@
+/** R11 / D6 / D8: local discovery proposes declarations; only a paired checkpoint installs them. */
+import type { LogEvent, ToolInvocationEvent } from "./events.ts";
+
+/** Assumed response bounds, not measured model optima; prevent a directory dump from replacing a lookup. */
+export const MAX_DISCOVERY_RESULTS = 8;
+export const MAX_DISCOVERY_QUERY = 256;
+const MAX_PARAMETER_HINTS = 8;
+const MAX_PURPOSE_CHARS = 320;
+
+export interface DiscoverableTool {
+  readonly name: string;
+  readonly description: string;
+  readonly input_schema: { readonly properties: Readonly<Record<string, unknown>>; readonly required: readonly string[] };
+}
+export interface DeclarationRequest { readonly name: string; readonly fingerprint: string }
+export interface DiscoveryMatch {
+  name: string; purpose: string; inputs: { name: string; type: string; required: boolean }[]; omitted_inputs: number;
+}
+export function declaredToolNames(tools: readonly unknown[]): string[] {
+  return tools.flatMap(tool => tool !== null && typeof tool === "object" && "name" in tool && typeof tool.name === "string" ? [tool.name] : []);
+}
+const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+function record(raw: unknown): Record<string, unknown> | undefined {
+  return raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : undefined;
+}
+function parameterType(raw: unknown): string {
+  if (raw === null || typeof raw !== "object") return "schema";
+  const type = (raw as Record<string, unknown>)["type"];
+  if (typeof type === "string") return type.slice(0, 64);
+  if (Array.isArray(type) && type.every(item => typeof item === "string")) return type.join("|").slice(0, 64);
+  return "schema";
+}
+
+/** Pure, deterministic matching over the caller's already-selected directory; never perform discovery I/O. */
+export function discoverTools(catalog: readonly DiscoverableTool[], query: string, limit = 5): DiscoveryMatch[] {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_DISCOVERY_RESULTS) throw new Error("invalid discovery limit");
+  const normalized = query.trim().toLowerCase();
+  if (!normalized || query.length > MAX_DISCOVERY_QUERY) throw new Error("query must contain 1 to 256 characters");
+  const terms = normalized.split(/[^\p{L}\p{N}_-]+/u).filter(Boolean);
+  if (terms.length === 0) return [];
+  return catalog.map(tool => {
+    const name = tool.name.toLowerCase(), text = `${name} ${tool.description.toLowerCase()}`;
+    const score = name === normalized ? 100 : terms.every(term => text.includes(term))
+      ? 1 + terms.filter(term => name.includes(term)).length : 0;
+    return { tool, score };
+  }).filter(item => item.score > 0).sort((a, b) => b.score - a.score || compare(a.tool.name, b.tool.name))
+    .slice(0, limit).map(({ tool }) => {
+      const required = new Set(tool.input_schema.required);
+      const parameters = Object.entries(tool.input_schema.properties).sort(([a], [b]) =>
+        Number(required.has(b)) - Number(required.has(a)) || compare(a, b));
+      return { name: tool.name, purpose: tool.description.slice(0, MAX_PURPOSE_CHARS),
+        inputs: parameters.slice(0, MAX_PARAMETER_HINTS).map(([name, raw]) => ({ name: name.slice(0, 128), type: parameterType(raw), required: required.has(name) })),
+        omitted_inputs: Math.max(0, parameters.length - MAX_PARAMETER_HINTS) };
+    });
+}
+
+/** A model assertion or another extension's data cannot authorize a declaration (D11). */
+export function recordedDeclarations(events: readonly LogEvent[]): DeclarationRequest[] {
+  const invocations = new Map<string, ToolInvocationEvent>();
+  const requested = new Map<string, { request: DeclarationRequest; user: string | undefined }>();
+  let user: string | undefined;
+  for (const event of events) {
+    if (event.t === "user") { user = event.id; continue; }
+    if (event.t === "interrupt") {
+      for (const [name, value] of requested) if (value.user === event.user_id) requested.delete(name);
+      continue;
+    }
+    if (event.t === "tool_invocation") { invocations.set(event.id, event); continue; }
+    if (event.t !== "tool_result" || !event.ok || !event.invocation_ref) continue;
+    if (event.outcome !== undefined && event.outcome.status !== "completed") continue;
+    const invocation = invocations.get(event.invocation_ref.event);
+    if (invocation?.name !== "tool_search" || invocation.call_id !== event.call_id) continue;
+    const data = record(event.data);
+    if (!data || data["kind"] !== "tool_discovery" || data["version"] !== 1) continue;
+    const entries = data["requested"];
+    if (!Array.isArray(entries) || entries.length > MAX_DISCOVERY_RESULTS) continue;
+    for (const entry of entries) {
+      const item = record(entry);
+      if (!item) continue;
+      const name = item["name"], fingerprint = item["fingerprint"];
+      if (typeof name === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(name) && typeof fingerprint === "string" && /^[a-f0-9]{64}$/.test(fingerprint)) {
+        requested.set(name, { request: { name, fingerprint }, user });
+      }
+    }
+  }
+  return [...requested.values()].map(value => value.request);
+}

package/src/core/tool-failure.ts

@@ -0,0 +1,60 @@
+/** R3 / D11: failure policy follows observed execution facts, never output keywords. */
+import type { ToolDiagnostic } from "./tool-contract.ts";
+
+export type FailureFacts = { execution: "not_started" | "started" | "unknown"; effects: "none" | "possible" };
+export const NOT_STARTED: FailureFacts = { execution: "not_started", effects: "none" };
+export const READ_ATTEMPTED: FailureFacts = { execution: "started", effects: "none" };
+export const UNKNOWN_EFFECT: FailureFacts = { execution: "unknown", effects: "possible" };
+
+const guidance: Record<ToolDiagnostic["code"], string> = {
+  invalid_input: "Correct the named argument using the tool schema; example values are placeholders.",
+  version_mismatch: "Read the current resource and derive a new edit from that version.",
+  not_found: "Verify the resource path or identifier before changing the request.",
+  ambiguous_edit: "Read the indicated range and choose a unique match before editing.",
+  permission_denied: "This operation was denied. Do not bypass it through another tool or wrapper; a user policy change is required.",
+  execution_failed: "Inspect the failure and change its cause before retrying.",
+  environment_missing: "Verify the working directory and required executable in this environment before retrying. If available and permitted, use environment with the exact program; use its python probe for actual Python API support.",
+  transient: "Retry with bounded backoff only if no side effect is possible.",
+  cancelled: "Respect cancellation; inspect any partial effects before a user-authorized continuation.",
+  timeout: "Inspect partial output and effects before deciding whether a new invocation is needed.",
+  unknown_effect: "Execution or effects are uncertain. Inspect existing state and output before any replay.",
+  command_failed: "Use the actual exit and output to diagnose the command; a nonzero exit alone does not identify its cause.",
+};
+
+export function failureDiagnostic(code: ToolDiagnostic["code"], message: string, facts: FailureFacts,
+  extra: Pick<ToolDiagnostic, "recover" | "example"> = {}): ToolDiagnostic {
+  const retry = code === "permission_denied" || code === "cancelled" ? "never"
+    : code === "unknown_effect" || facts.effects === "possible" ? "after_inspection"
+    : code === "transient" ? "backoff" : "after_change";
+  return { code, message, ...facts, retry, next: guidance[code], ...(code === "permission_denied" ? {} : extra) };
+}
+
+/** R10: only new advice is scoped; execution facts and historical records are never rewritten. */
+export function scopeFailureGuidance(diagnostic: ToolDiagnostic, tools: readonly string[], recoverAllowed = true): ToolDiagnostic {
+  const { recover, ...facts } = diagnostic;
+  const next = diagnostic.execution !== undefined && diagnostic.code === "environment_missing" && !tools.includes("environment")
+    ? { next: "Verify the working directory and required executable in the current executor using permitted observations. If the needed capability is unavailable, report that evidence gap before retrying." } : {};
+  return { ...facts, ...next, ...(recover && recoverAllowed && tools.includes(recover.tool) && diagnostic.code !== "permission_denied" ? { recover } : {}) };
+}
+
+/** Runtime and store throw only facts they own; the outer boundary must retain these facts. */
+export class ToolFault extends Error {
+  readonly diagnostic: ToolDiagnostic;
+  constructor(code: ToolDiagnostic["code"], message: string, facts: FailureFacts, extra: Pick<ToolDiagnostic, "recover"> = {}) {
+    super(message); this.name = "ToolFault";
+    this.diagnostic = failureDiagnostic(code, message, facts, extra);
+  }
+}
+
+/** OS codes are facts; words like "denied" in arbitrary output are not classification evidence. */
+export function failureFromError(error: unknown, facts: FailureFacts): ToolDiagnostic {
+  if (error instanceof ToolFault) return error.diagnostic;
+  const message = error instanceof Error ? error.message : String(error);
+  const os = error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
+  const code = os === "ENOENT" || os === "ENOTDIR" ? "not_found"
+    : os === "EACCES" || os === "EPERM" ? "permission_denied"
+    : os === "EISDIR" ? "invalid_input"
+    : ["EAGAIN", "ETIMEDOUT", "ECONNRESET", "EMFILE"].includes(String(os)) ? "transient"
+    : facts.effects === "possible" ? "unknown_effect" : "execution_failed";
+  return failureDiagnostic(code, message, facts);
+}

package/src/core/tool-mode-protocol.ts

@@ -0,0 +1,25 @@
+/** Q.21: the retired orchestration contrast cannot enter new direct-query trials. */
+export const TOOL_MODE_FACTORS = ["querySyntax"] as const;
+export const TOOL_MODE_TASKS = ["tool-small", "tool-batch", "tool-aggregate"] as const;
+export type ToolModeTask = typeof TOOL_MODE_TASKS[number];
+export const isToolModeTask = (task: string): task is ToolModeTask => (TOOL_MODE_TASKS as readonly string[]).includes(task);
+export interface ToolModeEngine { packages: Record<string, string>; assets: Record<string, string> }
+export function validateToolModeEngine(engine: ToolModeEngine | undefined): asserts engine is ToolModeEngine {
+  if (!engine || engine.packages["@earendil-works/pi-ai"] !== "0.99.1" || Object.keys(engine.packages).length !== 1 ||
+    !engine.assets || !Object.entries(engine.assets).every(([path, sha]) =>
+      /^@earendil-works\/pi-ai\/[a-zA-Z0-9_./-]+$/.test(path) && !path.split("/").includes("..") && /^[a-f0-9]{64}$/.test(sha)) ||
+    ["@earendil-works/pi-ai/package.json", "@earendil-works/pi-ai/dist/api/openai-codex-responses.js"].some(path => !engine.assets[path]))
+    throw Error("tool mode engine assets are missing or unsupported");
+}
+export interface ToolModeMetrics {
+  elapsedMs: number; queryCalls: number; primitiveCalls: number;
+  sourcePaths: string[]; requiredSourcePaths: string[]; sourceComplete: boolean;
+}
+export function isToolModeMetrics(value: unknown): value is ToolModeMetrics {
+  if (!value || typeof value !== "object") return false;
+  const v = value as ToolModeMetrics;
+  const paths = (list: unknown): list is string[] => Array.isArray(list) && list.every(item => typeof item === "string") && new Set(list).size === list.length;
+  return Number.isFinite(v.elapsedMs) && v.elapsedMs >= 0 && [v.queryCalls, v.primitiveCalls].every(n => Number.isSafeInteger(n) && n >= 0) &&
+    paths(v.sourcePaths) && paths(v.requiredSourcePaths) && v.requiredSourcePaths.length > 0 &&
+    v.sourceComplete === v.requiredSourcePaths.every(path => v.sourcePaths.includes(path));
+}

package/src/core/transcript.ts

@@ -9,6 +9,8 @@ export type TranscriptItem = Identity & (
   | { kind: "assistant" | "thinking" | "notice"; text: string }
   | { kind: "custom"; text: string; customType: string; data?: unknown; entry: boolean; timestamp: string }
   | { kind: "tool"; callId: string; name: string; input: unknown; result: { text: string; ok: boolean; data?: unknown; images?: readonly ImageRef[] } | null }
+  | { kind: "shell"; command: string; output: string; exit: number; excluded: boolean }
+  | { kind: "segment"; reason: string; handoff: string; nextNode?: number; nextModel?: string }
 );
 
 export function projectTranscript(events: readonly LogEvent[], entryTypes: ReadonlySet<string> = new Set()): TranscriptItem[] {
@@ -26,8 +28,7 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
         users.set(event.id, items.length);
         items.push({ ...identity, kind: "user", text: event.text, interrupted: false, ...(event.images?.length ? { images: event.images } : {}) });
         break;
-      case "user_bash": items.push({ ...identity, kind: "notice",
-        text: `${event.excludeFromContext ? "!!" : "!"}${event.command}\n${event.content}` }); break;
+      case "user_bash": items.push({ ...identity, kind: "shell", command: event.command, output: event.content, exit: event.exit, excluded: event.excludeFromContext }); break;
       case "outcome": items.push({ ...identity, kind: "notice",
         text: `${event.outcome.status} · ${event.outcome.reason} · ${event.reason}` }); break;
       case "assistant":
@@ -39,6 +40,12 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
           } else items.push({ id, revision: id, kind: block.type === "text" ? "assistant" : "thinking", text: block.text });
         });
         break;
+      case "tool_invocation": {
+        if (!event.parent_call_id && !event.origin) break;
+        calls.set(event.call_id, items.length);
+        items.push({ ...identity, kind: "tool", callId: event.call_id, name: event.name, input: event.input ?? { artifact: event.input_ref.sha256 }, result: null });
+        break;
+      }
       case "tool_result": {
         const index = calls.get(event.call_id);
         const call = index === undefined ? undefined : items[index];
@@ -54,13 +61,21 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
         items.push({ ...identity, kind: "notice", text: "Turn interrupted" });
         break;
       }
-      case "cut": items.push({ ...identity, kind: "notice", text: `Context boundary · ${event.reason} · ${event.handoff_ref}` }); break;
+      // A segment boundary is the log's own structure; the view draws it as a divider (D20).
+      case "cut": items.push({ ...identity, kind: "segment", reason: event.reason, handoff: event.handoff_ref,
+        ...(event.next_node === undefined ? {} : { nextNode: event.next_node }), ...(event.next_model === undefined ? {} : { nextModel: event.next_model }) }); break;
       case "rewind": items.push({ ...identity, kind: "notice", text: `Navigated context (${event.mode}) · ${event.prompt}` }); break;
       case "spawn": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} · ${event.purpose}` }); break;
       case "joined": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} finished · ${event.summary}` }); break;
       case "adopt": items.push({ ...identity, kind: "notice", text: `Adopted branch ${event.branch.node}` }); break;
       case "discard": items.push({ ...identity, kind: "notice", text: `Discarded branch ${event.branch.node} · ${event.reason}` }); break;
-      case "guidance": case "snapshot": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "evidence_link":
+      case "skill_loaded": items.push({ ...identity, kind: "notice", text: `Skill ${event.name} · ${event.mode} · ${event.sha256}` }); break;
+      case "process_exit": items.push({ ...identity, kind: "notice", text: `Process ${event.session} exited ${event.exit} · output ${event.output.sha256}` }); break;
+      case "acceptance_contract": items.push({ ...identity, kind: "notice", text: `Acceptance contract · ${event.contract.id}` }); break;
+      case "target_observation": items.push({ ...identity, kind: "notice", text: `Target ${event.observation.target} · ${event.observation.state} · ${event.observation.reason}` }); break;
+      case "acceptance_decision": items.push({ ...identity, kind: "notice", text: `User accepted · ${event.criterion}` }); break;
+      case "checkpoint": case "workspace_observation":
+      case "guidance": case "snapshot": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "work_owner": case "work_dependencies": case "evidence_link":
         // These remain inspectable via /state and /export; they are not chat messages.
         break;
       default: assertNever(event, "projectTranscript");

package/src/core/trial-lifecycle.ts

@@ -0,0 +1,14 @@
+/** R12 / Q.14: runner observations complement, but never replace, gateway billing evidence. */
+export type TrialInterruption = { source: "deadline" | "caller"; phase: "initialization" | "execution"; backendRequests: number };
+export type TrialLifecycle = { version: 1; backendRequests: number; interruption: TrialInterruption | null; cleanup: "complete" | "failed" };
+
+export function isTrialLifecycle(value: unknown): value is TrialLifecycle {
+  if (!value || typeof value !== "object") return false;
+  const v=value as Record<string,unknown>, n=v["backendRequests"], interruption=v["interruption"];
+  if (v["version"]!==1 || typeof n!=="number" || !Number.isSafeInteger(n) || n<0 || v["cleanup"]!=="complete" && v["cleanup"]!=="failed") return false;
+  if (interruption===null) return true;
+  if (!interruption || typeof interruption!=="object") return false;
+  const stop=interruption as Record<string,unknown>;
+  return (stop["source"]==="deadline" || stop["source"]==="caller") && (stop["phase"]==="initialization" || stop["phase"]==="execution")
+    && stop["backendRequests"]===n && (stop["phase"]!=="initialization" || n===0);
+}

package/src/core/tui-mode.ts

@@ -0,0 +1,29 @@
+/**
+ * Which screen an interactive session uses. Pure: flag, environment and
+ * setting go in, a concrete mode and the reason come out.
+ *
+ * Fullscreen is the default (OpenCode, grok-build and Pi 1.0 all default to
+ * the alternate screen). `auto` is Codex's / grok-build's policy rather than
+ * "always", because the alternate screen has known dead ends: Zellij keeps
+ * no scrollback for it (zellij#1032, Codex turns it off there), and a dumb
+ * terminal cannot address the screen at all. Every route back to native
+ * scrollback stays: `--tui-mode regular`, `XENO_TUI_MODE`, the setting.
+ */
+export type TuiModeSetting = "auto" | "regular" | "fullscreen";
+export type TuiMode = "regular" | "fullscreen";
+
+export interface TuiModeInput {
+  readonly flag?: TuiMode | undefined;
+  readonly setting?: TuiModeSetting | undefined;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+export function resolveTuiMode(input: TuiModeInput): { mode: TuiMode; reason: string } {
+  if (input.flag) return { mode: input.flag, reason: "--tui-mode" };
+  const fromEnv = input.env["XENO_TUI_MODE"];
+  if (fromEnv === "regular" || fromEnv === "fullscreen") return { mode: fromEnv, reason: "XENO_TUI_MODE" };
+  if (input.setting === "regular" || input.setting === "fullscreen") return { mode: input.setting, reason: "settings" };
+  if (input.env["TERM"] === "dumb") return { mode: "regular", reason: "TERM=dumb cannot draw a fullscreen UI" };
+  if (input.env["ZELLIJ"] !== undefined) return { mode: "regular", reason: "Zellij keeps no scrollback for the alternate screen" };
+  return { mode: "fullscreen", reason: "default" };
+}

package/src/core/update-check.ts

@@ -0,0 +1,97 @@
+/**
+ * Whether to look for a newer xeno and what to say about it (docs/tasks/feat-update-check.md). Pure.
+ *
+ * Notify only: xeno names the command for the way it was installed and never
+ * runs it. At most one registry request a day, recorded even when it fails,
+ * and none at all offline, in CI, when turned off, or from a source checkout
+ * (where the right update is `git pull`, not a package manager). Clock,
+ * environment and the cached answer are all arguments, so every rule is a
+ * plain function of its inputs.
+ */
+import { isUpgrade } from "./version.ts";
+
+export const PACKAGE_NAME = "@visual-z/xeno";
+/** One request a day, like update-notifier; Codex uses 20 hours. Assumed. */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export type InstallKind = "bun" | "npm" | "other" | "checkout";
+
+export interface UpdateCache {
+  /** Epoch ms of the last attempt, successful or not. */
+  readonly checkedAt: number;
+  /** The newest published version seen, when the last success had one. */
+  readonly latest?: string;
+}
+
+export interface UpdateInput {
+  readonly current: string;
+  readonly now: number;
+  readonly cache: UpdateCache | null;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly offline: boolean;
+  /** Settings `updateCheck`; undefined means on. */
+  readonly enabled: boolean | undefined;
+  readonly install: InstallKind;
+}
+
+export interface UpdatePlan {
+  /** Ask the registry now. */
+  readonly check: boolean;
+  /** What to tell the person, if anything is newer. */
+  readonly notice?: string;
+}
+
+function truthy(value: string | undefined): boolean {
+  return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
+
+/** Reasons not to send a request at all, in the order they are checked. */
+export function updateDisabled(input: Pick<UpdateInput, "env" | "offline" | "enabled" | "install">): string | undefined {
+  if (input.install === "checkout") return "running from a source checkout";
+  if (input.offline || truthy(input.env["XENO_OFFLINE"])) return "offline";
+  if (input.enabled === false) return "updateCheck is off";
+  if (truthy(input.env["XENO_NO_UPDATE_CHECK"]) || truthy(input.env["NO_UPDATE_NOTIFIER"])) return "turned off by environment";
+  if (truthy(input.env["CI"]) || truthy(input.env["CONTINUOUS_INTEGRATION"])) return "running in CI";
+  return undefined;
+}
+
+export function updatePlan(input: UpdateInput): UpdatePlan {
+  if (updateDisabled(input)) return { check: false };
+  const due = !input.cache || !Number.isFinite(input.cache.checkedAt) || input.now - input.cache.checkedAt >= CHECK_INTERVAL_MS
+    || input.cache.checkedAt > input.now; // a clock set back must not silence checks for a year
+  const latest = input.cache?.latest;
+  return { check: due, ...(latest && isUpgrade(latest, input.current) ? { notice: updateNotice(latest, input.current, input.install) } : {}) };
+}
+
+export function upgradeCommand(install: InstallKind): string | undefined {
+  switch (install) {
+    case "bun": return `bun add -g ${PACKAGE_NAME}@latest`;
+    case "npm": return `npm i -g ${PACKAGE_NAME}@latest`;
+    case "other": case "checkout": return undefined;
+  }
+}
+
+/** Two lines: what is new, then the command on its own line so it can be copied whole. */
+export function updateNotice(latest: string, current: string, install: InstallKind): string {
+  const command = upgradeCommand(install);
+  return `xeno ${latest} is available (you have ${current})\n  ${command ?? "see docs/install.md to update"}`;
+}
+
+/**
+ * How this copy was installed, from where its package root really lives.
+ * Detected from the path rather than by running package managers, which
+ * costs seconds at startup (OpenCode runs up to seven list commands).
+ */
+export function installKind(packageRoot: string, hasGit: boolean): InstallKind {
+  const path = packageRoot.replaceAll("\\", "/");
+  if (hasGit || !path.includes("/node_modules/")) return "checkout";
+  if (path.includes("/.bun/install/global/")) return "bun";
+  if (path.includes("/lib/node_modules/") || /\/npm\/node_modules\//i.test(path)) return "npm";
+  return "other";
+}
+
+/** The registry's dist-tags for the package, honouring npm's registry setting. */
+export function distTagsUrl(registry: string | undefined): string {
+  const base = (registry && /^https?:\/\//.test(registry) ? registry : "https://registry.npmjs.org/").replace(/\/+$/, "");
+  return `${base}/-/package/${PACKAGE_NAME.replace("/", "%2f")}/dist-tags`;
+}