@visual-z/xeno 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # xeno changelog
 
+## 0.2.1 — 2026-09-30
+
+- Handle Ctrl+C and termination signals while startup awaits resources or workspace snapshots, restoring the terminal before exit.
+- Show the current phase during slow initialization and retain early input until Pi's editor or startup selector owns it.
+- Preserve pasted control characters, Unicode input and terminal state across startup failures and selector transitions.
+
 ## 0.2.0 — 2026-09-30
 
 - Restore saved model identity on session entry; cross-model history moves through a mechanical checkpoint.

package/README.md

@@ -17,7 +17,7 @@ is ever summarized by a model, and nothing is ever rewritten in place.
 messages[]                             frozen system prefix + handoff + this node's events
 ```
 
-Version **0.2.0**. The on-disk session format will still change; `0.x` is that
+Version **0.2.1**. The on-disk session format will still change; `0.x` is that
 statement. Published as `@visual-z/xeno`; the license is `UNLICENSED` (readable and installable, no reuse granted).
 
 ## Install

package/docs/install.md

@@ -68,6 +68,11 @@ Each invocation starts a new session. `xeno -c` continues the newest one;
 and nothing is deleted. Resume restores the saved model. An explicit
 `--model` switches at a checkpoint while keeping the original log intact.
 
+Startup loads resources and establishes a workspace snapshot before the editor
+opens. Slow initialization shows its current stage; Ctrl+C cancels startup and
+restores the terminal. Snapshots cover the selected workspace, so start inside
+the intended project or pass `--workspace <path>`.
+
 ## Credentials
 
 Resolution order, first match wins:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visual-z/xeno",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "UNLICENSED",
   "type": "module",
   "description": "Segmented append-only agent log with pure context and handoff projections",

package/src/apps/cli.ts

@@ -13,18 +13,16 @@
  */
 
 import {
-  parseArgs, startup, readPipedStdin, mergePrintPrompt, silenceTtyEarly, printCliHelp,
+  parseArgs, startup, readPipedStdin, mergePrintPrompt, isInteractiveSession, printCliHelp,
 } from "./startup.ts";
+import { createStartupInput } from "./startup-input.ts";
 import { runPrompt, runRepl } from "./shell.ts";
 import { runPackageCommand } from "../runtime/package-manager.ts";
 import { exportHtmlFile } from "./export-cli.ts";
 
 const args = parseArgs(process.argv.slice(2), { deferExtensions: true });
-// Before startup reads auth, scans context files and prints the header:
-// in cooked mode the tty would echo anything typed during that window
-// straight into the banner.
-const restoreTty = silenceTtyEarly({ interactive: !args.packageCommand && !args.help && !args.version && !args.exportFile && !args.print && !args.prompt });
-process.once("exit", restoreTty);
+const input = createStartupInput({ interactive: isInteractiveSession(args) && !args.packageCommand && !args.version && !args.exportFile && !args.listModels && !args.modelsCommand });
+process.once("exit", input.restore);
 try {
   if (args.help && (args.packageCommand || args.configCommand || args.exportFile || args.version || args.listModels || args.modelsCommand)) {
     printCliHelp();
@@ -44,22 +42,23 @@ try {
     catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = controller.signal.aborted ? 130 : 1; }
     finally { process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
   } else {
-    const app = await startup(args);
+    const app = await startup(args, input);
     if (args.print) {
       // With a prompt already given, stdin is optional context: wait briefly for it.
       args.prompt = mergePrintPrompt(args.prompt,
         await readPipedStdin(process.stdin, args.prompt.length > 0 ? { firstByteMs: 3_000 } : {}));
     }
     if (args.prompt) {
-      restoreTty();
+      input.restore();
       await runPrompt(app, args.prompt);
     } else {
-      await runRepl(app, restoreTty);
+      input.phase("Loading conversation");
+      await runRepl(app, input.handoff);
     }
   }
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1;
 } finally {
-  process.off("exit", restoreTty);
-  restoreTty();
+  process.off("exit", input.restore);
+  input.restore();
 }

package/src/apps/project-trust.ts

@@ -33,7 +33,7 @@ export class TrustSelector extends SelectList {
       .map(line => truncateToWidth(line, width, ""));
   }
 }
-export async function pickProjectTrust(workspace: string): Promise<boolean> {
+export async function pickProjectTrust(workspace: string, handoff?: () => void): Promise<boolean> {
   const decision = await projectTrust(workspace);
   installBindings((await loadUiResources({ workspace, trusted: false })).keymap.byAction);
   const screen = createInteractiveTui();
@@ -42,7 +42,7 @@ export async function pickProjectTrust(workspace: string): Promise<boolean> {
   try {
     const choice = await new Promise<string | null>(resolve => {
       select.onInput = data => { const state = select.acceptInput(data); if (state.cancelled) resolve(null); else if (state.confirmed) resolve(state.confirmed.value); screen.requestRender(); };
-      screen.start();
+      handoff?.(); screen.start();
     });
     return choice === null ? false : applyTrustChoice(workspace, choice as TrustChoice);
   } finally { await screen.terminal.drainInput(); screen.stop(); }

package/src/apps/resource-browser.ts

@@ -54,7 +54,7 @@ export class ResourceBrowser extends SelectList {
 }
 
 /** Standalone configuration does not allocate a conversation or require a model credential. */
-export async function runResourceConfig(options: ResourceOptions): Promise<void> {
+export async function runResourceConfig(options: ResourceOptions, handoff?: () => void): Promise<void> {
   const index = await discoverResources(options);
   const ui = await loadUiResources(options, index);
   const screen = createInteractiveTui();
@@ -69,7 +69,7 @@ export async function runResourceConfig(options: ResourceOptions): Promise<void>
         if (browser.acceptInput(data).cancelled) resolve();
         screen.requestRender();
       }).catch(error => { browser.notice = String(error); screen.requestRender(); }); };
-      screen.start();
+      handoff?.(); screen.start();
     });
   } finally { await screen.terminal.drainInput(); screen.stop(); }
 }

package/src/apps/session-picker.ts

@@ -22,7 +22,7 @@ export async function pickStartupSession(opts: {
   style: Style;
   say: (line: string) => void;
   keymap?: Keymap;
-}): Promise<string | null> {
+}, handoff?: () => void): Promise<string | null> {
   const root = { path: sessionsDir(opts.workspace, opts.sessionDir), workspace: opts.workspace };
   await registerSessionRoot(root).catch(error => opts.say(String(error)));
   const screen = createInteractiveTui();
@@ -40,7 +40,7 @@ export async function pickStartupSession(opts: {
         else if (state.confirmed) resolve(state.confirmed.value);
         else screen.requestRender();
       }).catch(error => { opts.say(String(error)); }); };
-      screen.start();
+      handoff?.(); screen.start();
       void select.load().then(async () => {
         if (select.scope === "current" && !select.sessionCount && !select.notice && (await sessionRoots(root)).length === 1) {
           opts.say("No sessions to resume"); resolve(null);

package/src/apps/startup-input.ts

@@ -0,0 +1,94 @@
+/** Startup owns raw input until a Pi screen can own it (D19). */
+import { StdinBuffer } from "../vendor/pi-tui/stdin-buffer.ts";
+import { isKeyRelease, matchesKey } from "../vendor/pi-tui/keys.ts";
+import { resolveEscapeTimeoutMs } from "../vendor/pi-tui/terminal.ts";
+
+type StartupStdin = Pick<NodeJS.ReadStream, "isTTY" | "isRaw" | "setRawMode" | "setEncoding" | "on" | "off" | "resume" | "pause" | "unshift">;
+export interface StartupInput {
+  phase(name: string): void;
+  /** Pause, restore the shell's mode and replay held bytes to the next input owner. */
+  handoff(): void;
+  /** Final cleanup discards unsubmitted input instead of leaking it to the shell. */
+  restore(): void;
+  runWithTerminal<T>(run: (handoff: () => void) => Promise<T>): Promise<T>;
+}
+
+export function createStartupInput(opts: {
+  interactive: boolean;
+  stdin?: StartupStdin;
+  signals?: NodeJS.EventEmitter;
+  report?: (message: string) => void;
+  exit?: (code: number) => void;
+}): StartupInput {
+  const stdin = opts.stdin ?? process.stdin;
+  if (!opts.interactive || stdin.isTTY !== true) return {
+    phase() {}, handoff() {}, restore() {}, runWithTerminal: run => run(() => {}),
+  };
+  const signals = opts.signals ?? process;
+  const report = opts.report ?? (message => console.error(message));
+  const exit = opts.exit ?? (code => process.exit(code));
+  const wasRaw = stdin.isRaw === true;
+  let active = false, closed = false, announced = false;
+  let phase = "Reading configuration";
+  let pending: string[] = [];
+  let parser: StdinBuffer | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const release = () => {
+    if (!active) return;
+    active = false;
+    clearTimeout(timer);
+    stdin.pause();
+    stdin.off("data", receive);
+    signals.off("SIGINT", interrupt); signals.off("SIGTERM", terminate); signals.off("SIGHUP", hangup);
+    parser?.destroy(); parser = undefined;
+    stdin.setRawMode(wasRaw);
+  };
+  const restore = () => { closed = true; release(); pending = []; };
+  const cancel = (code: number) => {
+    if (!active) return;
+    restore();
+    if (code === 130) report("Startup cancelled.");
+    exit(code);
+  };
+  const interrupt = () => cancel(130), terminate = () => cancel(143), hangup = () => cancel(129);
+  const receive = (data: string) => {
+    // Keep original chunks, including partial escapes/pastes, for Pi's own decoder.
+    // The temporary parser only recognizes cancellation outside bracketed paste.
+    pending.push(data);
+    parser?.process(data);
+  };
+  const announce = () => { if (active) { announced = true; report(`  Starting xeno: ${phase} (Ctrl+C to cancel)`); } };
+  const capture = () => {
+    if (closed || active) return;
+    active = true; announced = false;
+    parser = new StdinBuffer({ escapeTimeout: resolveEscapeTimeoutMs() });
+    parser.on("data", (data: string) => { if (!isKeyRelease(data) && matchesKey(data, "ctrl+c")) interrupt(); });
+    stdin.setEncoding("utf8");
+    stdin.on("data", receive);
+    signals.on("SIGINT", interrupt); signals.on("SIGTERM", terminate); signals.on("SIGHUP", hangup);
+    stdin.setRawMode(true);
+    stdin.resume();
+    // Assumed UI grace period, not a work deadline: fast starts stay quiet;
+    // a slow stage remains visible without truncating or abandoning its work.
+    timer = setTimeout(announce, 750);
+    timer.unref();
+  };
+  const handoff = () => {
+    if (!active) return;
+    release();
+    const buffered = pending.join(""); pending = [];
+    if (buffered) stdin.unshift(buffered);
+  };
+  capture();
+  return {
+    phase(name) { if (name === phase) return; phase = name; if (announced) announce(); },
+    handoff, restore,
+    async runWithTerminal(run) {
+      // A selector can load settings/history before mounting. Keep owning input
+      // until its synchronous screen.start(), then reacquire only after stop().
+      try { return await run(handoff); }
+      finally { capture(); }
+    },
+  };
+}

package/src/apps/startup.ts

@@ -57,6 +57,7 @@ import { DEFAULT_CONTEXT_POLICY, isContextPolicy, type ContextPolicy } from "../
 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";
+import type { StartupInput } from "./startup-input.ts";
 
 export const SYSTEM_PROMPT = systemPromptFor(TOOL_SCHEMAS.map((tool) => tool.name));
 
@@ -346,32 +347,6 @@ function rejectUnknownFlag(flag: string): never {
   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[], options: { deferExtensions?: boolean; flags?: ReadonlyMap<string, ExtensionFlag> } = {}): Args {
   let selectedTheme: string | undefined;
   const args: Args = {
@@ -961,6 +936,7 @@ export function sessionDirFor(args: Args, workspace: string): string | undefined
 }
 
 type OpenSessionOptions = Omit<Parameters<typeof createSessionFor>[0], "providerConfig" | "credential" | "oauth" | "system"> & {
+  startupPhase?: (name: string) => void;
   catalog: readonly ModelSpec[];
   auth: AuthFile;
   credentialOf: (spec: ModelSpec) => Resolved;
@@ -1021,6 +997,7 @@ 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>>;
 }> {
+  opts.startupPhase?.("Reading session history");
   const recorded = await readCursor(opts.logDir);
   const priorCursor = recorded === null ? null : await recoverCut(opts.logDir, recorded);
   const workspace = priorCursor?.workspace ?? opts.workspace;
@@ -1029,6 +1006,7 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
     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();
+  opts.startupPhase?.("Loading session resources");
   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";
@@ -1042,6 +1020,7 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
   const explicit = flags.model.length > 0 || flags.provider.length > 0;
   const settings = opts.settings ?? {};
   const preferred = saved ?? opts.fallback?.spec;
+  opts.startupPhase?.("Resolving model credentials");
   const selected = !explicit && preferred !== undefined
     ? { ok: true as const, spec: preferred }
     : selectModel(settings, flags, (spec) => opts.credentialOf(spec).ok, opts.catalog);
@@ -1086,6 +1065,7 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
     credential: restoringCredential,
     ...(oauth(restoring, restoringCredential) ? { oauth: true } : {}),
   });
+  opts.startupPhase?.("Preparing workspace snapshot");
   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)) {
@@ -1103,7 +1083,8 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
     blobDir: session.config.blobDir ?? opts.blobDir, system: session.config.frozen.system, resources };
 }
 
-export async function startup(args: Args): Promise<App> {
+export async function startup(args: Args, input?: StartupInput): Promise<App> {
+  const withTerminal = <T>(run: (handoff: () => void) => Promise<T>): Promise<T> => input ? input.runWithTerminal(run) : run(() => {});
   if (args.extensionArgv && (args.listModels || args.modelsCommand || args.configCommand)) rejectUnknownFlag("--" + Object.keys(args.extensionInputs ?? {})[0]);
   const C = createPalette(colorEnabled());
   let printMode = isPrintMode(args);
@@ -1158,6 +1139,7 @@ export async function startup(args: Args): Promise<App> {
   }
 
   // File only. Passing fetch here would make the test of D16 un-runnable.
+  input?.phase("Loading model catalog");
   const loaded = loadCatalog(await readModelSources());
   for (const warning of loaded.warnings) io.say(C.yellow(`  ${warning}`));
   const catalog = loaded.models;
@@ -1187,6 +1169,7 @@ export async function startup(args: Args): Promise<App> {
    * It has to happen before model selection so a trusted `.xeno/settings.json`
    * can override the default model. Trust does not affect tools.
    */
+  input?.phase("Opening workspace");
   let workspace: string;
   try {
     workspace = await workspaceRoot(args.workspace);
@@ -1206,6 +1189,7 @@ export async function startup(args: Args): Promise<App> {
     }
   }
 
+  input?.phase("Preparing extensions and project settings");
   await prepareExtensionPackages(args,workspace);
   const trust = await projectTrust(workspace, args.approve);
   let loadProjectSettings = trust.trusted;
@@ -1213,11 +1197,11 @@ export async function startup(args: Args): Promise<App> {
     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 });
+    } else await withTerminal(handoff => runResourceConfig({ ...args, workspace, trusted: loadProjectSettings }, handoff));
     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 (!args.help && hasProjectResources && args.approve === undefined && !trust.saved && trust.policy === "ask" && isInteractiveSession(args)) loadProjectSettings = await withTerminal(handoff => pickProjectTrust(workspace, handoff));
   if (hasProjectResources && !loadProjectSettings) io.say(C.dim("  Project resources not loaded (project is not trusted). /trust changes resource trust; tool permissions are separate."));
 
   // Resolve the resource owner before factories run. Parsing flags must not load a different cwd first.
@@ -1231,6 +1215,7 @@ export async function startup(args: Args): Promise<App> {
     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;
   }
+  input?.phase("Loading session resources");
   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); }
@@ -1268,8 +1253,8 @@ export async function startup(args: Args): Promise<App> {
       if (printMode || jsonMode || !stdinIsTty() || !stdoutIsTty()) {
         throw new Error("--resume needs an interactive terminal. Pass -r <id> or --session <id> instead");
       }
-      const picked = await pickStartupSession({ workspace, style: ui.style, say: io.say, keymap: ui.keymap,
-        ...(sessionDir === undefined ? {} : { sessionDir }) });
+      const picked = await withTerminal(handoff => pickStartupSession({ workspace, style: ui.style, say: io.say, keymap: ui.keymap,
+        ...(sessionDir === undefined ? {} : { sessionDir }) }, handoff));
       if (picked === null) { io.say(C.dim("No session selected")); process.exit(0); }
       sessionOpts = { explicit: picked };
     }
@@ -1301,6 +1286,7 @@ export async function startup(args: Args): Promise<App> {
       settings: mergedSettings, modelFlags: { model: args.model, provider: args.provider }, projectTrusted: loadProjectSettings,
       ...(preparedResources ? { preparedResources } : {}),
       interactive: isInteractiveSession(args),
+      ...(input ? { startupPhase: input.phase } : {}),
     });
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);

package/src/runtime/oauth.ts

@@ -17,7 +17,7 @@ import { createServer, type Server } from "node:http";
 import { pollDeviceCode } from "./oauth-device.ts";
 
 /** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.2.0";
+export const XENO_VERSION = "0.2.1";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge