@visual-z/xeno 0.2.1 → 0.4.0

package/src/core/request-state.ts

@@ -0,0 +1,114 @@
+/** Q23 / D8 / D11: disposable request evidence, derived only from the selected log ancestry. */
+import type { LogEvent } from "./events.ts";
+import { deriveAcceptance, type AcceptanceState } from "./acceptance.ts";
+import { changedPaths } from "./checkpoints.ts";
+import { evidenceStale, isCommandResult, resolveEvidence } from "./evidence.ts";
+import { executionOutcome, modelOutcome, type ExecutionOutcome } from "./outcome.ts";
+import { deriveWorkItems, type WorkItem } from "./work-state.ts";
+import { deriveRequestProgress, type RequestProgress, type RequestRecord, type RequestSource } from "./request-progress.ts";
+
+export type RequestPart = { node: number; events: readonly LogEvent[] };
+export type RequestCommand = {
+  source: RequestSource; command: string; exit: number; status: "pass" | "fail" | "stale" | "superseded";
+  gate?: string; workspace_sha256?: string; workspace_scope?: "source-v1"; criteria: string[];
+};
+export type RequestArtifact = { source: RequestSource; path: string; sha256: string | null;
+  kind: "read" | "edit" | "checkpoint" | "command_output" };
+export type RequestState = {
+  request: RequestSource; inputs: RequestSource[];
+  status: "verified" | "awaiting_human" | "needs_work" | "blocked" | "unverified" | "not_applicable";
+  execution?: ExecutionOutcome; acceptance?: AcceptanceState;
+  commands: RequestCommand[]; artifacts: RequestArtifact[]; work: WorkItem[];
+  reported_blockers: { source: RequestSource; reason: string }[];
+  progress: RequestProgress;
+  changed: boolean; used_tools: boolean; reviewed: boolean;
+  final?: { source: RequestSource; text: string; has_tools: boolean };
+};
+
+/** New steering events refer to their original user event. Legacy users remain separate requests. */
+export function currentRequestRecords(parts: readonly RequestPart[]): RequestRecord[] {
+  const records = parts.flatMap(part => part.events.map(event => ({ node: part.node, event })));
+  const last = records.findLastIndex(({ event }) => event.t === "user");
+  if (last < 0) return [];
+  const user = records[last]!.event;
+  if (user.t !== "user") return [];
+  const start = user.request === undefined ? last : records.findIndex(({ event }) => event.t === "user" && event.id === user.request);
+  // Never reach through an unrelated user request because of an invalid reference.
+  if (start < 0 || records.slice(start + 1, last + 1).some(({ event }) => event.t === "user" && event.request !== user.request)) return records.slice(last);
+  return records.slice(start);
+}
+
+export function deriveRequestState(parts: readonly RequestPart[]): RequestState | undefined {
+  const records = currentRequestRecords(parts);
+  const first = records[0];
+  if (!first) return undefined;
+  const events = records.map(record => record.event);
+  const source = ({ node, event }: RequestRecord): RequestSource => ({ node, event: event.id });
+  const request = source(first);
+  const acceptance = deriveAcceptance(undefined, events.filter(event => event.t !== "acceptance_contract" || event.request === request.event));
+  const commands: RequestCommand[] = [], artifacts: RequestArtifact[] = [];
+  const lastCommands = new Map<string, string>();
+  for (const event of events) if (isCommandResult(event)) lastCommands.set(event.effect.cmd, event.id);
+  let work: WorkItem[] = [];
+  const ids = new Set(events.map(event => event.id)), completed = new Set<string>();
+  // Keep the existing work-item same-segment evidence contract (D11/O.2).
+  for (const part of parts) {
+    work = deriveWorkItems(work, part.events);
+    for (let index = 0; index < part.events.length; index++) {
+      const event = part.events[index]!;
+      // Legacy completed claims supersede a same-named blocker only when the
+      // original same-segment evidence resolves, just as in deriveHandoff.
+      if (event.t === "claim" && event.work_id === undefined && ids.has(event.id) &&
+          resolveEvidence(part.events.slice(0, index), event.evidence).ok) completed.add(event.what);
+    }
+  }
+  work = work.filter(item => ids.has(item.opened_at) || ids.has(item.updated_at));
+  const reported_blockers: RequestState["reported_blockers"] = [];
+  let execution: ExecutionOutcome | undefined, final: RequestState["final"], changed = false;
+  for (const record of records) {
+    const event = record.event, ref = source(record);
+    if (event.t === "user") { execution = undefined; final = undefined; }
+    else if (event.t === "assistant") {
+      final = { source: ref, text: event.blocks.flatMap(block => block.type === "text" ? [block.text] : []).join("\n").trim(),
+        has_tools: event.blocks.some(block => block.type === "tool_use") };
+      execution = final.has_tools ? undefined : modelOutcome(event.stop_reason ?? null);
+    } else if (event.t === "outcome") execution = { ...event.outcome };
+    else if (event.t === "interrupt") execution = executionOutcome("cancelled");
+    else if (event.t === "guidance" && (event.reason === "completion_review" || event.reason === "output_recovery")) execution = undefined;
+    if (event.t === "blocked" && (event.work_id ? work.some(item => item.id === event.work_id && item.status === "blocked") : !completed.has(event.what))) {
+      reported_blockers.push({ source: ref, reason: event.reason });
+    }
+    if (isCommandResult(event)) {
+      const effect = event.effect;
+      const evidence = { command: effect.cmd, exit: effect.exit, event_id: event.id, at: event.at,
+        ...(effect.workspace_sha256 === undefined ? {} : { workspace_sha256: effect.workspace_sha256 }),
+        ...(effect.workspace_scope === undefined ? {} : { workspace_scope: effect.workspace_scope }) };
+      commands.push({ source: ref, command: effect.cmd, exit: effect.exit,
+        status: !event.ok || effect.exit !== 0 ? "fail" : effect.workspace_observed === false || evidenceStale(events, evidence) ? "stale"
+          : lastCommands.get(effect.cmd) !== event.id ? "superseded" : "pass",
+        ...(effect.gate === undefined ? {} : { gate: effect.gate }),
+        ...(effect.workspace_sha256 === undefined ? {} : { workspace_sha256: effect.workspace_sha256 }),
+        ...(effect.workspace_scope === undefined ? {} : { workspace_scope: effect.workspace_scope }),
+        criteria: acceptance?.criteria.filter(item => item.kind === "command" && item.command === effect.cmd).map(item => item.id) ?? [] });
+      for (const output of effect.artifacts?.outputs ?? []) if (output.after.state === "observed") artifacts.push({
+        source: ref, path: output.path, sha256: output.after.sha256, kind: "command_output" });
+    } else if (event.t === "tool_result" && (event.effect?.kind === "read" || event.effect?.kind === "edit")) {
+      const effect = event.effect;
+      artifacts.push({ source: ref, path: effect.path, sha256: effect.kind === "read" ? effect.sha256 : effect.sha256_after, kind: effect.kind });
+      if (effect.kind === "edit" && effect.sha256_before !== effect.sha256_after) changed = true;
+    } else if (event.t === "checkpoint" && event.phase === "applied") {
+      for (const path of changedPaths(event.changes)) artifacts.push({ source: ref, path, sha256: event.changes[path]!.after?.sha256 ?? null, kind: "checkpoint" });
+      changed ||= changedPaths(event.changes).length > 0;
+    } else if (event.t === "workspace_observation") changed ||= event.changed;
+    else if (event.t === "snapshot") changed ||= Object.keys(event.added).length + Object.keys(event.changed).length + event.removed.length > 0;
+  }
+  return { request, inputs: records.filter(record => record.event.t === "user").map(source),
+    // Work notes can describe a later phase the user explicitly asked to defer.
+    // Only the declared request contract defines what must finish in this request.
+    status: reported_blockers.length ? "blocked" : acceptance?.status ?? "unverified",
+    ...(execution ? { execution } : {}), ...(acceptance ? { acceptance } : {}),
+    commands, artifacts, work, reported_blockers, progress: deriveRequestProgress(records), changed,
+    used_tools: events.some(event => event.t === "tool_result"),
+    reviewed: events.some(event => event.t === "guidance" && event.reason === "completion_review"),
+    ...(final ? { final } : {}) };
+}

