@visual-z/xeno 0.1.3 → 0.2.0

package/src/apps/startup.ts

@@ -13,25 +13,35 @@ 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 { ExtensionRegistry } from "../runtime/extensions.ts";
+import { CATALOG, outputTokenBudget, type ModelSpec } from "../runtime/model.ts";
+import { asThinkingLevel, clampThinkingLevel, supportedThinkingLevels } from "../core/thinking.ts";
+import { modelKey } from "../core/session-position.ts";
+import { extensionFlagValue, type ExtensionFlag, type FlagInput } from "../core/extension-flags.ts";
+import { scopedModels } from "../runtime/model-scope.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 { discoverResources, type ResourceIndex } from "../store/resource-index.ts";
+import { runResourceConfig } from "./resource-browser.ts";
+import { PackageManager, type PackageCommand } from "../runtime/package-manager.ts";
+import { pickProjectTrust } from "./project-trust.ts";
 import { appendSkillsToSystem } from "../core/skills.ts";
-import { resolveSlashCatalog, type SlashCatalog } from "./commands.ts";
+import { COMMANDS, 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 { readModelSources, readCatalogCacheText, writeCatalogCache, catalogCachePath } 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 { resolveLogDir, findSessionByPrefix, listSessions, sessionsDir, type ResolveLogOpts } from "../store/sessions.ts";
+import { recoverCut } from "../store/recovery.ts";
+import { planSessionEntry, restoreSessionModel } from "../core/session-entry.ts";
+import { pickStartupSession } from "./session-picker.ts";
 import { loadContext, assembleSystemPrompt, formatNotice, type LoadedContext } from "../store/context-files.ts";
 import {
-  lookupTrust, projectSettingsPath, readTrust,
+  projectTrust,
 } from "../store/trust.ts";
 import { stat } from "node:fs/promises";
 import {
@@ -165,6 +175,15 @@ export interface Args {
   provider: string;
   apiKey: string;
   listModels: boolean;
+  modelSearch?: string;
+  help?: boolean;
+  version?: boolean;
+  exportFile?: string;
+  offline?: boolean;
+  tuiMode?: "regular" | "fullscreen";
+  noThemes?: boolean;
+  themePaths?: string[];
+  sessionId?: string;
   modelsCommand: boolean;
   modelsRefresh: boolean;
   fresh: boolean;
@@ -180,6 +199,10 @@ export interface Args {
   allowTools: string[];
   /** `--approve` true, `--no-approve` false. Omitted when neither. */
   approve?: boolean;
+  configCommand?: boolean;
+  local?: boolean;
+  packageCommand?: PackageCommand;
+  packagePaths?: {source:string;path:string}[];
   /**
    * `-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
@@ -192,8 +215,14 @@ export interface Args {
   thinking?: string;
   /** `--models <patterns>`. Comma-separated; empty when the flag was not passed. */
   models?: string;
+  modelsExplicit?: boolean;
   noSkills: boolean;
   noPromptTemplates: boolean;
+  noExtensions?: boolean;
+  extensionPaths?: string[];
+  extensionFlags?: Record<string, string | boolean>;
+  extensionArgv?: string[];
+  extensionInputs?: Record<string, FlagInput>;
   skillPaths: string[];
   promptTemplatePaths: string[];
   /** `-c` / `--continue`. */
@@ -266,10 +295,12 @@ const KNOWN_FLAGS: readonly string[] = [
   "--prompt-template",
   "--no-skills",
   "--no-prompt-templates",
+  "--extension", "-e", "--no-extensions", "-ne", "--extension-flag",
   "--mode",
   "--verbose",
   "--print", "-p",
   "--help", "-h",
+  "--version", "-v", "--export", "--session-id", "--offline", "--tui-mode", "--use-theme", "--no-themes", "-ns", "-np", "-nbt",
 ];
 
 /**
@@ -341,7 +372,8 @@ export function silenceTtyEarly(opts: {
   };
 }
 
-export function parseArgs(argv: string[]): Args {
+export function parseArgs(argv: string[], options: { deferExtensions?: boolean; flags?: ReadonlyMap<string, ExtensionFlag> } = {}): Args {
+  let selectedTheme: string | undefined;
   const args: Args = {
     workspace: process.cwd(), logDir: "", maxTurns: 40, prompt: "",
     // Overridable so a node boundary can be forced in a short session --
@@ -362,6 +394,11 @@ export function parseArgs(argv: string[]): Args {
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
+    if (["--log", "--session", "--fork", "--session-dir", "--state-dir"].includes(a) &&
+      (!argv[i + 1] || argv[i + 1]!.startsWith("-"))) {
+      console.error(`${a} requires a value`);
+      process.exit(1);
+    }
     if (a === "--workspace" || a === "-w") args.workspace = argv[++i] ?? args.workspace;
     else if (a === "--path-root") args.pathRoot = resolve(argv[++i] ?? "/");
     else if (a === "--state-dir") args.stateDir = resolve(argv[++i] ?? ".");
@@ -382,13 +419,22 @@ export function parseArgs(argv: string[]): Args {
     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 === "--list-models") { args.listModels = true; const next = argv[i + 1]; if (next && !next.startsWith("-") && !next.startsWith("@")) args.modelSearch = argv[++i]!; }
+    else if (a === "--version" || a === "-v") args.version = true;
+    else if (a === "--export") { const file = argv[++i]; if (!file || file.startsWith("-")) throw new Error("--export requires a session path"); args.exportFile = file; }
+    else if (a === "--session-id") { const id = argv[++i]; if (!id || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(id)) throw new Error("--session-id requires a plain session identifier"); args.sessionId = id; }
+    else if (a === "--offline") args.offline = true;
+    else if (a === "--tui-mode") { const mode = argv[++i]; if (mode !== "regular" && mode !== "fullscreen") throw new Error("--tui-mode requires regular or fullscreen"); args.tuiMode = mode; }
     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 === "config" && i === 0) args.configCommand = true;
+    else if ((a === "install" || a === "remove" || a === "update" || a === "list") && i === 0) args.packageCommand = {operation:a,sources:[]};
+    else if ((a === "--local" || a === "-l") && (args.packageCommand || args.configCommand)) { args.local=true; if(args.packageCommand)args.packageCommand.local=true; }
+    else if (a === "--extensions" && args.packageCommand?.operation === "update") { /* Package-only update; xeno never self-updates. */ }
     else if (a === "--refresh" && args.modelsCommand) {
       args.modelsRefresh = true;
     }
@@ -410,70 +456,41 @@ export function parseArgs(argv: string[]): Args {
     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 === "--no-builtin-tools" || a === "-nbt") 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 === "--theme") {
+      const theme = argv[++i]; if (!theme || theme.startsWith("-")) throw new Error("--theme requires a name or path");
+      if (theme.includes("/") || theme.includes("\\") || theme.endsWith(".json")) { (args.themePaths ??= []).push(theme); if (theme.endsWith(".json")) args.theme = theme; }
+      else args.theme = theme;
+    }
+    else if (a === "--use-theme") { const theme = argv[++i]; if (!theme || theme.startsWith("-")) throw new Error("--use-theme requires a name"); selectedTheme = theme; }
+    else if (a === "--no-themes") args.noThemes = true;
     else if (a === "--thinking") args.thinking = argv[++i] ?? "";
-    else if (a === "--models") args.models = argv[++i] ?? "";
+    else if (a === "--models") { const value = argv[++i]; if (value === undefined || value.startsWith("--")) throw new Error("--models requires a value"); args.models = value; args.modelsExplicit = true; }
     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 === "--no-skills" || a === "-ns") args.noSkills = true;
+    else if (a === "--no-prompt-templates" || a === "-np") args.noPromptTemplates = true;
+    else if (a === "--no-extensions" || a === "-ne") args.noExtensions = true;
+    else if (a === "--extension" || a === "-e") {
+      const path = argv[++i]; if (!path || path.startsWith("-")) throw new Error("--extension requires a path");
+      (args.extensionPaths ??= []).push(path);
+    }
+    else if (a === "--extension-flag") {
+      const value = argv[++i] ?? "", at = value.indexOf("=");
+      if (at <= 0) throw new Error("--extension-flag requires name=value");
+      (args.extensionFlags ??= Object.create(null) as Record<string, string | boolean>)[value.slice(0, at)] = value.slice(at + 1) === "true" ? true : value.slice(at + 1) === "false" ? false : value.slice(at + 1);
+    }
     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" +
-          "  --state-dir <dir> keeps snapshots, observations and sessions out of the workspace.\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).",
-      );
+      if (options.deferExtensions) { args.help = true; continue; }
+      printCliHelp();
       process.exit(0);
     } else if (a === "--") {
       // Everything after `--` is content, never a flag. The delimiter
@@ -483,9 +500,23 @@ export function parseArgs(argv: string[]): Args {
       }
       break;
     } else if (a.startsWith("-") && a !== "-") {
-      rejectUnknownFlag(a);
-    } else args.prompt += (args.prompt ? " " : "") + a;
+      const equal = a.indexOf("="), name = a.slice(2, equal === -1 ? undefined : equal), definition = options.flags?.get(name);
+      if (a.startsWith("--") && (definition || options.deferExtensions)) {
+        const next = argv[i + 1], input: FlagInput = { inline: equal !== -1,
+          ...(equal !== -1 ? { value: a.slice(equal + 1) } : next !== undefined && !next.startsWith("-") && !next.startsWith("@") ? { value: next } : {}) };
+        if (definition) {
+          const value = extensionFlagValue(name, definition, input);
+          if (value !== undefined) (args.extensionFlags ??= Object.create(null) as Record<string, string | boolean>)[name] = value;
+          if (!input.inline && input.value !== undefined && (definition.type === "string" || input.value === "true" || input.value === "false")) i++;
+        } else {
+          args.extensionArgv = [...argv]; (args.extensionInputs ??= Object.create(null) as Record<string, FlagInput>)[name] = input;
+          if (!input.inline && input.value !== undefined) i++;
+        }
+      } else rejectUnknownFlag(a);
+    } else if(args.packageCommand)args.packageCommand.sources.push(a);
+    else args.prompt += (args.prompt ? " " : "") + a;
   }
