@visual-z/xeno 0.5.0 → 0.7.0

package/src/core/permissions.ts

@@ -19,6 +19,8 @@ export interface PermissionRequest {
   readonly tool: string;
   /** Exact command string for bash; omitted for tools that have none. */
   readonly command?: string;
+  /** Normalized workspace-relative or external absolute file resources. */
+  readonly paths?: readonly string[];
 }
 
 export interface PermissionRule {
@@ -27,6 +29,11 @@ export interface PermissionRule {
   readonly tool?: string;
   /** Absent matches every command. When set, matches only this exact string. */
   readonly command?: string;
+  /** Literal argv prefix, matched only for a single command without expansion. */
+  readonly commandPrefix?: readonly string[];
+  readonly path?: string;
+  /** Portable path glob: *, ?, and **; no brace or character-class expansion. */
+  readonly pathGlob?: string;
 }
 
 /**
@@ -39,6 +46,8 @@ export type ToolSource = "builtin" | "extension";
 /** Task capabilities are frozen once at session creation (O.7); not permissions. */
 export const TOOL_PROFILES = {
   coding: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note"],
+  // An explicit preset preserves the measured legacy ten-tool coding contract.
+  foundation: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "question", "apply_patch", "diff", "webfetch", "websearch", "format", "lsp"],
   readonly: ["read", "grep", "find", "history", "note"],
   research: ["read", "grep", "find", "history", "note", "branch", "resolve"],
   data: ["read", "grep", "find", "history", "note", "query"],
@@ -80,6 +89,11 @@ export const ALLOW_TOOLS_FLAG = "--allow-tools";
  */
 export function defaultRules(): readonly PermissionRule[] {
   return [
+    // Templates are ordinary source; actual environment values deserve the
+    // same last look as commands. Indirect readers also check read resources.
+    { action: "allow", tool: "read", pathGlob: "**/.env.example" },
+    { action: "ask", tool: "read", pathGlob: "**/.env" },
+    { action: "ask", tool: "read", pathGlob: "**/.env.*" },
     { action: "ask", tool: "bash" },
     // Same reach as bash. write_stdin needs no rule of its own: it can only
     // address a session exec_command already started, under this approval.
@@ -109,6 +123,12 @@ export function rulesWithAllowTools(
 export function ruleMatches(rule: PermissionRule, request: PermissionRequest): boolean {
   if (rule.tool !== undefined && rule.tool !== request.tool) return false;
   if (rule.command !== undefined && rule.command !== request.command) return false;
+  if (rule.commandPrefix !== undefined) {
+    const words = request.command === undefined ? null : literalCommandWords(request.command);
+    if (!words || rule.commandPrefix.length === 0 || rule.commandPrefix.some((word, i) => words[i] !== word)) return false;
+  }
+  if (rule.path !== undefined && !request.paths?.some(path => normalizePermissionPath(path) === normalizePermissionPath(rule.path!))) return false;
+  if (rule.pathGlob !== undefined && !request.paths?.some(path => permissionPathMatches(rule.pathGlob!, path))) return false;
   return true;
 }
 
@@ -121,12 +141,128 @@ export function decide(
   rules: readonly PermissionRule[],
   request: PermissionRequest,
 ): PermissionAction {
+  // A multi-file call needs every resource admitted. A broad allow for its
+  // first path must not conceal a denial on a later file (D13 / R13).
+  if (request.paths && request.paths.length > 1) {
+    const actions = request.paths.map(path => decide(rules, { ...request, paths: [path] }));
+    return actions.includes("deny") ? "deny" : actions.includes("ask") ? "ask" : "allow";
+  }
   for (const rule of rules) {
     if (ruleMatches(rule, request)) return rule.action;
   }
   return "allow";
 }
 
+/** Configured denial is a ceiling; in-memory approval can only resolve asks. */
+export function decideWithSessionRules(
+  configured: readonly PermissionRule[], remembered: readonly PermissionRule[], request: PermissionRequest,
+): PermissionAction {
+  if (decide(configured, request) === "deny") return "deny";
+  return decide([...remembered, ...configured], request);
+}
+
+/** Lexical normalization is pure; the store adds canonical symlink resources. */
+export function normalizePermissionPath(path: string): string {
+  const absolute = path.startsWith("/");
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") parts.pop();
+    else if (part === ".." && absolute) continue;
+    else parts.push(part);
+  }
+  return (absolute ? "/" : "") + parts.join("/") || ".";
+}
+
+/** Dynamic programming avoids exponential regexp backtracking on model input. */
+export function permissionPathMatches(pattern: string, path: string): boolean {
+  const glob = normalizePermissionPath(pattern), value = normalizePermissionPath(path);
+  let row = Array<boolean>(value.length + 1).fill(false); row[0] = true;
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i]!;
+    const next = Array<boolean>(value.length + 1).fill(false);
+    if (char === "*") {
+      const deep = glob[i + 1] === "*";
+      if (deep) i++;
+      // **/ also matches zero directories, as in **/.env at the root.
+      const directories = deep && glob[i + 1] === "/";
+      if (directories) i++;
+      next[0] = row[0]!;
+      for (let j = 1; j <= value.length; j++) {
+        next[j] = row[j]! || ((deep || value[j - 1] !== "/") && next[j - 1]!);
+        if (directories && value[j - 1] !== "/") next[j] = row[j]!;
+      }
+      // A globstar followed by slash may consume complete directories only.
+      if (directories) {
+        let reachable = row[0]!;
+        for (let j = 1; j <= value.length; j++) {
+          reachable = reachable || row[j]!;
+          next[j] = row[j]! || (value[j - 1] === "/" && reachable);
+        }
+      }
+    } else {
+      for (let j = 1; j <= value.length; j++) next[j] = row[j - 1]! &&
+        (char === "?" ? value[j - 1] !== "/" : char === value[j - 1]);
+    }
+    row = next;
+  }
+  return row[value.length]!;
+}
+
+/**
+ * This is a prefix matcher, never a command-danger classifier. Unknown shell
+ * syntax fails to match and therefore retains the full-command ask (D13).
+ */
+export function literalCommandWords(command: string): string[] | null {
+  const words: string[] = [];
+  let word = "", started = false, quote: "'" | '"' | null = null;
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i]!;
+    if (char === "\n" || char === "\r" || char === "\0") return null;
+    if (quote === "'") {
+      if (char === "'") quote = null; else word += char;
+      continue;
+    }
+    if (char === "\\") {
+      const escaped = command[++i];
+      if (escaped === undefined || escaped === "\n" || escaped === "\r") return null;
+      // Bash double quotes retain backslash before ordinary characters.
+      word += quote === '"' && !['$', '`', '"', "\\"].includes(escaped) ? `\\${escaped}` : escaped;
+      started = true; continue;
+    }
+    if (quote === '"') {
+      if (char === '"') quote = null;
+      else if (char === "$" || char === "`") return null;
+      else word += char;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; started = true; continue; }
+    if (char === " " || char === "\t") { if (started) words.push(word); word = ""; started = false; continue; }
+    if (";|&<>($`*?[]{}~#".includes(char)) return null;
+    word += char; started = true;
+  }
+  if (quote !== null) return null;
+  if (started) words.push(word);
+  return words.length ? words : null;
+}
+
+/** Unknown config keys are errors: a typo must not silently weaken a policy. */
+export function parsePermissionRule(value: unknown): PermissionRule {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error("permission rule must be an object");
+  const rule = value as Record<string, unknown>;
+  if (Object.keys(rule).some(key => !["action", "tool", "command", "commandPrefix", "path", "pathGlob"].includes(key))) throw Error("unknown permission rule field");
+  if (!["allow", "ask", "deny"].includes(String(rule["action"]))) throw Error("permission rule action must be allow, ask or deny");
+  for (const key of ["tool", "command", "path", "pathGlob"]) {
+    if (rule[key] !== undefined && (typeof rule[key] !== "string" || !String(rule[key]).trim() || String(rule[key]).includes("\0"))) throw Error(`permission ${key} must be a nonempty string`);
+  }
+  if (rule["path"] !== undefined && rule["pathGlob"] !== undefined) throw Error("permission path and pathGlob are mutually exclusive");
+  if (typeof rule["pathGlob"] === "string" && /[\[\]{}]/.test(rule["pathGlob"])) throw Error("permission pathGlob supports only *, ? and **");
+  const prefix = rule["commandPrefix"];
+  if (prefix !== undefined && (!Array.isArray(prefix) || prefix.length === 0 || prefix.some(word => typeof word !== "string" || !word || /[\r\n\0]/.test(word)))) throw Error("permission commandPrefix must contain literal argv tokens");
+  if (prefix !== undefined && rule["command"] !== undefined) throw Error("permission command and commandPrefix are mutually exclusive");
+  return structuredClone(value) as PermissionRule;
+}
+
 /**
  * Comma-separated flag values. Empty tokens are dropped so `--tools a,,b`
  * does not invent a blank name.
@@ -186,12 +322,15 @@ export function selectTools<T extends { name: string; source?: ToolSource }>(
 }
 
 export function permissionRequest(name: string, input: unknown): PermissionRequest {
-  if (!["bash", "exec_command", "environment"].includes(name) || typeof input !== "object" || input === null) {
+  if (typeof input !== "object" || input === null) {
     return { tool: name };
   }
-  const command = (input as { readonly [k: string]: unknown })[name === "exec_command" ? "cmd" : "command"];
-  if (typeof command !== "string") return { tool: name };
-  return { tool: name, command };
+  const fields = input as { readonly [k: string]: unknown };
+  const command = ["bash", "exec_command", "environment"].includes(name) ? fields[name === "exec_command" ? "cmd" : "command"] : undefined;
+  const paths = typeof fields["path"] === "string" ? [fields["path"]]
+    : Array.isArray(fields["paths"]) && fields["paths"].every(path => typeof path === "string") ? fields["paths"] as string[] : undefined;
+  return { tool: name, ...(typeof command === "string" ? { command } : {}),
+    ...(paths ? { paths: paths.map(normalizePermissionPath) } : {}) };
 }
 
 /**

package/src/core/progress.ts

@@ -5,6 +5,7 @@
  * its carried handoff view may be paged like the other structural state (D20).
  */
 import type { LineRange, LogEvent } from "./events.ts";
+import { isProcessReceipt } from "./process-receipt.ts";
 
 export type ProgressEvidence = (
   | { kind: "read"; sha256: string; ranges?: readonly LineRange[]; observation_sha256?: string }
@@ -123,6 +124,14 @@ export function deriveProgress(
         evidence.push({ kind: "observation", sha256: key, source });
         if (isAfter) progressed = true;
       }
+    } else if (isProcessReceipt(event.data) && !event.data.replayed && event.data.output !== undefined && event.data.output.bytes > 0 &&
+        !observations.has(event.data.output.sha256)) {
+      // A managed command can produce useful evidence before it exits. Credit
+      // raw captured bytes, never its elapsed header, changing ID or poll count.
+      const sha256 = event.data.output.sha256;
+      observations.add(sha256);
+      evidence.push({ kind: "observation", sha256, source });
+      progressed = true;
     } else if ((name === "grep" || name === "find" || name === "ls" || name === "query") &&
         observation !== undefined && (event.content_ref?.bytes ?? event.content.length) > 0 &&
         !observations.has(observation)) {

package/src/core/question.ts

@@ -0,0 +1,94 @@
+/** R13 / D11: an answer is bound to its original active invocation, never guessed. */
+
+// Product limits keep one interaction reviewable, not measured model limits.
+export const MAX_QUESTIONS = 3;
+export const MAX_QUESTION_CHOICES = 8;
+export interface QuestionChoice { readonly id: string; readonly label: string; readonly description?: string }
+export interface QuestionSpec {
+  readonly id: string;
+  readonly header: string;
+  readonly question: string;
+  readonly options: readonly QuestionChoice[];
+  readonly multiple: boolean;
+  readonly custom: boolean;
+}
+export interface QuestionRequest {
+  readonly request_id: string;
+  readonly turn_id: string;
+  readonly call_id: string;
+  readonly questions: readonly QuestionSpec[];
+}
+export interface QuestionAnswer { readonly id: string; readonly choices: readonly string[]; readonly text?: string }
+export interface QuestionReply {
+  readonly request_id: string;
+  readonly turn_id: string;
+  readonly answers: readonly QuestionAnswer[];
+}
+function object(value: unknown, label: string, fields: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error(`${label} must be an object`);
+  const result = value as Record<string, unknown>;
+  if (Object.keys(result).some(key => !fields.includes(key))) throw Error(`${label} contains an unknown field`);
+  return result;
+}
+function string(value: unknown, label: string, max = 2000): string {
+  if (typeof value !== "string" || !value.trim() || value.length > max || /[\0\x1b]/.test(value)) throw Error(`${label} must be nonempty plain text (max ${max} characters)`);
+  return value;
+}
+function identifier(value: unknown, label: string): string {
+  const id = string(value, label, 64);
+  if (!/^[a-z][a-z0-9_-]*$/.test(id)) throw Error(`${label} must be a stable lowercase identifier`);
+  return id;
+}
+
+export function parseQuestions(value: unknown): QuestionSpec[] {
+  const input = object(value, "question input", ["questions"]);
+  const questions = input["questions"];
+  if (!Array.isArray(questions) || questions.length < 1 || questions.length > MAX_QUESTIONS) throw Error(`question requires 1..${MAX_QUESTIONS} questions`);
+  const parsed = questions.map(value => {
+    const item = object(value, "question", ["id", "header", "question", "options", "multiple", "custom"]);
+    const options = item["options"] ?? [];
+    if (!Array.isArray(options) || options.length > MAX_QUESTION_CHOICES) throw Error(`question options must contain at most ${MAX_QUESTION_CHOICES} choices`);
+    const choices = options.map(value => {
+      const choice = object(value, "question option", ["id", "label", "description"]);
+      return { id: identifier(choice["id"], "option id"), label: string(choice["label"], "option label", 120),
+        ...(choice["description"] !== undefined ? { description: string(choice["description"], "option description", 600) } : {}) };
+    });
+    if (new Set(choices.map(choice => choice.id)).size !== choices.length) throw Error("question option ids must be unique");
+    if (new Set(choices.map(choice => choice.label)).size !== choices.length) throw Error("question option labels must be unique");
+    for (const key of ["multiple", "custom"]) if (item[key] !== undefined && typeof item[key] !== "boolean") throw Error(`question ${key} must be boolean`);
+    const multiple = item["multiple"] === true, custom = item["custom"] !== false;
+    if (!choices.length && !custom) throw Error("question must offer choices or custom text");
+    return { id: identifier(item["id"], "question id"), header: string(item["header"], "question header", 40),
+      question: string(item["question"], "question text"), options: choices, multiple, custom };
+  });
+  if (new Set(parsed.map(question => question.id)).size !== parsed.length) throw Error("question ids must be unique");
+  return parsed;
+}
+
+export function questionRequest(turnId: string, callId: string, questions: readonly QuestionSpec[]): QuestionRequest {
+  if (!turnId || !callId || /[\r\n\0]/.test(turnId + callId)) throw Error("question requires a trusted active turn and call identity");
+  // Tuple encoding avoids slash/delimiter collisions in opaque runtime IDs.
+  return { request_id: JSON.stringify([turnId, callId]), turn_id: turnId, call_id: callId, questions: structuredClone(questions) };
+}
+
+export function validateQuestionReply(request: QuestionRequest, value: unknown): QuestionReply {
+  const reply = object(value, "question reply", ["request_id", "turn_id", "answers"]);
+  if (reply["request_id"] !== request.request_id || reply["turn_id"] !== request.turn_id) throw Error("question reply belongs to a different invocation or turn");
+  const answers = reply["answers"];
+  if (!Array.isArray(answers) || answers.length !== request.questions.length) throw Error("question reply must answer every question exactly once");
+  const parsed = answers.map(value => {
+    const answer = object(value, "question answer", ["id", "choices", "text"]);
+    const id = identifier(answer["id"], "answer id"), question = request.questions.find(question => question.id === id);
+    if (!question) throw Error("question reply contains an unknown question id");
+    const choices = answer["choices"];
+    if (!Array.isArray(choices) || choices.some(choice => typeof choice !== "string" || !question.options.some(option => option.id === choice)) || new Set(choices).size !== choices.length) throw Error("question reply contains unknown or duplicate choices");
+    const text = answer["text"] === undefined ? undefined : string(answer["text"], "answer text", 10000);
+    if (text !== undefined && !question.custom) throw Error("custom text is not permitted for this question");
+    const count = choices.length + (text === undefined ? 0 : 1);
+    if (count === 0 || (!question.multiple && count !== 1)) throw Error("question reply requires one answer, or multiple only when enabled");
+    return { id, choices: [...choices] as string[], ...(text !== undefined ? { text } : {}) };
+  });
+  if (new Set(parsed.map(answer => answer.id)).size !== parsed.length) throw Error("question reply contains duplicate question ids");
+  return { request_id: request.request_id, turn_id: request.turn_id,
+    answers: request.questions.map(question => parsed.find(answer => answer.id === question.id)!) };
+}

package/src/core/request-budget.ts

@@ -0,0 +1,13 @@
+/** D6 / Q.26: finalization spends the existing budget and cannot admit new work. */
+export function requestPhase(index: number, limit: number): "work" | "finalize" | "exhausted" {
+  if (!Number.isSafeInteger(limit) || limit < 1 || !Number.isSafeInteger(index) || index < 0)
+    throw new RangeError("request budget requires positive integer limit and nonnegative index");
+  if (index >= limit) return "exhausted";
+  // One request cannot both investigate and close. Preserve that work opportunity;
+  // its deterministic outcome is the exit, without a second paid request.
+  return limit > 1 && index === limit - 1 ? "finalize" : "work";
+}
+
+export function finalizationNotice(): string {
+  return "Harness: this is the final request in the existing budget. Tools are disabled by the host. Give the user a concise answer from the observations already recorded: what is established, what remains unresolved, and the next useful action. Do not claim unobserved execution or verified completion.";
+}

package/src/core/review.ts

@@ -0,0 +1,68 @@
+/** Review scopes and checkpoint projection are data, never authorization (D8 / D11). */
+import type { LogEvent } from "./events.ts";
+import { sameVersion, changedPaths, type FileChanges } from "./checkpoints.ts";
+export type ReviewScope = { kind: "working" } | { kind: "branch"; base: string } |
+  { kind: "commit"; commit: string } | { kind: "last-turn" };
+export interface ReviewSnapshot {
+  scope: ReviewScope;
+  label: string;
+  diff: string;
+  paths: string[];
+  limitations: string[];
+  /** Resolved commits are immutable review premises, never raw shell expressions. */
+  base?: string;
+}
+
+/** Fold observed operations after the latest request; uncaptured effects remain unknown. */
+export function lastTurnChanges(events: readonly LogEvent[]): { changes: FileChanges; limitations: string[] } {
+  let start = 0;
+  for (let i = events.length - 1; i >= 0; i--) if (events[i]!.t === "user" || events[i]!.t === "user_bash") { start = i + 1; break; }
+  const changes: FileChanges = Object.create(null) as FileChanges;
+  const limitations = new Set<string>(["Last-turn diff covers durable file checkpoints; uncaptured command or external changes are unknown."]);
+  const suffix = events.slice(start);
+  const finalPhases = new Map(suffix.filter(event => event.t === "checkpoint").map(event => [event.operation, event.phase]));
+  for (const event of suffix) {
+    if (event.t !== "checkpoint") continue;
+    if (event.phase === "unavailable" && finalPhases.get(event.operation) !== "applied") limitations.add(event.reason ?? "A file checkpoint is unavailable.");
+    if (event.phase !== "applied" || finalPhases.get(event.operation) !== "applied") continue;
+    for (const path of changedPaths(event.changes)) {
+      const next = event.changes[path]!, previous = changes[path];
+      if (previous && !sameVersion(previous.after, next.before)) throw new Error(`discontinuous last-turn checkpoint: ${path}; external changes cannot be attributed`);
+      changes[path] = { before: previous ? previous.before : next.before, after: next.after };
+    }
+  }
+  return { changes: Object.fromEntries(changedPaths(changes).map(path => [path, changes[path]!])), limitations: [...limitations] };
+}
+
+/** A linear contiguous hunk avoids quadratic whole-file diff memory. No bytes are omitted. */
+export function unifiedFileDiff(path: string, before: string | null, after: string | null, destination = path): string {
+  if (before === after && path === destination) return "";
+  const lines = (text: string | null): { text: string; newline: boolean }[] => {
+    if (!text) return [];
+    const result = text.split("\n");
+    if (text.endsWith("\n")) result.pop();
+    return result.map((line, index) => ({ text: line, newline: index < result.length - 1 || text.endsWith("\n") }));
+  };
+  const oldLines = lines(before), newLines = lines(after);
+  const equal = (left: typeof oldLines[number] | undefined, right: typeof oldLines[number] | undefined) =>
+    left !== undefined && right !== undefined && left.text === right.text && left.newline === right.newline;
+  let prefix = 0, suffix = 0;
+  while (prefix < oldLines.length && prefix < newLines.length && equal(oldLines[prefix], newLines[prefix])) prefix++;
+  while (suffix < oldLines.length - prefix && suffix < newLines.length - prefix && equal(oldLines.at(-suffix - 1), newLines.at(-suffix - 1))) suffix++;
+  // Assumed familiar Git default: retain three lines of unchanged context per side.
+  const start = Math.max(0, prefix - 3), oldEnd = Math.min(oldLines.length, oldLines.length - suffix + 3), newEnd = Math.min(newLines.length, newLines.length - suffix + 3);
+  const quoted = (value: string) => /[\s"\\]/.test(value) ? JSON.stringify(value) : value;
+  const emit = (entries: typeof oldLines, marker: string) => entries.flatMap(line =>
+    [marker + line.text, ...(line.newline ? [] : ["\"])]);
+  const body = [...emit(oldLines.slice(start, prefix), " "),
+    ...emit(oldLines.slice(prefix, oldLines.length - suffix), "-"),
+    ...emit(newLines.slice(prefix, newLines.length - suffix), "+"),
+    ...emit(oldLines.slice(oldLines.length - suffix, oldEnd), " ")];
+  const range = (count: number) => count ? start + 1 : 0;
+  const oldCount = oldEnd - start, newCount = newEnd - start;
+  const headers = [`diff --git ${quoted("a/" + path)} ${quoted("b/" + destination)}`,
+    ...(path === destination ? [] : [`rename from ${quoted(path)}`, `rename to ${quoted(destination)}`]),
+    `--- ${before === null ? "/dev/null" : quoted("a/" + path)}`, `+++ ${after === null ? "/dev/null" : quoted("b/" + destination)}`];
+  if (body.length) headers.push(`@@ -${range(oldCount)},${oldCount} +${range(newCount)},${newCount} @@`, ...body);
+  return headers.join("\n") + "\n";
+}

package/src/core/session-exit.ts

@@ -0,0 +1,26 @@
+/** D8 / D11: terminal exit is a bounded projection of execution facts, never a replay. */
+import type { LogEvent } from "./events.ts";
+import { pendingToolCalls } from "./execution.ts";
+import { modelOutcome } from "./outcome.ts";
+
+export const DEFAULT_FULLSCREEN_EXIT_OUTPUT = "resume-hint";
+
+/** Terminal controls and arbitrarily large reason text do not own the shell surface. */
+export function exitLine(text: string, limit = 180): string {
+  return text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim().slice(0, limit);
+}
+
+export function sessionExitStatus(events: readonly LogEvent[]): string {
+  const start = events.findLastIndex(event => event.t === "user");
+  const current = events.slice(Math.max(0, start));
+  const outcome = current.findLast(event => event.t === "outcome" || event.t === "user_bash");
+  if (outcome?.t === "outcome") return exitLine(`${outcome.outcome.status} · ${outcome.outcome.reason} · ${outcome.reason}`);
+  if (outcome?.t === "user_bash") return `${outcome.outcome.status} · ${outcome.outcome.reason} · command exit ${outcome.exit}`;
+  if (current.some(event => event.t === "interrupt")) return "cancelled · user interrupted";
+  const assistant = current.findLast(event => event.t === "assistant");
+  if (assistant?.t === "assistant" && !assistant.blocks.some(block => block.type === "tool_use") && pendingToolCalls(current).length === 0) {
+    const result = modelOutcome(assistant.stop_reason ?? null);
+    return result.reason === "model_end" ? "model finished · verification remains in session evidence" : `${result.status} · ${result.reason}`;
+  }
+  return start < 0 ? "session saved" : "unfinished · inspect recorded receipts before continuing";
+}

package/src/core/settings.ts

@@ -99,7 +99,7 @@ export const DISPLAY_SETTINGS = [
   { id: "images.blockImages", label: "Block image transmission", fallback: "off" },
   { id: "markdown.mermaid", label: "Mermaid diagrams", fallback: "streaming" },
   { id: "tuiMode", label: "TUI mode", fallback: "fullscreen" },
-  { id: "fullscreenExitOutput", label: "Fullscreen exit output", fallback: "transcript" },
+  { id: "fullscreenExitOutput", label: "Fullscreen exit output", fallback: "resume-hint" },
   { id: "fullscreenScrollbar", label: "Fullscreen scrollbar", fallback: "hidden" },
   { id: "fullscreenCopyOnSelect", label: "Copy on select", fallback: "on" },
   { id: "fullscreenWheelScrollLines", label: "Fullscreen wheel scroll lines", fallback: "auto" },

package/src/core/stall.ts

@@ -3,6 +3,7 @@ import type { LogEvent } from "./events.ts";
 import { pendingToolCalls } from "./execution.ts";
 import { exchangeProgressChecks } from "./evidence.ts";
 import { deriveProgress, type ProgressEvidence } from "./progress.ts";
+import { isProcessReceipt } from "./process-receipt.ts";
 
 // A conservative hypothesis: enough room to change method after a mid-budget
 // notice, while bounding repeated paid requests. Not a task-quality classifier.
@@ -12,18 +13,27 @@ export interface StallState {
   pending: readonly LogEvent[];
   pendingNode: number;
   consecutive: number;
+  unproductive: number;
+  failures: number;
+  emptyWaits: number;
   warned: boolean;
 }
 export function emptyStallState(): StallState {
-  return { evidence: [], pending: [], pendingNode: 0, consecutive: 0, warned: false };
+  return { evidence: [], pending: [], pendingNode: 0, consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false };
 }
 export function finishStallExchange(state: StallState): StallState {
   const assistant = state.pending[0];
   if (assistant?.t !== "assistant" || pendingToolCalls(state.pending).length > 0) return state;
   if (!assistant.blocks.some((block) => block.type === "tool_use")) return { ...state, pending: [] };
   const progress = deriveProgress(state.evidence, state.pending, state.pendingNode, exchangeProgressChecks(state.pending));
+  const results = state.pending.filter(event => event.t === "tool_result");
+  const waits = new Set(assistant.blocks.flatMap(block => block.type === "tool_use" && block.name === "write_stdin" ? [block.call_id] : []));
   return { ...state, pending: [], evidence: progress.evidence,
-    consecutive: progress.progressed ? 0 : state.consecutive + 1, warned: progress.progressed ? false : state.warned };
+    consecutive: progress.progressed ? 0 : state.consecutive + 1,
+    unproductive: state.unproductive + (progress.progressed ? 0 : 1),
+    failures: state.failures + results.filter(result => !result.ok).length,
+    emptyWaits: state.emptyWaits + results.filter(result => waits.has(result.call_id) && isProcessReceipt(result.data) &&
+      result.data.running === true && result.data.cursor !== undefined && result.data.cursor.start === result.data.cursor.end).length };
 }
 
 /** Fold original events, never the retained projection where evidence can repeat. */
@@ -32,7 +42,7 @@ export function advanceStall(state: StallState, entries: readonly { node: number
   for (const { node, event } of entries) {
     if (event.t === "assistant" || event.t === "user" || event.t === "cut" || (event.t === "guidance" && event.reason === "stall")) {
       result = finishStallExchange(result);
-      if (event.t === "user") result = { ...result, pending: [], consecutive: 0, warned: false };
+      if (event.t === "user") result = { ...result, pending: [], consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false };
       if (event.t === "assistant") result = { ...result, pending: [event], pendingNode: node };
       if (event.t === "guidance") result = { ...result, warned: true };
     } else if (result.pending.length > 0) result = { ...result, pending: [...result.pending, event] };
@@ -42,7 +52,9 @@ export function advanceStall(state: StallState, entries: readonly { node: number
 export function stallDecision(state: StallState, limit: number) {
   if (!Number.isSafeInteger(limit) || limit < 0 || limit === 1) throw new RangeError("stall limit must be zero or an integer of at least two");
   const current = finishStallExchange(state);
-  return { consecutive: current.consecutive,
-    stop: limit > 0 && current.consecutive >= limit,
-    warn: limit > 0 && current.consecutive >= Math.max(1, Math.floor(limit / 2)) && !current.warned };
+  // Reuse the existing conservative allowance. Novelty resets a streak, not
+  // the request's spent no-progress budget (research Q.26); failures are diagnostics.
+  return { consecutive: current.consecutive, unproductive: current.unproductive, failures: current.failures, emptyWaits: current.emptyWaits,
+    stop: limit > 0 && (current.consecutive >= limit || current.unproductive >= limit),
+    warn: limit > 0 && current.unproductive >= Math.max(1, Math.floor(limit / 2)) && !current.warned };
 }

package/src/core/stop-report.ts

@@ -0,0 +1,25 @@
+/** D8 / D11: summarize termination mechanically; assistant claims never become receipts. */
+import type { LogEvent } from "./events.ts";
+import { isProcessReceipt, latestProcessReceipt } from "./process-receipt.ts";
+import { exitLine } from "./session-exit.ts";
+
+export function stopReport(events: readonly LogEvent[], requests: number, limit: number, cause: string): string {
+  const start = events.findLastIndex(event => event.t === "user" && event.request === undefined);
+  const current = events.slice(Math.max(0, start));
+  const results = current.filter(event => event.t === "tool_result");
+  const failures = results.filter(event => !event.ok);
+  const exits = results.filter(event => event.effect?.kind === "command" && event.effect.exit === 0).length;
+  const ids = new Set<number>();
+  for (const event of current) {
+    if (event.t === "tool_result" && isProcessReceipt(event.data)) ids.add(event.data.session_id);
+    if (event.t === "process_exit") ids.add(event.session);
+  }
+  const running = [...ids].filter(id => latestProcessReceipt([{ node: 0, events: current }], id)?.receipt.running === true);
+  return [
+    `Stopped: ${exitLine(cause)} (${requests}/${limit} model requests).`,
+    `Recorded evidence: ${results.length} tool receipts; ${exits} successful command exits; ${failures.length} failed tool receipts. Task completion is not verified by this stop.`,
+    ...(failures.length ? [`Inspect failed receipts: ${failures.slice(-3).map(event => exitLine(event.id, 80)).join(", ")}.`] : []),
+    ...(running.length ? [`Last observed running: ${running.slice(0, 3).join(", ")}${running.length > 3 ? ` (+${running.length - 3})` : ""}; inspect the process receipt before replaying a command.`] : []),
+    "Next: inspect /state or the recorded tool output, then provide a focused continuation; completed commands should not be replayed just to recover their output.",
+  ].join("\n");
+}

package/src/core/update-check.ts

@@ -2,13 +2,14 @@
  * 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
+ * runs it. Automatic checks run at most once a day, recorded even when they fail,
+ * and no automatic requests 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.
+ * plain function of its inputs. Explicit checks bypass automatic scheduling
+ * and opt-outs, while retaining the offline and source-checkout boundaries.
  */
-import { isUpgrade } from "./version.ts";
+import { compareVersions, isUpgrade, parseVersion } from "./version.ts";
 
 export const PACKAGE_NAME = "@visual-z/xeno";
 /** One request a day, like update-notifier; Codex uses 20 hours. Assumed. */
@@ -32,6 +33,8 @@ export interface UpdateInput {
   /** Settings `updateCheck`; undefined means on. */
   readonly enabled: boolean | undefined;
   readonly install: InstallKind;
+  /** Explicit checks bypass only automatic scheduling and opt-outs (D16 manual-check extension). */
+  readonly manual?: boolean;
 }
 
 export interface UpdatePlan {
@@ -46,9 +49,10 @@ function truthy(value: string | undefined): boolean {
 }
 
 /** 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 {
+export function updateDisabled(input: Pick<UpdateInput, "env" | "offline" | "enabled" | "install" | "manual">): string | undefined {
   if (input.install === "checkout") return "running from a source checkout";
   if (input.offline || truthy(input.env["XENO_OFFLINE"])) return "offline";
+  if (input.manual) return undefined;
   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";
@@ -57,6 +61,7 @@ export function updateDisabled(input: Pick<UpdateInput, "env" | "offline" | "ena
 
 export function updatePlan(input: UpdateInput): UpdatePlan {
   if (updateDisabled(input)) return { check: false };
+  if (input.manual) return { check: true };
   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;
@@ -77,6 +82,20 @@ export function updateNotice(latest: string, current: string, install: InstallKi
   return `xeno ${latest} is available (you have ${current})\n  ${command ?? "see docs/install.md to update"}`;
 }
 
+/** A manual result describes this request, never an older cached answer. */
+export function manualUpdateResult(latest: string | null, current: string, install: InstallKind): {
+  readonly status: "available" | "current" | "ahead" | "ineligible" | "failed";
+  readonly text: string;
+} {
+  const next = latest === null ? null : parseVersion(latest), now = parseVersion(current);
+  if (!next || !now || latest === null) return { status: "failed", text: `Could not check for xeno updates (current ${current}). Check your connection or registry setting and try again.` };
+  if (isUpgrade(latest, current)) return { status: "available", text: updateNotice(latest, current, install) };
+  const order = compareVersions(next, now);
+  if (order === 0) return { status: "current", text: `xeno is up to date (${current}).` };
+  if (order < 0) return { status: "ahead", text: `xeno ${current} is newer than the registry's latest release (${latest}).` };
+  return { status: "ineligible", text: `No newer stable xeno release is available (current ${current}; registry latest ${latest}).` };
+}
+
 /**
  * How this copy was installed, from where its package root really lives.
  * Detected from the path rather than by running package managers, which