package/src/core/runtime-target.ts

@@ -0,0 +1,94 @@
+/** R8: declarations select a target; only an owned runtime observation supplies its identity. */
+import { parseCommandArtifactPlan, validArtifactPath, type CommandArtifactPlan } from "./command-artifacts.ts";
+import type { ArtifactRef } from "./events.ts";
+import { isObservationArtifact } from "./observation-view.ts";
+import type { ProcessSource } from "./process-receipt.ts";
+
+export type RuntimeTarget = { id: string; build: string; artifacts: CommandArtifactPlan; entry: string;
+  interpreter?: string; args?: string[]; workdir?: string; port?: number };
+export type TargetBuild = { node: number; event: string; manifest: ArtifactRef };
+export type RuntimeInstance = { id: string; session: number; pid: number; source: ProcessSource;
+  entry: { path: string; sha256: string }; program: { path: string; sha256: string; device: string; inode: string } };
+export type RuntimeTargetReceipt = {
+  kind: "runtime_target"; version: 1; target: string; request: string; contract_event: string;
+  state: "ready" | "not_ready" | "stale" | "unknown"; reason: string; observed_at: string;
+  source: ProcessSource; build?: TargetBuild; instance?: RuntimeInstance; port?: number;
+  checks: { build: boolean; inputs: boolean; artifacts: boolean; process: boolean; image: boolean; port: boolean | null };
+  manifest?: ArtifactRef;
+};
+export type TargetAcceptance = { id: string; build: string; status: "not_run" | RuntimeTargetReceipt["state"];
+  observation?: string; binding?: string; session?: number; pid?: number; entry?: string; port?: number; build_event?: string; reason?: string };
+
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const id = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$/.test(value);
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const digest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const source = (value: unknown): value is ProcessSource => record(value) && ["host", "workspace", "cwd", "runtime"].every(key => text(value[key]));
+
+export function parseRuntimeTarget(value: unknown): RuntimeTarget {
+  if (!record(value) || Object.keys(value).some(key => !["id", "build", "artifacts", "entry", "interpreter", "args", "workdir", "port"].includes(key)) ||
+    !id(value["id"]) || !id(value["build"]) || !validArtifactPath(value["entry"])) throw Error("invalid runtime target declaration");
+  const artifacts = parseCommandArtifactPlan(value["artifacts"]);
+  if (!artifacts.paths.includes(value["entry"])) throw Error("target entry must be an observed build artifact");
+  const interpreter = value["interpreter"], args = value["args"], workdir = value["workdir"], port = value["port"];
+  if (interpreter !== undefined && (typeof interpreter !== "string" || !interpreter.startsWith("/") || /[\x00-\x1f\x7f]/.test(interpreter) || interpreter.length > 4096)) throw Error("target interpreter needs an explicit absolute path");
+  // Assumed argv budget prevents declarations from becoming an unbounded prompt or exec payload.
+  if (args !== undefined && (!Array.isArray(args) || args.length > 64 || !args.every(arg => typeof arg === "string" && !arg.includes("\0")) || JSON.stringify(args).length > 8192)) throw Error("target args must be a bounded literal string array");
+  if (workdir !== undefined && workdir !== "." && !validArtifactPath(workdir)) throw Error("target workdir must stay inside the workspace");
+  if (port !== undefined && (!natural(port) || port < 1 || port > 65535)) throw Error("target port must be 1..65535 on IPv4 loopback");
+  return { id: value["id"], build: value["build"], entry: value["entry"], artifacts,
+    ...(interpreter !== undefined ? { interpreter: interpreter as string } : {}), ...(args !== undefined ? { args: [...args as string[]] } : {}),
+    ...(workdir !== undefined ? { workdir: workdir as string } : {}), ...(port !== undefined ? { port: port as number } : {}) };
+}
+
+export function targetIsReady(receipt: Pick<RuntimeTargetReceipt, "build" | "instance" | "checks">): boolean {
+  return receipt.build !== undefined && receipt.instance !== undefined && receipt.checks.build && receipt.checks.inputs && receipt.checks.artifacts &&
+    receipt.checks.process && receipt.checks.image && receipt.checks.port !== false;
+}
+export function isRuntimeTargetReceipt(value: unknown): value is RuntimeTargetReceipt {
+  if (!record(value) || value["kind"] !== "runtime_target" || value["version"] !== 1 || !id(value["target"]) || !text(value["request"]) ||
+    !text(value["contract_event"]) || !text(value["observed_at"]) || !text(value["reason"]) || !source(value["source"]) ||
+    !["ready", "not_ready", "stale", "unknown"].includes(String(value["state"]))) return false;
+  const build = value["build"], instance = value["instance"], checks = value["checks"], port = value["port"];
+  if (build !== undefined && (!record(build) || !natural(build["node"]) || !text(build["event"]) || !isObservationArtifact(build["manifest"]))) return false;
+  if (instance !== undefined && (!record(instance) || !text(instance["id"]) || !natural(instance["session"]) || instance["session"] < 1 ||
+    !natural(instance["pid"]) || instance["pid"] < 1 || !source(instance["source"]) ||
+    !["host", "workspace", "cwd", "runtime"].every(key => (instance["source"] as Record<string, string>)[key] === (value["source"] as Record<string, string>)[key]) ||
+    !record(instance["entry"]) || !text(instance["entry"]["path"]) || !digest(instance["entry"]["sha256"]) ||
+    !record(instance["program"]) || !text(instance["program"]["path"]) || !digest(instance["program"]["sha256"]) ||
+    !text(instance["program"]["device"]) || !text(instance["program"]["inode"]))) return false;
+  if (!record(checks) || !["build", "inputs", "artifacts", "process", "image"].every(key => typeof checks[key] === "boolean") ||
+    !(checks["port"] === null || typeof checks["port"] === "boolean") ||
+    (port === undefined ? checks["port"] !== null : !natural(port) || port < 1 || port > 65535 || checks["port"] === null)) return false;
+  if (value["manifest"] !== undefined && !isObservationArtifact(value["manifest"])) return false;
+  return value["state"] !== "ready" || targetIsReady(value as RuntimeTargetReceipt) && isObservationArtifact(value["manifest"]);
+}
+
+/** lsof -F0 is a field protocol; matching a process name or display substring proves nothing. */
+export function lsofFiles(output: string, pid: number): Record<string, string>[] {
+  let process = -1, file: Record<string, string> | undefined;
+  const files: Record<string, string>[] = [];
+  for (const chunk of output.split("\0")) {
+    const field = chunk.replace(/^\n/, "");
+    if (!field) continue;
+    const key = field[0]!, value = field.slice(1);
+    if (key === "p") { process = Number(value); file = undefined; }
+    else if (key === "f") { file = { f: value }; if (process === pid) files.push(file); }
+    else if (file && process === pid) {
+      if (key === "T") { const split = value.indexOf("="); if (split > 0) file[`T${value.slice(0, split)}`] = value.slice(split + 1); }
+      else file[key] = value;
+    }
+  }
+  return files;
+}
+export function lsofOwnsImage(output: string, pid: number, device: string, inode: string): boolean {
+  return lsofFiles(output, pid).some(file => {
+    if (file["f"] !== "txt" || file["i"] !== inode || !/^0x[0-9a-f]+$/i.test(file["D"] ?? "")) return false;
+    try { return BigInt(file["D"]!) === BigInt(device); } catch { return false; }
+  });
+}
+export function lsofOwnsPort(output: string, pid: number, port: number): boolean {
+  return lsofFiles(output, pid).some(file => file["t"] === "IPv4" && file["P"] === "TCP" && file["TST"] === "LISTEN" &&
+    ["*", "127.0.0.1"].some(host => file["n"] === `${host}:${port}`));
+}

