@visual-z/xeno 0.1.0

package/src/apps/startup.ts

@@ -0,0 +1,1302 @@
+import { release } from "node:os";
+import { workingProtocol } from "../core/continuation.ts";
+import { environmentSection, type SessionEnvironment } from "../core/environment.ts";
+/**
+ * From argv to a session that can run. Credential order, model selection,
+ * --fresh and the leftover-log notice all live here so the CLI entry can
+ * stay a few calls -- and so those rules can be tested without starting
+ * a REPL.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { Session, systemClock } from "../runtime/loop.ts";
+import { DEFAULT_PROVIDER, type ProviderConfig } from "../runtime/provider.ts";
+import { createProvider, selectModel, loadCatalog, groupedModels, parseUserCatalog, type CatalogFetch } from "../runtime/catalog.ts";
+import { CATALOG, outputTokenBudget, type Effort, type ModelSpec } from "../runtime/model.ts";
+import {
+  resolveCredential, envLabel, storedIsOAuth,
+  type AuthFile, type ResolveEffects, type Resolved, describeMissingCredential } from "../runtime/auth.ts";
+import { authPath, configDir, readJsonFile } from "../store/config.ts";
+import { loadUiResources, loadTextResources, type UiResources } from "../store/resources.ts";
+import { appendSkillsToSystem } from "../core/skills.ts";
+import { resolveSlashCatalog, type SlashCatalog } from "./commands.ts";
+import { createStyle, IDENTITY, type Style } from "../tui/style.ts";
+import type { Settings } from "../core/settings.ts";
+import { readModelsText, writeModelsFile, modelsPath } from "../store/models.ts";
+import { refreshRemoteCatalog } from "../runtime/models-fetch.ts";
+import { readCursor, writeCursor, type Cursor } from "../store/log.ts";
+import {
+  copyAncestryTo, createSession, findSessionByPrefix, resolveLogDir,
+} from "../store/sessions.ts";
+import { loadContext, assembleSystemPrompt, formatNotice, type LoadedContext } from "../store/context-files.ts";
+import {
+  lookupTrust, projectSettingsPath, readTrust,
+} from "../store/trust.ts";
+import { stat } from "node:fs/promises";
+import {
+  parseToolList, rulesWithAllowTools, selectTools,
+  type PermissionRequest, type PermissionRule,
+} from "../core/permissions.ts";
+import {
+  TOOL_SCHEMAS, DEFAULT_TOOL_CONTEXT, workspaceRoot,
+  type ApprovalChoice, type ToolContext,
+} from "../runtime/tools.ts";
+import { DEFAULT_BOUNDARY } from "../core/boundary.ts";
+import { DEFAULT_CONTEXT_POLICY, isContextPolicy, type ContextPolicy } from "../core/context-policy.ts";
+import { windowBudget } from "../core/context-window.ts";
+import { colorEnabled, createPalette, describeError, stdinIsTty, stdoutIsTty, type Palette } from "./render.ts";
+import { type ActionId, type Keymap } from "../core/keymap.ts";
+
+export const SYSTEM_PROMPT = systemPromptFor(TOOL_SCHEMAS.map((tool) => tool.name));
+
+/**
+ * The instructions mention only tools the model can actually see. Naming a
+ * tool that was excluded from the schema teaches it to call something that
+ * will never work. The default prompt is left alone when every tool is visible.
+ */
+export function systemPromptFor(toolNames: readonly string[], env?: SessionEnvironment): string {
+  const has = (name: string) => toolNames.includes(name);
+  const toolsLine = toolNames.length === 0
+    ? "No tools are available in this session."
+    : `Tools: ${toolNames.join(", ")}.` +
+      (toolNames.some(name => ["grep", "find", "ls"].includes(name)) ? " Use the available grep/find/ls tools for confined search." : "") +
+      (has("bash")
+        ? " Use bash for verification commands and operations the other tools do not cover."
+        : "");
+
+  // Each line answers a failure class in the Terminal-Bench taxonomy
+  // (arXiv 2601.11868): premature termination, no verification, step
+  // repetition. The wording of the first and last follows the Codex
+  // prompting guide: persist end to end, and end on a change or a blocker.
+  const work = [
+    "How to work:",
+    "- Keep going until the request is fully resolved. When a reasonable assumption lets you proceed, make it and mention it at the end; stop to ask only when blocked on a decision only the user can make.",
+    "- Understand before changing: read the relevant code, and for a bug, reproduce it first.",
+    "- Put independent reads and searches in one response; they run in parallel.",
+    "- After a change, run the project's own tests, build or type check. When a command fails, read the end of its output first; errors and summaries are printed last.",
+    "- If the same approach fails twice, change the approach instead of retrying it.",
+    "- A claim without a passing command is not evidence. Finish with what changed and the command that verified it, or the specific blocker.",
+  ];
+  if (has("bash")) work.push(
+    "- Each bash call is a fresh non-interactive shell with no TTY: use workdir or `cd dir && ...` within one call. Never open pagers or interactive editors. " +
+    "Start servers in the background with output redirected (`nohup cmd > app.log 2>&1 &`), then poll the log or port. Pass a larger timeout for long builds and installs.",
+  );
+  if (has("exec_command")) work.push("- For servers, REPLs and programs that prompt for input, use exec_command (tty=true when the program needs a terminal) and continue with write_stdin.");
+  if (has("edit")) work.push("- Prefer edit to rewriting a whole file; copy old_string from read output without the line numbers.");
+
+  return [
+    "You are a coding agent working in a terminal.",
+    toolsLine,
+    ...(env === undefined ? [] : [environmentSection(env)]),
+    work.join("\n"),
+    workingProtocol(toolNames),
+    "Be concise. Do not narrate what you are about to do; do it, then say what happened.",
+  ].join("\n\n");
+}
+
+/** I/O half of the environment snapshot; the formatting is pure (core/environment.ts). */
+export function sessionEnvironment(workspace: string): SessionEnvironment {
+  const now = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  let git = false;
+  try {
+    git = Bun.spawnSync(["git", "rev-parse", "--is-inside-work-tree"], { cwd: workspace, stdout: "pipe", stderr: "ignore" })
+      .stdout.toString().trim() === "true";
+  } catch { /* no git on PATH is "not a repository" for the model's purposes */ }
+  return {
+    platform: `${process.platform} ${release()} (${process.arch})`,
+    shell: "bash (tool commands run with bash -lc)",
+    cwd: workspace,
+    date: `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`,
+    git,
+  };
+}
+
+/**
+ * Session policy a CLI coding session differs from a benchmark run in.
+ * Benchmarks construct their own SessionConfig and keep the core defaults.
+ */
+export function cliSessionConfig(args: Args): { continuationAfter: number; timeBudgetMs?: number } {
+  // Never within a request. A real Kimi K3 run with the reminder at reply six
+  // spent half its requests on notes after the work was already verified
+  // (fix-cli-continuation-noise). The reminder still fires where it earns its
+  // place: a resumed handoff that cannot continue, and boundary preparation.
+  return { continuationAfter: Infinity, ...(args.timeBudgetMs === undefined ? {} : { timeBudgetMs: args.timeBudgetMs }) };
+}
+
+export type AskSlot = {
+  current?: (request: PermissionRequest) => Promise<ApprovalChoice>;
+};
+
+export interface Args {
+  workspace: string;
+  /** `--time-budget <seconds>`, in ms: when to warn the model its run is nearly out of time. */
+  timeBudgetMs?: number;
+  /**
+   * `--path-root`: how far file tools may reach, absolute. Must contain the
+   * workspace. Fingerprints, snapshots and rewind stay workspace-scoped.
+   */
+  pathRoot?: string;
+  logDir: string;
+  maxTurns: number;
+  prompt: string;
+  trigger: number;
+  hard: number;
+  contextPolicy?: ContextPolicy;
+  model: string;
+  provider: string;
+  apiKey: string;
+  listModels: boolean;
+  modelsCommand: boolean;
+  modelsRefresh: boolean;
+  fresh: boolean;
+  noContextFiles: boolean;
+  appendSystemPrompt: string[];
+  systemPrompt: string | null;
+  /** `--tools` allowlist. Omitted when the flag was not passed. */
+  tools?: string[];
+  excludeTools: string[];
+  noTools: boolean;
+  /** `--no-builtin-tools`. False when the flag was not passed. */
+  noBuiltinTools: boolean;
+  allowTools: string[];
+  /** `--approve` true, `--no-approve` false. Omitted when neither. */
+  approve?: boolean;
+  /**
+   * `-p` / `--print`. Distinct from a leftover positional prompt: only this
+   * flag reads piped stdin, so a one-shot that did not ask for a pipe cannot
+   * hang on an open stdin the caller never meant to send.
+   */
+  print: boolean;
+  /** `--theme <name|path>`. Empty when the flag was not passed. */
+  theme: string;
+  /** `--thinking <level>`. Empty when the flag was not passed. */
+  thinking?: string;
+  /** `--models <patterns>`. Comma-separated; empty when the flag was not passed. */
+  models?: string;
+  noSkills: boolean;
+  noPromptTemplates: boolean;
+  skillPaths: string[];
+  promptTemplatePaths: string[];
+  /** `-c` / `--continue`. */
+  continueLatest?: boolean;
+  /**
+   * `-r` / `--resume`. A string is an id prefix; `true` is the selector
+   * with no id (list, do not guess).
+   */
+  resume?: string | true;
+  /** `--session <path|id prefix>`. */
+  session?: string;
+  /** `--fork <path|id prefix>`. */
+  forkFrom?: string;
+  /** `--no-session`. */
+  noSession?: boolean;
+  /** `--session-dir <dir>`. */
+  sessionDir?: string;
+  /** `-n` / `--name`. */
+  sessionName?: string;
+  /** `--mode json`. Empty / omitted when the flag was not passed. */
+  mode?: string;
+  /** `--verbose`. Expands the startup header's counts into lists. */
+  verbose?: boolean;
+}
+
+/**
+ * Names `parseArgs` actually accepts. `--refresh` is not here: it is only
+ * valid after the `models` subcommand, and listing it would make a top-level
+ * `--refresh` suggest itself while still being rejected.
+ *
+ * Keep in sync with the branches in `parseArgs`. A missing entry still
+ * parses; it just cannot be offered as a suggestion.
+ */
+const KNOWN_FLAGS: readonly string[] = [
+  "--workspace", "-w",
+  "--path-root",
+  "--time-budget",
+  "--log",
+  "--max-turns",
+  "--trigger",
+  "--hard",
+  "--context-policy",
+  "--model", "-m",
+  "--provider",
+  "--api-key",
+  "--list-models",
+  "--fresh",
+  "--continue", "-c",
+  "--resume", "-r",
+  "--session",
+  "--fork",
+  "--no-session",
+  "--session-dir",
+  "--name", "-n",
+  "--no-context-files", "-nc",
+  "--system-prompt",
+  "--append-system-prompt",
+  "--tools", "-t",
+  "--exclude-tools", "-xt",
+  "--no-tools", "-nt",
+  "--no-builtin-tools",
+  "--allow-tools",
+  "--approve", "-a",
+  "--no-approve", "-na",
+  "--theme",
+  "--thinking",
+  "--models",
+  "--skill",
+  "--prompt-template",
+  "--no-skills",
+  "--no-prompt-templates",
+  "--mode",
+  "--verbose",
+  "--print", "-p",
+  "--help", "-h",
+];
+
+/**
+ * Levenshtein. Ten lines instead of a dependency. `--no-session` and
+ * `--no-sessions` are distance 1: the caller must suggest, never apply.
+ */
+function editDistance(a: string, b: string): number {
+  const n = b.length;
+  const prev = Array.from({ length: n + 1 }, (_, j) => j);
+  const cur = new Array<number>(n + 1);
+  for (let i = 1; i <= a.length; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur[j] = Math.min(prev[j]! + 1, cur[j - 1]! + 1, prev[j - 1]! + cost);
+    }
+    for (let j = 0; j <= n; j++) prev[j] = cur[j]!;
+  }
+  return prev[n]!;
+}
+
+function closestKnownFlag(flag: string): string {
+  let best = KNOWN_FLAGS[0]!;
+  let bestD = Infinity;
+  for (const known of KNOWN_FLAGS) {
+    const d = editDistance(flag, known);
+    if (d < bestD || (d === bestD && known < best)) {
+      bestD = d;
+      best = known;
+    }
+  }
+  return best;
+}
+
+/**
+ * A warning that still exits 0 is how this bug hid: scripts treated a typo
+ * as success. Suggest the nearest name and stop. Never rewrite the argv.
+ */
+function rejectUnknownFlag(flag: string): never {
+  const suggestion = closestKnownFlag(flag);
+  console.error(`unknown flag: ${flag}`);
+  console.error(`  did you mean ${suggestion}?`);
+  process.exit(1);
+}
+
+/**
+ * Stop the terminal echoing before startup does anything slow.
+ *
+ * Reading auth, scanning context files and printing the header all happen
+ * before the TUI attaches. In cooked mode the tty echoes whatever is typed
+ * during that window, so keystrokes land *between* the banner's own lines
+ * and look like output the program produced. Raw mode is the TUI's anyway;
+ * taking it at the first instruction just closes the gap.
+ *
+ * `stdin` is a parameter so the decision is testable without a real tty.
+ * Returns an undo so a caller that bails out can put the terminal back.
+ */
+export function silenceTtyEarly(opts: {
+  interactive: boolean;
+  stdin?: Pick<NodeJS.ReadStream, "isTTY" | "setRawMode" | "resume">;
+}): () => void {
+  const stdin = opts.stdin ?? process.stdin;
+  if (!opts.interactive || stdin.isTTY !== true) return () => {};
+  stdin.setRawMode(true);
+  // Leave input buffered until ProcessTerminal installs its listener. Resuming
+  // here drops keystrokes typed while startup or transcript loading awaits I/O.
+  return () => {
+    if (stdin.isTTY === true) stdin.setRawMode(false);
+  };
+}
+
+export function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    workspace: process.cwd(), logDir: "", maxTurns: 40, prompt: "",
+    // Overridable so a node boundary can be forced in a short session --
+    // otherwise cutting is only reachable after tens of thousands of tokens,
+    // which makes the most interesting path the least exercised one.
+    trigger: 0, hard: 0,
+    model: "", provider: "", apiKey: "", listModels: false, modelsCommand: false, modelsRefresh: false, fresh: false,
+    noContextFiles: false, appendSystemPrompt: [],
+    systemPrompt: null,
+    excludeTools: [], noTools: false, noBuiltinTools: false, allowTools: [],
+    print: false,
+    theme: "",
+    thinking: "",
+    models: "",
+    noSkills: false, noPromptTemplates: false, skillPaths: [], promptTemplatePaths: [],
+    continueLatest: false, session: "", forkFrom: "", noSession: false, sessionDir: "", sessionName: "",
+    mode: "", verbose: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--workspace" || a === "-w") args.workspace = argv[++i] ?? args.workspace;
+    else if (a === "--path-root") args.pathRoot = resolve(argv[++i] ?? "/");
+    else if (a === "--time-budget") {
+      const seconds = Number(argv[++i]);
+      if (!Number.isFinite(seconds) || seconds <= 0) throw new Error("--time-budget requires a positive number of seconds");
+      args.timeBudgetMs = seconds * 1000;
+    }
+    else if (a === "--log") args.logDir = argv[++i] ?? "";
+    else if (a === "--max-turns") args.maxTurns = Number(argv[++i] ?? args.maxTurns);
+    else if (a === "--trigger") args.trigger = Number(argv[++i] ?? 0);
+    else if (a === "--hard") args.hard = Number(argv[++i] ?? 0);
+    else if (a === "--context-policy") {
+      const policy = argv[++i];
+      if (!isContextPolicy(policy)) throw new Error("--context-policy requires windowed, segmented, continuous, or adaptive");
+      args.contextPolicy = policy;
+    }
+    else if (a === "--model" || a === "-m") args.model = argv[++i] ?? "";
+    else if (a === "--provider") args.provider = argv[++i] ?? "";
+    else if (a === "--api-key") args.apiKey = argv[++i] ?? "";
+    else if (a === "--list-models") args.listModels = true;
+    else if (a === "models" && i === 0) {
+      // Subcommand, not a prompt. Do not consume the rest: a later
+      // `--models-url` must still be an unknown-flag error, and `-h`
+      // must still print help.
+      args.modelsCommand = true;
+    }
+    else if (a === "--refresh" && args.modelsCommand) {
+      args.modelsRefresh = true;
+    }
+    else if (a === "--fresh") args.fresh = true;
+    else if (a === "-c" || a === "--continue") args.continueLatest = true;
+    else if (a === "-r" || a === "--resume") {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("-")) args.resume = argv[++i]!;
+      else args.resume = true;
+    }
+    else if (a === "--session") args.session = argv[++i] ?? "";
+    else if (a === "--fork") args.forkFrom = argv[++i] ?? "";
+    else if (a === "--no-session") args.noSession = true;
+    else if (a === "--session-dir") args.sessionDir = argv[++i] ?? "";
+    else if (a === "-n" || a === "--name") args.sessionName = argv[++i] ?? "";
+    else if (a === "--no-context-files" || a === "-nc") args.noContextFiles = true;
+    else if (a === "--system-prompt") args.systemPrompt = argv[++i] ?? "";
+    else if (a === "--append-system-prompt") args.appendSystemPrompt.push(argv[++i] ?? "");
+    else if (a === "--tools" || a === "-t") args.tools = parseToolList(argv[++i] ?? "");
+    else if (a === "--exclude-tools" || a === "-xt") args.excludeTools = parseToolList(argv[++i] ?? "");
+    else if (a === "--no-tools" || a === "-nt") args.noTools = true;
+    else if (a === "--no-builtin-tools") args.noBuiltinTools = true;
+    else if (a === "--allow-tools") args.allowTools = parseToolList(argv[++i] ?? "");
+    else if (a === "--approve" || a === "-a") args.approve = true;
+    else if (a === "--no-approve" || a === "-na") args.approve = false;
+    else if (a === "--theme") args.theme = argv[++i] ?? "";
+    else if (a === "--thinking") args.thinking = argv[++i] ?? "";
+    else if (a === "--models") args.models = argv[++i] ?? "";
+    else if (a === "--skill") args.skillPaths.push(argv[++i] ?? "");
+    else if (a === "--prompt-template") args.promptTemplatePaths.push(argv[++i] ?? "");
+    else if (a === "--no-skills") args.noSkills = true;
+    else if (a === "--no-prompt-templates") args.noPromptTemplates = true;
+    else if (a === "--mode") args.mode = argv[++i] ?? "";
+    else if (a === "--verbose") args.verbose = true;
+    else if (a === "-p" || a === "--print") {
+      args.print = true;
+      const next = argv[++i] ?? "";
+      args.prompt += (args.prompt ? " " : "") + next;
+    }
+    else if (a === "--help" || a === "-h") {
+      console.log(
+        "usage: xeno [-m <model>] [--provider <name>] [--api-key <key>]\n" +
+          "            [-w <workspace>] [--log <dir>] [--max-turns N]\n" +
+          "            [--context-policy windowed|segmented|continuous|adaptive]\n" +
+          "            [--trigger N --hard N] [--list-models] [--fresh]\n" +
+          "            [-c|--continue] [-r|--resume [id]] [--session path|id]\n" +
+          "            [--fork path|id] [--no-session] [--session-dir dir]\n" +
+          "            [-n|--name name]\n" +
+          "            [models --refresh]\n" +
+          "            [--system-prompt <text-or-file>] [--append-system-prompt <text>]\n" +
+          "            [--no-context-files|-nc]\n" +
+          "            [--tools names] [--exclude-tools names] [--no-tools]\n" +
+          "            [--no-builtin-tools]\n" +
+          "            [--allow-tools names] [--approve|--no-approve]\n" +
+          "            [--theme <name|path>] [--thinking <level>] [--models a,b]\n" +
+          "            [--skill <path>] [--no-skills]\n" +
+          "            [--prompt-template <path>] [--no-prompt-templates]\n" +
+          "            [--mode json] [--verbose]\n" +
+          "            [-p <prompt>] [prompt...]\n\n" +
+          "  A workspace that already holds a session is resumed. --fresh starts a\n" +
+          "  separate one alongside it; nothing is ever deleted.\n" +
+          "  -c continues the newest; --session / -r <id> pick one (unique prefix only).\n" +
+          "  --no-session runs without writing .xeno/sessions/. --fork copies into a new one.\n" +
+          "  A leftover .xeno/log is not moved; continue it with --log .xeno/log.\n\n" +
+          "  With a prompt, runs it and exits. Without one, reads prompts from stdin.\n" +
+          "  Commands: /model  /thinking  /login  /new  /resume  /name  /session  /usage  /state\n" +
+          "            /export  /copy  /fork  /clone\n" +
+          "            /back [n [files|context]] [confirm]  /trust  /settings  /hotkeys\n" +
+          "            /help  /quit\n\n" +
+          "  Credentials resolve in this order: --api-key, then ~/.xeno/auth.json,\n" +
+          "  then the provider's environment variable.\n" +
+          "  --system-prompt replaces the built-in instructions (text, or a file that exists).\n" +
+          "  --append-system-prompt appends; repeatable. -nc skips AGENTS.md discovery.\n" +
+          "  --tools is a strict allowlist; excluded tools leave the schema.\n" +
+          "  --no-builtin-tools drops built-ins and keeps any other source; --tools still wins.\n" +
+          "  bash asks before it runs. --allow-tools bash skips the ask for this process.\n" +
+          "  --time-budget <seconds> tells the model, once, when 75% of the run's wall-clock budget is used.\n" +
+          "  --path-root <dir> lets file tools reach absolute paths under <dir> (e.g. / in a container);\n" +
+          "  relative paths, fingerprints and /back stay in the workspace, so edits outside it are not rewound.\n" +
+          "  --approve loads .xeno/settings.json this run; --no-approve skips it.\n" +
+          "  Project trust does not affect tool execution.\n" +
+          "  --mode json writes one JSON object per event to stdout; diagnostics stay on stderr.\n" +
+          "  --verbose expands the startup header (AGENTS.md, skills, prompt templates).",
+      );
+      process.exit(0);
+    } else if (a === "--") {
+      // Everything after `--` is content, never a flag. The delimiter
+      // is consumed so a dashed token cannot be mistaken for an option.
+      for (let j = i + 1; j < argv.length; j++) {
+        args.prompt += (args.prompt ? " " : "") + argv[j]!;
+      }
+      break;
+    } else if (a.startsWith("-") && a !== "-") {
+      rejectUnknownFlag(a);
+    } else args.prompt += (args.prompt ? " " : "") + a;
+  }
+  return args;
+}
+
+/**
+ * Command-line prompt first, piped stdin after. Both belong in the first
+ * user message; reversing that would make `cat README | xeno -p "总结"`
+ * look like the file was the instruction.
+ */
+export function mergePrintPrompt(prompt: string, stdinText: string): string {
+  if (stdinText.length === 0) return prompt;
+  if (prompt.length === 0) return stdinText;
+  return (prompt.endsWith("\n") ? prompt : `${prompt}\n`) + stdinText;
+}
+
+/**
+ * Drain stdin only when it is not a tty. Reading a tty would wait forever
+ * for a pipe that an interactive `-p` never has.
+ *
+ * `firstByteMs` bounds the wait for the FIRST byte, and is set when the
+ * command line already carries a prompt. An eval runner, an IDE or a parent
+ * script often hands a child a pipe it never writes and never closes; reading
+ * that to EOF hung the whole run before the banner (fix-print-stdin-hang).
+ * Claude Code applies the same 3s guard. Once data starts, it is read to EOF
+ * however slowly it arrives, so a slow producer is not truncated.
+ */
+export async function readPipedStdin(
+  input: { readonly isTTY?: boolean } & AsyncIterable<unknown> = process.stdin,
+  opts: { firstByteMs?: number; warn?: (line: string) => void } = {},
+): Promise<string> {
+  if (input.isTTY === true) return "";
+  const chunks: Uint8Array[] = [];
+  const encoder = new TextEncoder();
+  const iterator = input[Symbol.asyncIterator]();
+  const push = (chunk: unknown) => {
+    if (typeof chunk === "string") chunks.push(encoder.encode(chunk));
+    else if (chunk instanceof Uint8Array) chunks.push(chunk);
+  };
+  let first: IteratorResult<unknown>;
+  if (opts.firstByteMs === undefined) first = await iterator.next();
+  else {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), opts.firstByteMs); });
+    const raced = await Promise.race([iterator.next(), timeout]);
+    clearTimeout(timer);
+    if (raced === null) {
+      (opts.warn ?? ((line) => process.stderr.write(line + "\n")))(
+        `warning: no stdin data received in ${(opts.firstByteMs / 1000).toFixed(0)}s, proceeding without it; ` +
+        "redirect stdin from /dev/null to skip the wait");
+      // Stop holding the pipe open for the rest of the run.
+      if (input === process.stdin) process.stdin.pause();
+      return "";
+    }
+    first = raced;
+  }
+  for (let result = first; !result.done; result = await iterator.next()) push(result.value);
+  if (chunks.length === 0) return "";
+  return new TextDecoder().decode(Buffer.concat(chunks));
+}
+
+export function isPrintMode(args: Args): boolean {
+  return args.print || args.prompt.length > 0;
+}
+
+export function isJsonMode(args: Args): boolean {
+  return args.mode === "json";
+}
+
+/**
+ * Most-used actions, in glance order. Keys are read off the map so an
+ * unbound action cannot appear as a hint (feat-status-line rule 6, reused
+ * here). Labels are not chords; a chord that is not in `byKey` is a bug.
+ */
+const HEADER_SHORTCUTS: readonly { action: ActionId; label: string }[] = [
+  { action: "app.interrupt", label: "interrupt" },
+  { action: "app.toggleTools", label: "tools" },
+  { action: "app.toggleThinking", label: "think" },
+  { action: "app.externalEditor", label: "editor" },
+  { action: "app.exit", label: "quit" },
+];
+
+export function formatShortcutLine(keymap: Keymap): string {
+  const parts: string[] = [];
+  for (const { action, label } of HEADER_SHORTCUTS) {
+    const key = keymap.byAction[action]?.[0];
+    if (key === undefined) continue;
+    parts.push(`${key} ${label}`);
+  }
+  return parts.join(" · ");
+}
+
+export function formatStartupHeader(input: {
+  readonly model: string;
+  readonly workspace: string;
+  readonly session: string;
+  readonly agents: readonly string[];
+  readonly skills: readonly string[];
+  readonly prompts: readonly string[];
+  readonly tools?: readonly string[];
+  readonly keymap: Keymap;
+  readonly verbose: boolean;
+}): string[] {
+  const lines: string[] = [
+    input.model,
+    `workspace  ${input.workspace}`,
+    `session    ${input.session}`,
+  ];
+  const pushCount = (label: string, items: readonly string[]): void => {
+    lines.push(`${label.padEnd(10)}${items.length}`);
+    if (input.verbose) {
+      for (const item of items) lines.push(`  ${item}`);
+    }
+  };
+  pushCount("agents", input.agents);
+  pushCount("skills", input.skills);
+  pushCount("prompts", input.prompts);
+  if (input.tools !== undefined) pushCount("tools", input.tools);
+  const keys = formatShortcutLine(input.keymap);
+  if (keys.length > 0) lines.push(`keys       ${keys}`);
+  return lines;
+}
+
+function countCatalogDelta(
+  beforeText: string | null,
+  afterText: string | null,
+): { added: number; changed: number } {
+  const ids = (text: string | null): Map<string, string> => {
+    const map = new Map<string, string>();
+    if (text === null || text.trim().length === 0) return map;
+    let json: unknown;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      return map;
+    }
+    for (const spec of parseUserCatalog(json).models) {
+      map.set(spec.id, JSON.stringify(spec));
+    }
+    return map;
+  };
+  const before = ids(beforeText);
+  const after = ids(afterText);
+  let added = 0;
+  let changed = 0;
+  for (const [id, body] of after) {
+    const prev = before.get(id);
+    if (prev === undefined) added += 1;
+    else if (prev !== body) changed += 1;
+  }
+  return { added, changed };
+}
+
+/**
+ * Explicit catalog refresh. Download and validate before the write; a
+ * failure returns a reason and must not have touched the existing file.
+ * Exit status is the caller's: the CLI process exits non-zero, `/models
+ * refresh` only prints.
+ */
+export async function runModelsRefresh(opts: {
+  fetch: CatalogFetch;
+  write: (value: unknown) => Promise<void>;
+}): Promise<
+  | { ok: true; count: number; added: number; changed: number }
+  | { ok: false; reason: string }
+> {
+  const before = await readModelsText();
+  const result = await refreshRemoteCatalog({
+    fetch: opts.fetch,
+    write: opts.write,
+  });
+  if (!result.ok) return result;
+  const after = await readModelsText();
+  const delta = countCatalogDelta(before.text, after.text);
+  return { ok: true, count: result.count, added: delta.added, changed: delta.changed };
+}
+
+/**
+ * The two effects credential resolution needs. Real ones here; the tests
+ * inject fakes, which is why the priority rules can be pinned offline.
+ *
+ * A key command runs once per process. Re-running `security find-generic-
+ * password` on every request would spend a keychain round trip per turn to
+ * re-learn something that has not changed.
+ */
+const commandCache = new Map<string, string>();
+
+export function processEffects(): ResolveEffects {
+  return {
+    env: (name) => process.env[name],
+    run: (command) => {
+      const cached = commandCache.get(command);
+      if (cached !== undefined) return cached;
+      const p = Bun.spawnSync(["bash", "-lc", command]);
+      if (p.exitCode !== 0) {
+        throw new Error(`exit ${p.exitCode}: ${new TextDecoder().decode(p.stderr).trim()}`);
+      }
+      const out = new TextDecoder().decode(p.stdout);
+      commandCache.set(command, out);
+      return out;
+    },
+  };
+}
+
+/**
+ * Mutable I/O for a running app. The TUI replaces `say` so retry lines
+ * land in the transcript rather than punching through the live region.
+ * The object identity is stable: providers close over this reference.
+ */
+export interface AppIO {
+  palette: Palette;
+  say: (line: string) => void;
+  err: (line: string) => void;
+  /**
+   * Print mode only. The assistant's final text belongs on stdout; `say` is
+   * stderr there so a script cannot mistake a draft or a banner for the
+   * answer. Absent in interactive and piped-REPL runs, which still print
+   * the whole transcript through `say`.
+   */
+  answer?: (text: string) => void;
+}
+
+export interface App {
+  args: Args;
+  session: Session;
+  workspace: string;
+  logDir: string;
+  blobDir: string;
+  system: string;
+  providerConfig: ProviderConfig;
+  /** May be `{ ok: false }` in an interactive session waiting on /login. */
+  credential: Resolved;
+  auth: AuthFile;
+  effects: ResolveEffects;
+  loadedContext: LoadedContext;
+  credentialOf: (spec: ModelSpec) => Resolved;
+  catalog: readonly ModelSpec[];
+  io: AppIO;
+  /**
+   * The TUI writes `current` while it can ask. One-shot and piped runs
+   * leave it empty, so an ask becomes a named refusal.
+   */
+  askSlot: AskSlot;
+  ui?: UiState;
+  slash?: SlashCatalog;
+}
+
+export interface UiState {
+  settings: Settings;
+  theme: UiResources["theme"];
+  keymap: UiResources["keymap"];
+  userOverrides: Partial<Settings>;
+  style: Style;
+}
+
+function toUiState(loaded: UiResources, color: boolean): UiState {
+  return {
+    settings: loaded.settings,
+    theme: loaded.theme,
+    keymap: loaded.keymap,
+    userOverrides: loaded.userOverrides,
+    style: color ? createStyle(loaded.theme.colors) : IDENTITY,
+  };
+}
+
+function asEffort(value: string | undefined): Effort | undefined {
+  if (value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max") {
+    return value;
+  }
+  return undefined;
+}
+
+/** `--models a,b` and settings.scopedModels share this split so a stray space cannot invent a pattern. */
+export function splitModelPatterns(raw: string | undefined): string[] {
+  if (raw === undefined || raw.length === 0) return [];
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+/**
+ * One line saying where the key came from, or why there isn't one.
+ *
+ * When a stored entry is what failed, the reason has to be the stored entry
+ * -- naming the environment variable would offer a fix that this resolver
+ * will then deliberately ignore, because a stored credential owns its
+ * provider.
+ */
+export function whyNot(spec: ModelSpec, got: Resolved, auth: AuthFile, C: Palette): string {
+  if (got.ok) return C.dim(`  via ${got.source}`);
+  if (auth[spec.provider] !== undefined) return C.yellow(`  ${got.reason}`);
+  return C.dim(`  ${envLabel(spec.provider)}`);
+}
+
+/**
+ * /login only exists inside a live session. A one-shot prompt and a pipe
+ * cannot answer it, so those runs must still refuse -- naming /login there
+ * is how this file used to deadlock a first run.
+ */
+/**
+ * What a non-interactive run says when it has no key. A model named with
+ * --model is the only thing the caller asked about; listing every provider
+ * hides the one variable that would fix it.
+ */
+export function missingCredentialMessage(spec: ModelSpec, explicit: boolean, catalog: readonly ModelSpec[] = CATALOG): string {
+  return explicit ? `${spec.id}: ${describeMissingCredential(spec.provider)}` : describeUnauthenticatedScript(catalog);
+}
+
+export function isInteractiveSession(args: Args): boolean {
+  return args.prompt.length === 0 && stdinIsTty() && stdoutIsTty();
+}
+
+/**
+ * Script-facing missing-key text. Environment variables and --api-key are
+ * the routes that actually work without a tty; /login is not one of them.
+ */
+export function describeUnauthenticatedScript(catalog: readonly ModelSpec[] = CATALOG): string {
+  const providers = [...new Set(catalog.map((m) => m.provider))];
+  const vars = providers.map((p) => envLabel(p));
+  return (
+    `no model has a credential. Set an API key for one of: ${providers.join(", ")}` +
+    ` -- export ${vars.join(" or ")}, or pass --api-key`
+  );
+}
+
+/** Banner / hint for an interactive session that started without a key. */
+export function describeUnauthenticatedSession(catalog: readonly ModelSpec[] = CATALOG): string {
+  const vars = [...new Set(catalog.map((m) => m.provider))].map((p) => envLabel(p));
+  return (
+    `no credential. This session cannot send until one is set. ` +
+    `Export ${vars.join(" or ")}, or run /login <provider>`
+  );
+}
+
+export function retryHandler(io: AppIO): (attempt: number, delayMs: number, error: unknown) => void {
+  return (attempt, delayMs, error) => {
+    const C = io.palette;
+    // A retry that prints nothing is indistinguishable from a hang, which is
+    // the problem retrying was supposed to remove rather than one to add.
+    io.say(
+      C.yellow(`  retry ${attempt} in ${(delayMs / 1000).toFixed(1)}s`) +
+        C.dim(`  ${describeError(error)}`),
+    );
+  };
+}
+
+export function toolSelectionOf(args: Args) {
+  return {
+    ...(args.noTools ? { none: true as const } : {}),
+    ...(args.tools !== undefined ? { only: args.tools } : {}),
+    ...(args.excludeTools.length > 0 ? { exclude: args.excludeTools } : {}),
+    ...(args.noBuiltinTools === true ? { noBuiltin: true as const } : {}),
+  };
+}
+
+/**
+ * Schema assembly: every tool is tagged with a source here so
+ * `--no-builtin-tools` can drop a category without a later cross-layer
+ * recut. Today the only producer is builtin; an extension would push
+ * `{ ...schema, source: "extension" }` into this list.
+ *
+ * `source` is stripped before the frozen prefix: the wire schema is what
+ * the provider bills, and an extra field there would look like a tool
+ * argument.
+ */
+export function visibleSchemas(args: Args) {
+  const available = TOOL_SCHEMAS.map((t) => ({ ...t, source: "builtin" as const }));
+  return selectTools(available, toolSelectionOf(args)).map((tool) => {
+    const { source, ...schema } = tool;
+    void source;
+    return schema;
+  });
+}
+
+export function unknownToolNames(names: readonly string[]): string[] {
+  const known = new Set(TOOL_SCHEMAS.map((t) => t.name));
+  return names.filter((n) => !known.has(n));
+}
+
+export function createSessionFor(opts: {
+  args: Args;
+  workspace: string;
+  logDir: string;
+  blobDir: string;
+  system: string;
+  providerConfig: ProviderConfig;
+  credential: Resolved;
+  io: AppIO;
+  askSlot: AskSlot;
+  oauth?: boolean;
+}): Session {
+  const { args, workspace, logDir, blobDir, system, providerConfig, credential, io, askSlot } = opts;
+  const schemas = visibleSchemas(args);
+  const names = schemas.map((t) => t.name);
+  const sessionRules: PermissionRule[] = [];
+  const tools: ToolContext = {
+    root: workspace,
+    ...DEFAULT_TOOL_CONTEXT,
+    ...(args.pathRoot === undefined ? {} : { pathRoot: args.pathRoot }),
+    allow: names,
+    rules: rulesWithAllowTools(args.allowTools),
+    sessionRules,
+    askSlot,
+  };
+  return new Session(
+    {
+      logDir,
+      frozen: { system, tools: schemas },
+      blobDir,
+      tools,
+      maxTurns: args.maxTurns,
+      ...cliSessionConfig(args),
+      // Explicit legacy thresholds still select that experiment unless overridden.
+      contextPolicy: args.contextPolicy ?? (args.trigger > 0 ? "segmented" : DEFAULT_CONTEXT_POLICY),
+      ...(args.trigger > 0
+        ? {
+            boundary: {
+              triggerTokens: args.trigger,
+              hardTokens: args.hard || args.trigger * 2,
+              // The work floor has to scale with the trigger: the two are
+              // validated against each other, and a default floor of 5000 under
+              // an experimental trigger of 1200 is a contradiction.
+              minNodeWorkTokens: Math.max(1, Math.floor(args.trigger / 6)),
+            },
+          }
+        : {}),
+    },
+    // Empty key is a placeholder the shell must not send through. Interactive
+    // startup reaches this path so /login exists; run() refuses until a real
+    // credential is installed on the session.
+    createProvider(
+      providerConfig,
+      credential.ok ? credential.key : "",
+      retryHandler(io),
+      opts.oauth === true ? { oauth: true } : undefined,
+    ),
+    systemClock(),
+  );
+}
+
+export async function startup(args: Args): Promise<App> {
+  const C = createPalette(colorEnabled());
+  const printMode = isPrintMode(args);
+  const jsonMode = isJsonMode(args);
+  if ((args.mode ?? "").length > 0 && args.mode !== "json") {
+    console.error(`unknown --mode ${args.mode} (supported: json)`);
+    process.exit(1);
+  }
+  const divert = printMode || jsonMode;
+  const io: AppIO = {
+    palette: C,
+    say: (line) => (divert ? console.error(line) : console.log(line)),
+    err: (line) => console.error(line),
+    ...(printMode && !jsonMode
+      ? {
+          answer: (text: string) => {
+            process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+          },
+        }
+      : {}),
+  };
+  const effects = processEffects();
+
+  const authRead = await readJsonFile<AuthFile>(authPath());
+  if (authRead.error) io.say(C.yellow(`  ${authRead.error}`));
+  const auth: AuthFile = authRead.value ?? {};
+
+  if (args.modelsCommand) {
+    if (!args.modelsRefresh) {
+      io.say("usage: xeno models --refresh");
+      io.say(C.dim("  fetches models.dev into ~/.xeno/models.json; startup never does this."));
+      process.exit(0);
+    }
+    const result = await runModelsRefresh({
+      fetch: globalThis.fetch,
+      write: writeModelsFile,
+    });
+    if (result.ok) {
+      io.say(`  added ${result.added}, changed ${result.changed} (${result.count} total) → ${modelsPath()}`);
+      process.exit(0);
+    } else {
+      io.say(C.yellow(`  ${result.reason}`));
+      io.say(C.dim("  existing models.json left unchanged"));
+      process.exit(1);
+    }
+  }
+
+  // File only. Passing fetch here would make the test of D16 un-runnable.
+  const userFile = await readModelsText();
+  const loaded = loadCatalog({ userText: userFile.text });
+  for (const warning of loaded.warnings) io.say(C.yellow(`  ${warning}`));
+  const catalog = loaded.models;
+
+  const credentialOf = (spec: ModelSpec) => resolveCredential(spec, auth, args.apiKey, effects);
+  const hasCredential = (spec: ModelSpec) => credentialOf(spec).ok;
+
+  if (args.listModels) {
+    io.say(C.bold("models"));
+    for (const group of groupedModels(catalog)) {
+      io.say(C.bold(group.provider));
+      for (const spec of group.models) {
+        const got = credentialOf(spec);
+        const mark = got.ok ? C.green("ready") : C.dim("  --  ");
+        io.say(`  ${mark}  ${spec.id.padEnd(28)}${C.dim(spec.name.padEnd(28))}${whyNot(spec, got, auth, C)}`);
+      }
+    }
+    io.say(C.dim("\n  run one with  --model <id>"));
+    process.exit(0);
+  }
+
+  const named = [
+    ...(args.tools ?? []),
+    ...args.excludeTools,
+    ...args.allowTools,
+  ];
+  const unknown = unknownToolNames(named);
+  if (unknown.length > 0) {
+    io.err(C.red(`\n  unknown tool: ${unknown.join(", ")}`));
+    io.err(C.dim(`  known: ${TOOL_SCHEMAS.map((t) => t.name).join(", ")}\n`));
+    process.exit(1);
+  }
+
+  /**
+   * Resolving the workspace is the first thing that can fail, and it fails for
+   * ordinary reasons -- a typo in `-w`, a directory that was moved. Reported as
+   * a sentence rather than as a stat() stack trace.
+   *
+   * It has to happen before model selection so a trusted `.xeno/settings.json`
+   * can override the default model. Trust does not affect tools.
+   */
+  let workspace: string;
+  try {
+    workspace = await workspaceRoot(args.workspace);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    io.err(C.red(`\n  cannot use ${args.workspace} as a workspace`));
+    io.err(C.dim(`  ${detail}\n`));
+    process.exit(1);
+  }
+  // A path root that does not contain the workspace would confine relative
+  // paths out of the very directory they resolve in.
+  if (args.pathRoot !== undefined) {
+    const rel = relative(args.pathRoot, workspace);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      io.err(C.red(`\n  --path-root ${args.pathRoot} does not contain the workspace ${workspace}\n`));
+      process.exit(1);
+    }
+  }
+
+  const trustRead = await readTrust();
+  if (trustRead.error) io.say(C.yellow(`  ${trustRead.error}`));
+  let loadProjectSettings = false;
+  if (args.approve === true) {
+    loadProjectSettings = true;
+  } else if (args.approve === false) {
+    loadProjectSettings = false;
+  } else {
+    const decision = lookupTrust(trustRead.value, workspace);
+    if (decision === true) loadProjectSettings = true;
+    else if (decision === false) loadProjectSettings = false;
+    else {
+      loadProjectSettings = false;
+      try {
+        await stat(projectSettingsPath(workspace));
+        io.say(
+          C.dim(
+            `  ${projectSettingsPath(workspace)} not loaded (project is not trusted). ` +
+              `Trust does not affect tool execution. /trust saves a decision, or pass --approve this run.`,
+          ),
+        );
+      } catch {
+        // No project settings file: nothing to load, no notice.
+      }
+    }
+  }
+
+  const uiLoaded = await loadUiResources({
+    workspace,
+    trusted: loadProjectSettings,
+    ...(args.theme.length > 0 ? { theme: args.theme } : {}),
+  });
+  for (const line of uiLoaded.diagnostics) io.say(C.yellow(`  ${line}`));
+  const mergedSettings = uiLoaded.settings;
+  const ui = toUiState(uiLoaded, colorEnabled());
+  const scopedFromFlag = splitModelPatterns(args.models);
+  if (scopedFromFlag.length > 0) {
+    ui.settings = { ...ui.settings, scopedModels: scopedFromFlag };
+  }
+
+  const selected = selectModel(mergedSettings, { model: args.model, provider: args.provider }, hasCredential, catalog);
+  const interactive = isInteractiveSession(args);
+  let spec: ModelSpec;
+  if (selected.ok) {
+    spec = selected.spec;
+  } else {
+    const missingAll = selected.reason.startsWith("no model has a credential");
+    if (!missingAll || !interactive) {
+      io.err(C.red(`\n  ${missingAll ? describeUnauthenticatedScript(catalog) : selected.reason}\n`));
+      process.exit(1);
+    }
+    // Same order as selectModel, ignoring credentials, so the banner names a
+    // real catalog model rather than inventing one.
+    const fallback = selectModel(mergedSettings, { model: args.model, provider: args.provider }, () => true, catalog);
+    const picked = fallback.ok ? fallback.spec : catalog[0];
+    if (picked === undefined) {
+      io.err(C.red("\n  catalog is empty\n"));
+      process.exit(1);
+    }
+    spec = picked;
+  }
+
+  const credential = credentialOf(spec);
+  if (!credential.ok && !interactive) {
+    io.err(C.red(`\n  ${missingCredentialMessage(spec, args.model.length > 0, catalog)}\n`));
+    process.exit(1);
+  }
+
+  const providerConfig: ProviderConfig = {
+    spec,
+    maxTokens: outputTokenBudget(spec),
+    // --thinking wins, then a Ctrl+S default, then /settings thinking / builtin.
+    effort:
+      asEffort(args.thinking) ??
+      asEffort(mergedSettings.defaultThinking) ??
+      asEffort(mergedSettings.thinking) ??
+      DEFAULT_PROVIDER.effort,
+    thinkingDisplay: DEFAULT_PROVIDER.thinkingDisplay,
+  };
+  /**
+   * `--fresh` opens a NEW session beside the old one rather than clearing it.
+   *
+   * Deleting a session's history is destructive and irreversible, and it must
+   * never be the side effect of a flag that reads like "start over". The old
+   * log stays where it is, still resumable by pointing --log at it. A leftover
+   * `.xeno/log` from before named sessions is the same: pointed at, not moved.
+   */
+  const sessionDir = (args.sessionDir ?? "").length > 0 ? args.sessionDir : undefined;
+  const sessionPick =
+    (args.session ?? "").length > 0
+      ? args.session
+      : typeof args.resume === "string"
+        ? args.resume
+        : undefined;
+  let logDir: string;
+  try {
+    const forkFrom = args.forkFrom;
+    if (forkFrom !== undefined && forkFrom.length > 0) {
+      const found = await findSessionByPrefix(workspace, forkFrom, sessionDir);
+      if (!found.ok) {
+        io.err(C.red(`\n  ${found.reason}\n`));
+        process.exit(1);
+      }
+      const created = await createSession(workspace, undefined, sessionDir);
+      await copyAncestryTo(found.session.path, created.path, new Date().toISOString());
+      logDir = created.path;
+    } else {
+      const resolved = await resolveLogDir(workspace, {
+        ...(args.logDir ? { explicit: resolve(args.logDir) } : {}),
+        fresh: args.fresh,
+        ...(args.continueLatest === true ? { continueLatest: true } : {}),
+        ...(args.noSession === true ? { noSession: true } : {}),
+        ...(sessionPick !== undefined ? { session: sessionPick } : {}),
+        ...(sessionDir !== undefined ? { sessionDir } : {}),
+      });
+      if (resolved.legacyNotice !== null && !args.logDir) {
+        io.say(C.yellow(`  ${resolved.legacyNotice}`));
+      }
+      logDir = resolved.logDir;
+    }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    io.err(C.red(`\n  ${detail}\n`));
+    process.exit(1);
+  }
+  if (args.resume === true && sessionPick === undefined && (args.forkFrom ?? "").length === 0 && args.noSession !== true) {
+    // `-r` with no id is a selector, not a guess. Print mode cannot pick.
+    if (isPrintMode(args)) {
+      io.err(C.red("\n  -r needs a session id. Pass -r <id> or --session <id>.\n"));
+      process.exit(1);
+    }
+  }
+  // Snapshots are on by default here. They are optional in the loop because a
+  // read-only branch has nothing to snapshot, but a session a person drives is
+  // exactly the one that will want to go back, and the content has to have been
+  // stored before the turn a person wants back -- it cannot be opted into after.
+  const blobDir = join(workspace, ".xeno", "blobs");
+  await mkdir(logDir, { recursive: true });
+  await mkdir(blobDir, { recursive: true });
+
+  /**
+   * Context files are read once, here, and the result is frozen. Re-reading
+   * them at a node boundary would change `system` and invalidate the prefix
+   * cache for the whole conversation (D6). A reload is a cut; that is a
+   * later card.
+   */
+  const loadedContext = await loadContext({
+    workspace,
+    cwd: process.cwd(),
+    configDir: configDir(),
+    noContextFiles: args.noContextFiles,
+    appendSystemPrompt: args.appendSystemPrompt,
+    ...(args.systemPrompt !== null ? { systemPrompt: args.systemPrompt } : {}),
+  });
+  const selection = toolSelectionOf(args);
+  const visible = visibleSchemas(args);
+  const filtered =
+    selection.only !== undefined ||
+    selection.none === true ||
+    (selection.exclude !== undefined && selection.exclude.length > 0) ||
+    selection.noBuiltin === true;
+  const builtin = systemPromptFor((filtered ? visible : TOOL_SCHEMAS).map((t) => t.name), sessionEnvironment(workspace));
+  const textLoaded = await loadTextResources({
+    workspace,
+    configDir: configDir(),
+    trusted: loadProjectSettings,
+    noSkills: args.noSkills,
+    noPromptTemplates: args.noPromptTemplates,
+    skillPaths: args.skillPaths,
+    promptTemplatePaths: args.promptTemplatePaths,
+  });
+  for (const line of textLoaded.diagnostics) io.say(C.yellow(`  ${line}`));
+  const slashResolved = resolveSlashCatalog(textLoaded.prompts, textLoaded.skills);
+  for (const line of slashResolved.diagnostics) io.say(C.yellow(`  ${line}`));
+  const slash = slashResolved.catalog;
+  const system = appendSkillsToSystem(
+    assembleSystemPrompt(builtin, loadedContext),
+    [...slash.skills.values()],
+  );
+
+  const askSlot: AskSlot = {};
+  const oauth = credential.ok && storedIsOAuth(auth, spec.provider) && args.apiKey.length === 0;
+  const session = createSessionFor({
+    args, workspace, logDir, blobDir, system, providerConfig, credential, io, askSlot,
+    ...(oauth ? { oauth: true } : {}),
+  });
+  // Read before starting, so the banner can say whether this is a new session
+  // or a continued one. start() moves the cursor, which would erase the answer.
+  const priorCursor = await readCursor(logDir);
+
+  try {
+    await session.start();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    io.err(C.red(`\n  cannot start a session in ${workspace}`));
+    io.err(C.dim(`  ${detail}\n`));
+    process.exit(1);
+  }
+
+  const sessionName = args.sessionName;
+  if (sessionName !== undefined && sessionName.length > 0) {
+    const cursor = await readCursor(logDir);
+    if (cursor !== null) {
+      await writeCursor(logDir, { ...cursor, name: sessionName });
+    }
+  }
+
+  printBanner(args, io, {
+    workspace, logDir, providerConfig, credential, loadedContext, session, priorCursor, catalog,
+    keymap: ui.keymap,
+    skills: [...slash.skills.keys()],
+    prompts: [...slash.prompts.keys()],
+    tools: visible.map((t) => t.name),
+  });
+
+  return {
+    args, session, workspace, logDir, blobDir, system, providerConfig, credential,
+    auth, effects, loadedContext, credentialOf, catalog, io, askSlot, ui, slash,
+  };
+}
+
+function printBanner(
+  args: Args,
+  io: AppIO,
+  opts: {
+    workspace: string;
+    logDir: string;
+    providerConfig: ProviderConfig;
+    credential: Resolved;
+    loadedContext: LoadedContext;
+    session: Session;
+    priorCursor: Cursor | null;
+    catalog: readonly ModelSpec[];
+    keymap: Keymap;
+    skills: readonly string[];
+    prompts: readonly string[];
+    tools: readonly string[];
+  },
+): void {
+  const C = io.palette;
+  const {
+    workspace, logDir, providerConfig, credential, loadedContext, session, priorCursor, catalog,
+    keymap, skills, prompts, tools,
+  } = opts;
+  io.say(
+    C.bold("xeno") +
+      C.dim(`  ${providerConfig.spec.name}  effort=${providerConfig.effort}`) +
+      (credential.ok ? C.dim(`  key from ${credential.source}`) : C.yellow("  no credential")),
+  );
+  const header = formatStartupHeader({
+    model: providerConfig.spec.id,
+    workspace,
+    session: basename(logDir),
+    agents: loadedContext.agents.map((f) => f.path),
+    skills,
+    prompts,
+    tools,
+    keymap,
+    verbose: args.verbose === true,
+  });
+  for (const line of header) {
+    // The first header line is the model; the banner already named it.
+    if (line === providerConfig.spec.id) continue;
+    io.say(C.dim(line));
+  }
+  io.say(C.dim(`log        ${logDir}`));
+  for (const notice of loadedContext.notices) {
+    const line = formatNotice(notice);
+    io.say(notice.kind === "skipped" ? C.yellow(`  ${line}`) : C.dim(`  ${line}`));
+  }
+  const { triggerTokens: trigger, hardTokens: hard } = { ...DEFAULT_BOUNDARY, ...session.config.boundary };
+  const policy = session.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY;
+  const budget = windowBudget(session.provider.config.spec.contextWindow, session.provider.config.maxTokens);
+  const description = policy === "continuous" ? "continuous replay; stops at model window"
+    : policy === "windowed" && budget !== null ? `windowed replay; prepare ${budget.prepare}, cut ${budget.trigger}, output reserved`
+    : `${policy}${policy === "windowed" ? " (unknown window; fixed fallback)" : ""}; cut ${trigger}, hard ${hard}`;
+  io.say(C.dim(`boundary   ${description} (estimated tokens)`));
+  if (priorCursor !== null) {
+    const events = session.state.events.length;
+    io.say(
+      C.green(`resumed    node ${session.state.node}`) +
+        C.dim(`  ${events} event${events === 1 ? "" : "s"} in context, last ${priorCursor.updated_at}`),
+    );
+  }
+  if (!credential.ok) {
+    io.say(C.yellow(`  ${describeUnauthenticatedSession(catalog)}`));
+  }
+  io.say("");
+}