+  if (selectedTheme !== undefined) args.theme = selectedTheme;
   return args;
 }
 
@@ -621,7 +652,7 @@ function countCatalogDelta(
       return map;
     }
     for (const spec of parseUserCatalog(json).models) {
-      map.set(spec.id, JSON.stringify(spec));
+      map.set(modelKey(spec), JSON.stringify(spec));
     }
     return map;
   };
@@ -650,13 +681,13 @@ export async function runModelsRefresh(opts: {
   | { ok: true; count: number; added: number; changed: number }
   | { ok: false; reason: string }
 > {
-  const before = await readModelsText();
+  const before = await readCatalogCacheText();
   const result = await refreshRemoteCatalog({
     fetch: opts.fetch,
     write: opts.write,
   });
   if (!result.ok) return result;
-  const after = await readModelsText();
+  const after = await readCatalogCacheText();
   const delta = countCatalogDelta(before.text, after.text);
   return { ok: true, count: result.count, added: delta.added, changed: delta.changed };
 }
@@ -729,6 +760,10 @@ export interface App {
   askSlot: AskSlot;
   ui?: UiState;
   slash?: SlashCatalog;
+  resources?: ResourceIndex;
+  projectTrusted?: boolean;
+  extensions?: ExtensionRegistry;
+  shutdownRequested?: boolean;
 }
 
 export interface UiState {
@@ -749,13 +784,6 @@ function toUiState(loaded: UiResources, color: boolean): UiState {
   };
 }
 
-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 [];
@@ -791,7 +819,7 @@ export function missingCredentialMessage(spec: ModelSpec, explicit: boolean, cat
 }
 
 export function isInteractiveSession(args: Args): boolean {
-  return args.prompt.length === 0 && stdinIsTty() && stdoutIsTty();
+  return !args.print && !args.help && args.mode !== "json" && args.prompt.length === 0 && stdinIsTty() && stdoutIsTty();
 }
 
 /**
@@ -847,8 +875,9 @@ export function toolSelectionOf(args: Args) {
  * 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 }));
+export function visibleSchemas(args: Args, extensions?: ExtensionRegistry) {
+  const custom = [...extensions?.definitions().values() ?? []].map(({ name, description, input_schema }) => ({ name, description, input_schema, source: "extension" as const }));
+  const available = [...TOOL_SCHEMAS.filter(tool => !extensions?.tools.has(tool.name)).map((t) => ({ ...t, source: "builtin" as const })), ...custom];
   return selectTools(available, toolSelectionOf(args)).map((tool) => {
     const { source, ...schema } = tool;
     void source;
@@ -872,9 +901,11 @@ export function createSessionFor(opts: {
   io: AppIO;
   askSlot: AskSlot;
   oauth?: boolean;
+  effects?: ResolveEffects;
+  extensions?: ExtensionRegistry;
 }): Session {
   const { args, workspace, logDir, blobDir, system, providerConfig, credential, io, askSlot } = opts;
-  const schemas = visibleSchemas(args);
+  const schemas = visibleSchemas(args, opts.extensions);
   const names = schemas.map((t) => t.name);
   const sessionRules: PermissionRule[] = [];
   const tools: ToolContext = {
@@ -885,6 +916,7 @@ export function createSessionFor(opts: {
     rules: rulesWithAllowTools(args.allowTools),
     sessionRules,
     askSlot,
+    ...(opts.extensions ? { extensions: opts.extensions.definitions(), extensionHooks: opts.extensions.toolHooks() } : {}),
   };
   return new Session(
     {
@@ -916,21 +948,171 @@ export function createSessionFor(opts: {
       providerConfig,
       credential.ok ? credential.key : "",
       retryHandler(io),
-      opts.oauth === true ? { oauth: true } : undefined,
+      { ...(opts.oauth === true ? { oauth: true } : {}), ...(opts.effects ? { effects: opts.effects } : {}) },
     ),
     systemClock(),
   );
 }
 
+/** One location policy for startup, /new, /resume and /fork. */
+export function sessionDirFor(args: Args, workspace: string): string | undefined {
+  if (args.sessionDir) return args.sessionDir;
+  return args.stateDir === undefined ? undefined : statePaths(workspace, args.stateDir).sessions;
+}
+
+type OpenSessionOptions = Omit<Parameters<typeof createSessionFor>[0], "providerConfig" | "credential" | "oauth" | "system"> & {
+  catalog: readonly ModelSpec[];
+  auth: AuthFile;
+  credentialOf: (spec: ModelSpec) => Resolved;
+  interactive: boolean;
+  settings?: Settings;
+  /** CLI overrides belong to this open only; /resume must not inherit them. */
+  modelFlags?: { model: string; provider: string };
+  preparedResources?: { workspace: string; value: Awaited<ReturnType<typeof loadSessionResources>> };
+  fallback?: ProviderConfig;
+  projectTrusted?: boolean;
+};
+
+/** Pi replaces cwd-scoped resources with the session runtime; publish only after all reads succeed. */
+async function prepareExtensionPackages(args: Args, workspace: string): Promise<void> {
+  const remote=(args.extensionPaths??[]).filter(path=>/^(npm:|git:|git\+|https?:\/\/|ssh:\/\/|git@)/.test(path));
+  if(!remote.length)return;
+  if(args.offline || process.env["XENO_OFFLINE"] === "1") throw new Error("--offline prevents remote extension package preparation; install it explicitly beforehand");
+  const manager=new PackageManager({workspace});
+  for(const source of remote)(args.packagePaths??=[]).push({source,path:await manager.temporary(source)});
+  args.extensionPaths=(args.extensionPaths??[]).filter(path=>!remote.includes(path));
+}
+
+export async function loadSessionResources(args: Args, workspace: string, io: AppIO, trustOverride?: boolean): Promise<{
+  loadedContext: LoadedContext; slash: SlashCatalog; ui: UiState; index: ResourceIndex; trusted: boolean; system: string; extensions: ExtensionRegistry;
+}> {
+  const { trusted } = await projectTrust(workspace, trustOverride ?? args.approve);
+  await prepareExtensionPackages(args,workspace);
+  const index = await discoverResources({ ...args, workspace, trusted });
+  const extensions = new ExtensionRegistry({ reserved: COMMANDS.map(command => command.name), reservedFlags: KNOWN_FLAGS.map(flag => flag.replace(/^-+/, "")),
+    flagValue: (name, definition) => args.extensionFlags && Object.hasOwn(args.extensionFlags, name) ? args.extensionFlags[name] : extensionFlagValue(name, definition, args.extensionInputs && Object.hasOwn(args.extensionInputs, name) ? args.extensionInputs[name] : undefined), report: io.say });
+  await extensions.load(index);
+  if(args.extensionArgv) {
+    const validated = parseArgs(args.extensionArgv, { flags: extensions.flags, ...(args.help ? { deferExtensions: true } : {}) });
+    if (validated.extensionArgv) rejectUnknownFlag("--" + Object.keys(validated.extensionInputs ?? {})[0]);
+    args.prompt = validated.prompt; args.extensionFlags = validated.extensionFlags ?? {};
+  }
+  const loaded = await loadUiResources({ ...args, workspace, trusted, ...(args.theme ? { theme: args.theme } : {}) }, index);
+  const loadedContext = await loadContext({ workspace, cwd: workspace, configDir: configDir(),
+    noContextFiles: args.noContextFiles, appendSystemPrompt: args.appendSystemPrompt,
+    ...(args.systemPrompt === null ? {} : { systemPrompt: args.systemPrompt }) });
+  for (const notice of loadedContext.notices) if (notice.kind === "skipped" || notice.truncated) io.say(io.palette.yellow(formatNotice(notice)));
+  const text = await loadTextResources({ workspace, configDir: configDir(), trusted, noSkills: args.noSkills,
+    noPromptTemplates: args.noPromptTemplates, skillPaths: args.skillPaths, promptTemplatePaths: args.promptTemplatePaths }, index);
+  const slash = resolveSlashCatalog(text.prompts, text.skills);
+  for (const line of new Set([...loaded.diagnostics, ...text.diagnostics, ...slash.diagnostics])) io.say(io.palette.yellow(`  ${line}`));
+  const system = appendSkillsToSystem(assembleSystemPrompt(systemPromptFor(visibleSchemas(args, extensions).map(tool => tool.name), sessionEnvironment(workspace)), loadedContext), text.skills);
+  const ui = toUiState(loaded, colorEnabled());
+  if (args.tuiMode) ui.settings = { ...ui.settings, tuiMode: args.tuiMode };
+  return { loadedContext, slash: { ...slash.catalog, skillCommands: loaded.settings.enableSkillCommands !== false }, ui, index, trusted, system, extensions };
+}
+
+/**
+ * Pi's session-before-model order, with xeno's N.8 checkpoint on an explicit
+ * model change. Opening never sends a request to the previous provider.
+ * Callers publish the returned session/config/credential together on success.
+ */
+export async function openSessionFor(opts: OpenSessionOptions): Promise<{
+  session: Session; priorCursor: Cursor | null; providerConfig: ProviderConfig; credential: Resolved;
+  workspace: string; blobDir: string; system: string; resources: Awaited<ReturnType<typeof loadSessionResources>>;
+}> {
+  const recorded = await readCursor(opts.logDir);
+  const priorCursor = recorded === null ? null : await recoverCut(opts.logDir, recorded);
+  const workspace = priorCursor?.workspace ?? opts.workspace;
+  if (opts.args.pathRoot) {
+    const rel = relative(opts.args.pathRoot, workspace);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("saved workspace is outside --path-root");
+  }
+  if (opts.preparedResources && opts.preparedResources.workspace !== workspace) await opts.preparedResources.value.extensions.dispose();
+  const resources = opts.preparedResources?.workspace === workspace ? opts.preparedResources.value
+    : await loadSessionResources(opts.args, workspace, opts.io, workspace === opts.workspace ? opts.projectTrusted : undefined);
+  const interactive = opts.interactive && !opts.args.print && !opts.args.prompt && opts.args.mode !== "json";
+  const named = [...opts.args.tools ?? [], ...opts.args.excludeTools, ...opts.args.allowTools];
+  const unknown = unknownToolNames(named).filter(name => !resources.extensions.tools.has(name));
+  if (unknown.length) throw new Error(`unknown tool: ${unknown.join(", ")}`);
+  const saved = priorCursor === null ? undefined : restoreSessionModel(priorCursor, opts.catalog);
+  const flags = { ...opts.modelFlags ?? { model: "", provider: "" } };
+  const parsedModel = flags.model ? scopedModels([flags.model], flags.provider ? opts.catalog.filter(model => model.provider === flags.provider) : opts.catalog, true).entries[0] : undefined;
+  if (parsedModel) flags.model = modelKey(parsedModel.model);
+  const explicit = flags.model.length > 0 || flags.provider.length > 0;
+  const settings = opts.settings ?? {};
+  const preferred = saved ?? opts.fallback?.spec;
+  const selected = !explicit && preferred !== undefined
+    ? { ok: true as const, spec: preferred }
+    : selectModel(settings, flags, (spec) => opts.credentialOf(spec).ok, opts.catalog);
+  let spec: ModelSpec;
+  if (selected.ok) spec = selected.spec;
+  else {
+    const missingAll = selected.reason.startsWith("no model has a credential");
+    if (!missingAll || !interactive) {
+      throw new Error(missingAll ? describeUnauthenticatedScript(opts.catalog) : selected.reason);
+    }
+    const fallback = selectModel(settings, flags, () => true, opts.catalog);
+    if (!fallback.ok) throw new Error(fallback.reason);
+    spec = fallback.spec;
+  }
+  const credential = opts.credentialOf(spec);
+  if (!credential.ok && !interactive) {
+    throw new Error(credential.reason.startsWith("no credential for ")
+      ? missingCredentialMessage(spec, explicit || saved !== undefined, opts.catalog) : credential.reason);
+  }
+  const explicitEffort = asThinkingLevel(opts.args.thinking), requestedEffort = explicitEffort ?? parsedModel?.thinking;
+  if (opts.args.thinking && (!explicitEffort || !supportedThinkingLevels(spec).includes(explicitEffort))) {
+    throw new Error(`thinking ${opts.args.thinking} is not supported by ${modelKey(spec)}; supported: ${supportedThinkingLevels(spec).join(", ")}`);
+  }
+  const providerConfig: ProviderConfig = {
+    spec, maxTokens: outputTokenBudget(spec),
+    effort: clampThinkingLevel(spec, requestedEffort ?? asThinkingLevel(priorCursor?.thinking) ??
+      settings.modelThinkingLevels?.[modelKey(spec)] ?? opts.fallback?.effort ?? asThinkingLevel(settings.defaultThinking) ??
+      asThinkingLevel(settings.thinking) ?? DEFAULT_PROVIDER.effort),
+    thinkingDisplay: opts.fallback?.thinkingDisplay ?? DEFAULT_PROVIDER.thinkingDisplay,
+  };
+  const restoring = saved ?? spec;
+  const restoringCredential = saved === undefined ? credential : opts.credentialOf(restoring);
+  const oauth = (model: ModelSpec, got: Resolved) => got.ok && storedIsOAuth(opts.auth, model.provider) && opts.args.apiKey.length === 0;
+  const session = createSessionFor({
+    ...opts,
+    system: resources.system,
+    extensions: resources.extensions,
+    workspace: priorCursor?.workspace ?? opts.workspace,
+    blobDir: priorCursor?.blob_dir ?? (priorCursor?.workspace && priorCursor.workspace !== opts.workspace
+      ? statePaths(priorCursor.workspace, opts.args.stateDir).blobs : opts.blobDir),
+    providerConfig: { ...providerConfig, spec: restoring, maxTokens: outputTokenBudget(restoring) },
+    credential: restoringCredential,
+    ...(oauth(restoring, restoringCredential) ? { oauth: true } : {}),
+  });
+  await session.start();
+  if (resources.extensions.loaded.length || session.config.frozen.tools.some(tool =>
+    typeof tool === "object" && tool !== null && "name" in tool && typeof tool.name === "string" && unknownToolNames([tool.name]).length)) {
+    await session.reloadResources({ system: resources.system, tools: visibleSchemas(opts.args, resources.extensions) });
+  }
+  if (restoring.id !== spec.id || restoring.provider !== spec.provider) {
+    await session.switchModel(createProvider(providerConfig, credential.ok ? credential.key : "", retryHandler(opts.io),
+      { ...(oauth(spec, credential) ? { oauth: true } : {}), ...(opts.effects ? { effects: opts.effects } : {}) }));
+    opts.io.say(opts.io.palette.yellow(`  switched ${restoring.id} → ${spec.id} at a model checkpoint`));
+  }
+  resources.ui.settings = { ...resources.ui.settings, thinking: providerConfig.effort,
+    ...(opts.args.modelsExplicit || opts.args.models ? { scopedModels: splitModelPatterns(opts.args.models) } : {}) };
+  if (resources.ui.settings.scopedModels) for (const warning of scopedModels(resources.ui.settings.scopedModels, opts.catalog).diagnostics) opts.io.say(`  ${warning}`);
+  return { session, priorCursor, providerConfig, credential, workspace: session.config.tools.root,
+    blobDir: session.config.blobDir ?? opts.blobDir, system: session.config.frozen.system, resources };
+}
+
 export async function startup(args: Args): Promise<App> {
+  if (args.extensionArgv && (args.listModels || args.modelsCommand || args.configCommand)) rejectUnknownFlag("--" + Object.keys(args.extensionInputs ?? {})[0]);
   const C = createPalette(colorEnabled());
-  const printMode = isPrintMode(args);
+  let printMode = isPrintMode(args);
   const jsonMode = isJsonMode(args);
-  if ((args.mode ?? "").length > 0 && args.mode !== "json") {
-    console.error(`unknown --mode ${args.mode} (supported: json)`);
+  if ((args.mode ?? "").length > 0 && args.mode !== "json" && args.mode !== "text") {
+    console.error(`unknown --mode ${args.mode} (supported: text, json)`);
     process.exit(1);
   }
-  const divert = printMode || jsonMode;
+  let divert = printMode || jsonMode;
   const io: AppIO = {
     palette: C,
     say: (line) => (divert ? console.error(line) : console.log(line)),
@@ -943,6 +1125,11 @@ export async function startup(args: Args): Promise<App> {
         }
       : {}),
   };
+  const refreshOutputMode = () => {
+    printMode = isPrintMode(args); divert = printMode || jsonMode;
+    if (printMode && !jsonMode) io.answer = text => { process.stdout.write(text.endsWith("\n") ? text : `${text}\n`); };
+    else delete io.answer;
+  };
   const effects = processEffects();
 
   const authRead = await readJsonFile<AuthFile>(authPath());
@@ -955,12 +1142,13 @@ export async function startup(args: Args): Promise<App> {
       io.say(C.dim("  fetches models.dev into ~/.xeno/models.json; startup never does this."));
       process.exit(0);
     }
+    if (args.offline || process.env["XENO_OFFLINE"] === "1") throw new Error("--offline prevents catalog refresh");
     const result = await runModelsRefresh({
       fetch: globalThis.fetch,
-      write: writeModelsFile,
+      write: writeCatalogCache,
     });
     if (result.ok) {
-      io.say(`  added ${result.added}, changed ${result.changed} (${result.count} total) → ${modelsPath()}`);
+      io.say(`  added ${result.added}, changed ${result.changed} (${result.count} total) → ${catalogCachePath()}`);
       process.exit(0);
     } else {
       io.say(C.yellow(`  ${result.reason}`));
@@ -970,17 +1158,16 @@ export async function startup(args: Args): Promise<App> {
   }
 
   // File only. Passing fetch here would make the test of D16 un-runnable.
-  const userFile = await readModelsText();
-  const loaded = loadCatalog({ userText: userFile.text });
+  const loaded = loadCatalog(await readModelSources());
   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)) {
+    const query = args.modelSearch?.toLowerCase();
+    for (const group of groupedModels(query ? catalog.filter(model => [modelKey(model), model.name].some(text => { let at=0; for(const char of text.toLowerCase()) if(char===query[at])at++; return at===query.length; })) : catalog)) {
       io.say(C.bold(group.provider));
       for (const spec of group.models) {
         const got = credentialOf(spec);
@@ -992,18 +1179,6 @@ export async function startup(args: Args): Promise<App> {
     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
@@ -1031,139 +1206,81 @@ export async function startup(args: Args): Promise<App> {
     }
   }
 
-  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.
-      }
-    }
+  await prepareExtensionPackages(args,workspace);
+  const trust = await projectTrust(workspace, args.approve);
+  let loadProjectSettings = trust.trusted;
+  if (args.configCommand) {
+    if (!stdinIsTty() || !stdoutIsTty()) {
+      const index = await discoverResources({ ...args, workspace, trusted: loadProjectSettings });
+      for (const entry of index.entries) io.say(`${entry.enabled ? "[x]" : "[ ]"} ${entry.kind} ${entry.scope}${entry.package?" · "+entry.package.source:""} ${entry.path}`);
+    } else await runResourceConfig({ ...args, workspace, trusted: loadProjectSettings });
+    process.exit(0);
   }
+  const hasProjectResources = (await Promise.all(["settings.json", "keybindings.json", "skills", "prompts", "themes", "extensions"].map(name => stat(join(workspace, ".xeno", name)).then(() => true, () => false)))).some(Boolean);
+  if (!args.help && hasProjectResources && args.approve === undefined && !trust.saved && trust.policy === "ask" && isInteractiveSession(args)) loadProjectSettings = await pickProjectTrust(workspace);
+  if (hasProjectResources && !loadProjectSettings) io.say(C.dim("  Project resources not loaded (project is not trusted). /trust changes resource trust; tool permissions are separate."));
 
-  const uiLoaded = await loadUiResources({
+  // Resolve the resource owner before factories run. Parsing flags must not load a different cwd first.
+  let resourceWorkspace = workspace;
+  const prepareFlags = (args.extensionArgv && args.resume !== true) || args.help;
+  if (prepareFlags) {
+    const target = args.logDir || args.session || args.forkFrom || (typeof args.resume === "string" ? args.resume : undefined);
+    let resourceLog: string | undefined;
+    if (target) { const found = await findSessionByPrefix(workspace, target, sessionDirFor(args, workspace)); if (found.ok) resourceLog = found.session.path; }
+    else if (args.sessionId) resourceLog = join(sessionsDir(workspace, sessionDirFor(args, workspace)), args.sessionId);
+    else if (args.continueLatest) resourceLog = (await listSessions(workspace, sessionDirFor(args, workspace), Infinity)).sessions.find(session => session.ok)?.path;
+    if (resourceLog) resourceWorkspace = (await readCursor(resourceLog))?.workspace ?? workspace;
+  }
+  const preparedResources = prepareFlags
+    ? { workspace: resourceWorkspace, value: await loadSessionResources(args, resourceWorkspace, io, resourceWorkspace === workspace ? loadProjectSettings : undefined) } : undefined;
+  if (args.help) { printCliHelp(preparedResources?.value.extensions.flags); await preparedResources?.value.extensions.dispose(); process.exit(0); }
+  refreshOutputMode();
+  const uiLoaded = preparedResources ? undefined : await loadUiResources({
+    ...args,
     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());
+  for (const line of uiLoaded?.diagnostics ?? []) io.say(C.yellow(`  ${line}`));
+  const ui = preparedResources?.value.ui ?? toUiState(uiLoaded!, colorEnabled());
+  const mergedSettings = ui.settings;
   const scopedFromFlag = splitModelPatterns(args.models);
-  if (scopedFromFlag.length > 0) {
+  if (args.modelsExplicit || 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 paths = statePaths(workspace, args.stateDir);
-  const sessionDir = (args.sessionDir ?? "").length > 0 ? args.sessionDir : args.stateDir !== undefined ? paths.sessions : undefined;
-  const sessionPick =
-    (args.session ?? "").length > 0
-      ? args.session
-      : typeof args.resume === "string"
-        ? args.resume
-        : undefined;
+  const sessionDir = sessionDirFor(args, workspace);
+  let sessionOpts: ResolveLogOpts = {
+    ...(args.logDir ? { explicit: resolve(args.logDir) } : {}),
+    fresh: args.fresh,
+    ...(args.continueLatest === undefined ? {} : { continueLatest: args.continueLatest }),
+    ...(args.noSession === undefined ? {} : { noSession: args.noSession }),
+    ...(args.session === undefined ? {} : { session: args.session }),
+    ...(args.sessionId === undefined ? {} : { sessionId: args.sessionId }),
+    ...(args.resume === undefined ? {} : { resume: args.resume }),
+    ...(args.forkFrom === undefined ? {} : { forkFrom: args.forkFrom }),
+    ...(sessionDir === undefined ? {} : { sessionDir }),
+  };
   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);
+    if (planSessionEntry(sessionOpts).kind === "select") {
+      if (printMode || jsonMode || !stdinIsTty() || !stdoutIsTty()) {
+        throw new Error("--resume needs an interactive terminal. Pass -r <id> or --session <id> instead");
       }
-      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;
+      const picked = await pickStartupSession({ workspace, style: ui.style, say: io.say, keymap: ui.keymap,
+        ...(sessionDir === undefined ? {} : { sessionDir }) });
+      if (picked === null) { io.say(C.dim("No session selected")); process.exit(0); }
+      sessionOpts = { explicit: picked };
     }
+    const resolved = await resolveLogDir(workspace, sessionOpts);
+    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
@@ -1172,64 +1289,27 @@ export async function startup(args: Args): Promise<App> {
   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);
+  // Resource ownership follows the resolved session workspace. openSessionFor
+  // loads and freezes it once; explicit reloads checkpoint a changed prefix (D6).
   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);
-
+  let opened: Awaited<ReturnType<typeof openSessionFor>>;
   try {
-    await session.start();
+    opened = await openSessionFor({
+      args, workspace, logDir, blobDir, io, askSlot, catalog, auth, credentialOf, effects,
+      settings: mergedSettings, modelFlags: { model: args.model, provider: args.provider }, projectTrusted: loadProjectSettings,
+      ...(preparedResources ? { preparedResources } : {}),
+      interactive: isInteractiveSession(args),
+    });
   } 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 { session, priorCursor, providerConfig, credential } = opened;
+  refreshOutputMode();
 
   const sessionName = args.sessionName;
   if (sessionName !== undefined && sessionName.length > 0) {
@@ -1239,17 +1319,19 @@ export async function startup(args: Args): Promise<App> {
     }
   }
 
-  printBanner(args, io, {
-    workspace, logDir, providerConfig, credential, loadedContext, session, priorCursor, catalog,
-    keymap: ui.keymap,
-    skills: [...slash.skills.keys()],
-    prompts: [...slash.prompts.keys()],
+  if (opened.resources.ui.settings.quietStartup !== true || args.verbose) printBanner(args, io, {
+    workspace: opened.workspace, logDir, providerConfig, credential, loadedContext: opened.resources.loadedContext, session, priorCursor, catalog,
+    keymap: opened.resources.ui.keymap,
+    skills: [...opened.resources.slash.skills.keys()],
+    prompts: [...opened.resources.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,
+    args, session, workspace: opened.workspace, logDir, blobDir: opened.blobDir, system: opened.system, providerConfig, credential,
+    auth, effects, loadedContext: opened.resources.loadedContext, credentialOf, catalog, io, askSlot,
+    ui: opened.resources.ui, slash: opened.resources.slash, resources: opened.resources.index, projectTrusted: opened.resources.trusted,
+    extensions: opened.resources.extensions,
   };
 }
 
@@ -1321,3 +1403,53 @@ function printBanner(
   }
   io.say("");
 }
+
+export function printCliHelp(flags?: ReadonlyMap<string, ExtensionFlag>): void {
+      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] [--session-id id] [--version|-v]\n" +
+          "            [models --refresh]\n" +
+          "            [install|remove <source>... [--local]] [update [source] [--extensions]] [list]\n" +
+          "            [config [--local]] [--export session [output.html]] [--offline]\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>] [--use-theme name] [--no-themes] [--thinking level] [--models patterns]\n" +
+          "            [--skill <path>] [--no-skills]\n" +
+          "            [--prompt-template <path>] [--no-prompt-templates]\n" +
+          "            [--extension <path>] [--no-extensions] [--extension-flag name=value]\n" +
+          "            [--mode text|json] [--tui-mode regular|fullscreen] [--verbose]\n" +
+          "            [-p <prompt>] [prompt...]\n\n" +
+          "  Starts a new session by default; --fresh is an explicit alias. Nothing is deleted.\n" +
+          "  -c continues the newest (or starts one); -r opens the session picker.\n" +
+          "  --session / -r <id> pick one (unique prefix only). Resume restores its model;\n" +
+          "  an explicit --model switches at a checkpoint before the next turn.\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: " + COMMANDS.map(command => "/" + command.name).join("  ") + "\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" +
+          "  --state-dir <dir> keeps snapshots, observations and sessions out of the workspace.\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).",
+      );
+  if (flags?.size) console.log("\nExtension CLI flags:\n" + [...flags].map(([name, flag]) => `  --${name}${flag.type === "string" ? " <value>" : ""}  ${flag.description ?? ""}`).join("\n"));
+}