package/src/core/search-observation.ts

@@ -0,0 +1,97 @@
+/** R2: scan completeness and preview completeness answer different questions. */
+import { headTailSelection, isObservationArtifact, isBytePreview, type BytePreview } from "./observation-view.ts";
+import type { ArtifactRef } from "./events.ts";
+import { artifactRecovery } from "./prompt-policy.ts";
+
+export interface SearchRow { prefix: string; text: string; }
+export interface SearchScan {
+  status: "complete" | "partial" | "unknown";
+  reasons: { code: string; path?: string }[];
+  examined_files: number | null;
+  source_versions: "recorded" | "unknown";
+}
+export interface SearchObservation {
+  engine: "walk" | "ripgrep" | "fd" | "directory";
+  rows: SearchRow[];
+  scan: SearchScan;
+  sources: { path: string; sha256: string }[];
+  raw?: Uint8Array;
+  rawErrors?: Uint8Array;
+  limit: number;
+  empty: string;
+}
+
+export interface SearchReceipt {
+  kind: "search";
+  version: 1;
+  source: { host: string; workspace: string; resource: string };
+  engine: SearchObservation["engine"];
+  scan: { status: SearchScan["status"]; reasons: string[]; examined_files: number | null; source_versions: SearchScan["source_versions"] };
+  matches: number;
+  artifact: ArtifactRef;
+  manifest: ArtifactRef;
+  raw?: ArtifactRef;
+  raw_errors?: ArtifactRef;
+  preview: BytePreview;
+}
+
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function isSearchReceipt(value: unknown): value is SearchReceipt {
+  if (!object(value) || value["kind"] !== "search" || value["version"] !== 1 || !isObservationArtifact(value["artifact"]) || !isObservationArtifact(value["manifest"]) || !natural(value["matches"])) return false;
+  if (!["walk", "ripgrep", "fd", "directory"].includes(String(value["engine"])) || value["raw"] !== undefined && !isObservationArtifact(value["raw"])) return false;
+  if (value["raw_errors"] !== undefined && !isObservationArtifact(value["raw_errors"])) return false;
+  const source = value["source"], scan = value["scan"];
+  if (!object(source) || !["host", "workspace", "resource"].every(key => typeof source[key] === "string" && source[key] !== "")) return false;
+  if (!object(scan) || !["complete", "partial", "unknown"].includes(String(scan["status"])) || !["recorded", "unknown"].includes(String(scan["source_versions"])) ||
+    !Array.isArray(scan["reasons"]) || !scan["reasons"].every(reason => typeof reason === "string") || scan["examined_files"] !== null && !natural(scan["examined_files"])) return false;
+  if (scan["status"] === "complete" && scan["reasons"].length !== 0 || scan["status"] !== "complete" && scan["reasons"].length === 0) return false;
+  return isBytePreview(value["preview"], value["artifact"].bytes);
+}
+
+const encoder = new TextEncoder();
+const bytes = (text: string) => encoder.encode(text).length;
+export const searchObservationText = (rows: readonly SearchRow[]): string => rows.map(row => row.prefix + row.text).join("\n");
+
+/** Map count, per-line, and UTF-8 byte cuts back to the same immutable full observation. */
+export function previewSearchObservation(observation: SearchObservation, artifact: string, maxBytes: number, maxLineChars = 500, notice = "", tools?: readonly string[]) {
+  let text = "", source = 0, view = 0;
+  const spans: { view: number; source: number; bytes: number }[] = [];
+  const mapped = (value: string) => { const size = bytes(value); if (size) spans.push({ view, source, bytes: size }); text += value; view += size; };
+  const synthetic = (value: string) => { text += value; view += bytes(value); };
+  if (notice) synthetic(notice + "\n");
+  const shown = Math.max(0, Math.min(observation.rows.length, observation.limit));
+  for (let index = 0; index < observation.rows.length; index++) {
+    const row = observation.rows[index]!;
+    if (index < shown) {
+      let end = Math.min(maxLineChars, row.text.length);
+      if (end > 0 && end < row.text.length && /[\uD800-\uDBFF]/.test(row.text[end - 1]!)) end--;
+      const kept = row.prefix + row.text.slice(0, end);
+      mapped(kept);
+      if (end < row.text.length) synthetic(`… [line truncated; ${artifactRecovery(artifact, source + bytes(kept), tools)}]`);
+    }
+    source += bytes(row.prefix + row.text);
+    if (index < observation.rows.length - 1) { if (index < shown) mapped("\n"); source++; }
+  }
+  if (!observation.rows.length) synthetic(observation.scan.status === "complete" ? observation.empty : "[No matches observed in the scanned portion]");
+  if (shown < observation.rows.length) synthetic(`[${observation.rows.length - shown} more matches omitted; ${artifactRecovery(artifact, 0, tools)}]`);
+  if (observation.scan.status !== "complete") synthetic(`\n[scan ${observation.scan.status}: ${[...new Set(observation.scan.reasons.map(reason => reason.code === "match_timeout" ? "search cut off: match_timeout" : reason.code))].join(", ")}]`);
+  const previewBytes = encoder.encode(text);
+  const selected = headTailSelection(previewBytes, previewBytes, previewBytes.length, maxBytes,
+    omitted => `\n[truncated ${omitted} preview bytes; ${artifactRecovery(artifact, 0, tools)}]\n`);
+  const visible: [number, number][] = [];
+  for (const [lo, hi] of selected.visible) for (const span of spans) {
+    const begin = Math.max(lo, span.view), end = Math.min(hi, span.view + span.bytes);
+    if (end <= begin) continue;
+    const a = span.source + begin - span.view, b = span.source + end - span.view;
+    const last = visible.at(-1);
+    if (last?.[1] === a) last[1] = b;
+    else visible.push([a, b]);
+  }
+  let next = 0;
+  for (const [lo, hi] of visible) { if (lo !== next) break; next = hi; }
+  const full = encoder.encode(searchObservationText(observation.rows));
+  const semantic = visible.map(([lo, hi]) => new TextDecoder().decode(full.subarray(lo, hi))).join("");
+  return { text: selected.text, semantic, preview: { unit: "utf8_bytes" as const, complete: next === source,
+    visible, next_offset: next === source ? null : next } };
+}

package/src/core/session-tree.ts

@@ -0,0 +1,147 @@
+/**
+ * The session tree as data. Pure: restore points + parent pointers in,
+ * a forest out; plus a flattening that the UI and the line-mode printer
+ * share. Moved from src/tui/tree.ts when the view was rewritten (D20) so the
+ * shape of history does not depend on any renderer.
+ */
+
+/** Same mark /back uses for a branch the session rewound away from. */
+export const LEFT_BRANCH_MARK = "↩";
+export const EMPTY_TREE_MESSAGE = "nothing to go back to -- no exchange has completed yet";
+
+export type TreeKind = "user" | "other";
+export type TreeFilter = "user" | "default" | "no-tools" | "user-only" | "labeled-only" | "all";
+
+export interface TreeNode {
+  readonly id: string;
+  readonly prompt: string;
+  readonly onPath: boolean;
+  readonly current: boolean;
+  readonly kind: TreeKind;
+  readonly children: readonly TreeNode[];
+  readonly category?: "tool" | "message" | "metadata";
+  readonly label?: string;
+  readonly labelAt?: string;
+  readonly at?: string;
+  readonly content?: string;
+  /** Exact event position; user messages navigate before themselves. */
+  readonly target?: string;
+}
+
+/**
+ * A restore point as the log already knows it. parent pointers are a
+ * separate map so this file never imports store.
+ */
+export interface TreePoint {
+  readonly node: number;
+  readonly atEvent: string;
+  readonly prompt: string;
+  readonly onPath: boolean;
+  readonly kind?: TreeKind;
+  readonly category?: "tool" | "message" | "metadata";
+  readonly label?: string;
+  readonly labelAt?: string;
+  readonly at?: string;
+  readonly content?: string;
+  readonly target?: string;
+}
+
+export type NodeParent = { readonly node: number; readonly at_event?: string } | null;
+
+/**
+ * Restore points plus parent pointers → the tree the view paints.
+ *
+ * Same-node exchanges stay a chain. A child node whose parent.at_event
+ * matches a point hangs off that point as a sibling of the continuation,
+ * which is how a rewind becomes a visible fork instead of a missing row.
+ */
+export function treeFromPoints(
+  points: readonly TreePoint[],
+  parents: ReadonlyMap<number, NodeParent>,
+  currentNode: number,
+): TreeNode[] {
+  const byNode = new Map<number, TreePoint[]>();
+  for (const p of points) {
+    const list = byNode.get(p.node) ?? [];
+    list.push(p);
+    byNode.set(p.node, list);
+  }
+
+  const lastHere = [...points].reverse().find((p) => p.onPath && p.node === currentNode);
+  const lastOnPath = lastHere ?? [...points].reverse().find((p) => p.onPath);
+
+  function toNode(p: TreePoint, children: readonly TreeNode[]): TreeNode {
+    return {
+      ...p,
+      id: `${p.node}:${p.atEvent}`,
+      prompt: p.prompt,
+      onPath: p.onPath,
+      current: lastOnPath !== undefined && lastOnPath.node === p.node && lastOnPath.atEvent === p.atEvent,
+      kind: p.kind ?? "user",
+      children,
+    };
+  }
+
+  // Wire event chains and branch edges separately. Recursing once per event
+  // overflows the JS stack on otherwise valid long sessions.
+  type MutableNode = TreeNode & { children: TreeNode[] };
+  const chains = new Map<number, MutableNode[]>();
+  const events = new Map<string, MutableNode>();
+  for (const [id, pts] of byNode) {
+    const nodes = pts.map(p => toNode(p, []) as MutableNode);
+    for (let i = 0; i < nodes.length; i++) {
+      events.set(nodes[i]!.id, nodes[i]!);
+      if (nodes[i + 1]) nodes[i]!.children.push(nodes[i + 1]!);
+    }
+    chains.set(id, nodes);
+  }
+  const forest: TreeNode[] = [];
+  for (const [id, nodes] of [...chains].sort(([a], [b]) => a - b)) {
+    const first = nodes[0];
+    if (!first) continue;
+    let parent = parents.get(id);
+    const visited = new Set<number>([id]);
+    while (parent && !chains.get(parent.node)?.length && !visited.has(parent.node)) {
+      visited.add(parent.node); parent = parents.get(parent.node);
+    }
+    const anchor = parent && !visited.has(parent.node) ? events.get(`${parent.node}:${parent.at_event}`) ?? chains.get(parent.node)?.at(-1) : undefined;
+    if (anchor) anchor.children.push(first); else forest.push(first);
+  }
+  return forest;
+}
+
+
+export interface TreeRow { readonly node: TreeNode; readonly depth: number; readonly branch: string }
+
+/** Depth-first rows with connector prefixes; iterative so a 10k-event session cannot overflow the stack. */
+export function flattenTree(nodes: readonly TreeNode[], filter: TreeFilter = "all"): TreeRow[] {
+  const rows: TreeRow[] = [];
+  const stack = visibleTree(nodes, filter).map((node, i, all) => ({ node, prefix: "", root: true, last: i === all.length - 1 })).reverse();
+  while (stack.length) {
+    const { node, prefix, root, last } = stack.pop()!;
+    rows.push({ node, depth: prefix.length / 3, branch: root ? "" : prefix + (last ? "└─ " : "├─ ") });
+    const next = root ? "" : prefix + (last ? "   " : "│  ");
+    const children = node.children;
+    for (let i = children.length - 1; i >= 0; i--) stack.push({ node: children[i]!, prefix: next.length > 30 ? next.slice(-30) : next, root: false, last: i === children.length - 1 });
+  }
+  return rows;
+}
+
+/**
+ * Filtering hides a node but keeps its descendants: they re-attach to the
+ * nearest visible ancestor, so a "user only" view is still a tree.
+ */
+export function visibleTree(nodes: readonly TreeNode[], filter: TreeFilter): TreeNode[] {
+  if (filter === "all") return [...nodes];
+  const out: TreeNode[] = [];
+  const stack = [...nodes].reverse().map(node => ({ node, into: out }));
+  while (stack.length) {
+    const { node: n, into } = stack.pop()!;
+    const include = filter === "user" || filter === "user-only" ? n.kind === "user" :
+      filter === "labeled-only" ? Boolean(n.label) : filter === "no-tools" ? n.category !== "tool" && n.category !== "metadata" : n.category !== "metadata";
+    const children: TreeNode[] = [];
+    if (include) into.push({ ...n, children });
+    for (let i = n.children.length - 1; i >= 0; i--) stack.push({ node: n.children[i]!, into: include ? children : into });
+  }
+  return out;
+}

package/src/core/settings.ts

@@ -4,8 +4,12 @@ import { packageDeclaration, type PackageDeclaration } from "./packages.ts";
 /** Validated configuration. D19: display policy never mutates the log. */
 export interface Settings {
   readonly theme?: string;
+  /** Presentation only: no animation is allowed to advance a log or block input. */
+  readonly animations?: boolean;
   readonly thinking?: string;
   readonly statusBar?: boolean;
+  /** Look for a newer published xeno once a day and say so (docs/tasks/feat-update-check.md). Default on. */
+  readonly updateCheck?: boolean;
   readonly hideThinkingBlock?: boolean;
   readonly showCacheMissNotices?: boolean;
   readonly defaultProvider?: string;
@@ -13,9 +17,11 @@ export interface Settings {
   readonly defaultThinking?: string;
   readonly modelThinkingLevels?: Readonly<Record<string, ThinkingLevel>>;
   readonly scopedModels?: readonly string[];
+  /** provider/model keys, most recent first; the /model picker's first section. */
+  readonly recentModels?: readonly string[];
   readonly steeringMode?: "all" | "one-at-a-time";
   readonly followUpMode?: "all" | "one-at-a-time";
-  readonly tuiMode?: "regular" | "fullscreen";
+  readonly tuiMode?: "auto" | "regular" | "fullscreen";
   readonly fullscreenExitOutput?: "transcript" | "resume-hint";
   readonly fullscreenScrollbar?: "auto" | "always" | "hidden";
   readonly fullscreenCopyOnSelect?: boolean;
@@ -35,12 +41,14 @@ export interface Settings {
   readonly packages?: readonly PackageDeclaration[];
   readonly enableSkillCommands?: boolean;
   readonly defaultProjectTrust?: "ask" | "always" | "never";
-  readonly terminal?: { readonly clearOnShrink?: boolean; readonly showTerminalProgress?: boolean; readonly showImages?: boolean; readonly imageWidthCells?: number };
+  readonly terminal?: { readonly clearOnShrink?: boolean; readonly showTerminalProgress?: boolean; readonly showImages?: boolean; readonly imageWidthCells?: number;
+    /** How pictures are drawn; `auto` names them instead when the terminal can only draw block characters. */
+    readonly imageProtocol?: "auto" | "kitty" | "sixel" | "blocks" };
   readonly images?: { readonly autoResize?: boolean; readonly blockImages?: boolean };
   readonly markdown?: { readonly mermaid?: "off" | "final" | "streaming" };
 }
-export const SETTINGS_KEYS = ["theme", "thinking", "statusBar", "hideThinkingBlock", "showCacheMissNotices", "defaultProvider", "defaultModel", "defaultThinking",
-  "modelThinkingLevels", "scopedModels", "steeringMode", "followUpMode", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar",
+export const SETTINGS_KEYS = ["theme", "animations", "thinking", "statusBar", "updateCheck", "hideThinkingBlock", "showCacheMissNotices", "defaultProvider", "defaultModel", "defaultThinking",
+  "modelThinkingLevels", "scopedModels", "recentModels", "steeringMode", "followUpMode", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar",
   "fullscreenCopyOnSelect", "fullscreenWheelScrollLines", "editorPaddingX", "outputPad", "autocompleteMaxVisible",
   "showHardwareCursor", "quietStartup", "doubleEscapeAction", "treeFilterMode", "externalEditor", "terminal", "images", "markdown",
   "skills", "prompts", "themes", "extensions", "packages", "enableSkillCommands", "defaultProjectTrust"] as const;
@@ -52,11 +60,11 @@ type Rule = { readonly kind: "boolean" | "string" | "strings" } | { readonly kin
 const levels: Rule = { kind: "enum", values: THINKING_LEVELS };
 const delivery: Rule = { kind: "enum", values: ["all", "one-at-a-time"] };
 const rules: Readonly<Record<string, Rule>> = {
-  theme: { kind: "string" }, thinking: levels, statusBar: { kind: "boolean" },
+  theme: { kind: "string" }, animations: { kind: "boolean" }, thinking: levels, statusBar: { kind: "boolean" }, updateCheck: { kind: "boolean" },
   hideThinkingBlock: { kind: "boolean" }, showCacheMissNotices: { kind: "boolean" },
   defaultProvider: { kind: "string" }, defaultModel: { kind: "string" }, defaultThinking: levels,
-  scopedModels: { kind: "strings" }, steeringMode: delivery, followUpMode: delivery,
-  tuiMode: { kind: "enum", values: ["regular", "fullscreen"] },
+  scopedModels: { kind: "strings" }, recentModels: { kind: "strings" }, steeringMode: delivery, followUpMode: delivery,
+  tuiMode: { kind: "enum", values: ["auto", "regular", "fullscreen"] },
   fullscreenExitOutput: { kind: "enum", values: ["transcript", "resume-hint"] },
   fullscreenScrollbar: { kind: "enum", values: ["auto", "always", "hidden"] },
   fullscreenCopyOnSelect: { kind: "boolean" },
@@ -70,6 +78,7 @@ const rules: Readonly<Record<string, Rule>> = {
   externalEditor: { kind: "string" }, "terminal.clearOnShrink": { kind: "boolean" },
   "terminal.showTerminalProgress": { kind: "boolean" },
   "terminal.showImages": { kind: "boolean" }, "terminal.imageWidthCells": { kind: "integer", min: 1, max: 240 },
+  "terminal.imageProtocol": { kind: "enum", values: ["auto", "kitty", "sixel", "blocks"] },
   "images.autoResize": { kind: "boolean" }, "images.blockImages": { kind: "boolean" },
   "markdown.mermaid": { kind: "enum", values: ["off", "final", "streaming"] },
   skills: { kind: "strings" }, prompts: { kind: "strings" }, themes: { kind: "strings" }, extensions: { kind: "strings" },
@@ -77,19 +86,22 @@ const rules: Readonly<Record<string, Rule>> = {
 };
 /** One catalog supplies menu values and command validation. */
 export const DISPLAY_SETTINGS = [
+  { id: "animations", label: "Animations", fallback: "on" },
   { id: "hideThinkingBlock", label: "Hide thinking blocks", fallback: "on" },
   { id: "showCacheMissNotices", label: "Cache miss notices", fallback: "off" },
   { id: "enableSkillCommands", label: "Skill commands", fallback: "on" },
   { id: "defaultProjectTrust", label: "Default project trust", fallback: "ask" },
+  { id: "updateCheck", label: "Check for updates", fallback: "on" },
   { id: "terminal.showImages", label: "Show images", fallback: "on" },
+  { id: "terminal.imageProtocol", label: "Image protocol", fallback: "auto" },
   { id: "terminal.imageWidthCells", label: "Image width", fallback: "60" },
   { id: "images.autoResize", label: "Resize images", fallback: "on" },
   { id: "images.blockImages", label: "Block image transmission", fallback: "off" },
   { id: "markdown.mermaid", label: "Mermaid diagrams", fallback: "streaming" },
-  { id: "tuiMode", label: "TUI mode", fallback: "regular" },
+  { id: "tuiMode", label: "TUI mode", fallback: "fullscreen" },
   { id: "fullscreenExitOutput", label: "Fullscreen exit output", fallback: "transcript" },
-  { id: "fullscreenScrollbar", label: "Fullscreen scrollbar", fallback: "auto" },
-  { id: "fullscreenCopyOnSelect", label: "Fullscreen copy on select", fallback: "on" },
+  { id: "fullscreenScrollbar", label: "Fullscreen scrollbar", fallback: "hidden" },
+  { id: "fullscreenCopyOnSelect", label: "Copy on select", fallback: "on" },
   { id: "fullscreenWheelScrollLines", label: "Fullscreen wheel scroll lines", fallback: "auto" },
   { id: "editorPaddingX", label: "Editor padding", fallback: "0" },
   { id: "outputPad", label: "Output padding", fallback: "1" },
@@ -101,6 +113,13 @@ export const DISPLAY_SETTINGS = [
   { id: "terminal.clearOnShrink", label: "Clear on shrink", fallback: "off" },
   { id: "terminal.showTerminalProgress", label: "Terminal progress", fallback: "on" },
 ] as const;
+/** Only fields with a real picker may be suggested without a value. Raw config keys remain writable explicitly. */
+export function interactiveSettingKeys(): string[] {
+  const pickers = ["theme", "thinking", "defaultModel", "modelThinkingLevels"];
+  return [...new Set([...pickers, ...SETTINGS_KEYS, ...DISPLAY_SETTINGS.map(item => item.id)])]
+    .filter(key => pickers.includes(key) || settingValues(key).length > 0);
+}
+
 export function defaultSettings(): Settings { return { theme: "dark", thinking: "high", statusBar: true }; }
 export function mergeSettings(layers: SettingsLayers): Settings {
   const { defaultProjectTrust: _projectCannotGrantTrust, ...project } = layers.project ?? {};
@@ -166,6 +185,10 @@ function validate(key: string, raw: unknown, out: Record<string, unknown>, diagn
   else diagnostics.push("settings." + key + " must be " + (rule.kind === "enum" ? rule.values.join("|") : rule.kind === "integer" ? rule.min + ".." + rule.max + (rule.auto ? " or auto" : "") : rule.kind));
 }
 export function settingValues(key: string): string[] {
+  // `auto` is the unset default and stays valid in settings.json; cycling it in
+  // the menu would be a press that visibly does nothing on a terminal where
+  // auto already means fullscreen, so the menu toggles the two real screens.
+  if (key === "tuiMode") return ["regular", "fullscreen"];
   const rule = rules[key];
   if (rule?.kind === "enum") return [...rule.values];
   if (rule?.kind === "boolean") return ["on", "off"];