drexler 0.2.14 → 0.2.16

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.16
+
+- Added an interactive pet system: feed, play, work, praise, rest, vibe, name, and profile commands; persistent stats with offline decay; intern→analyst→associate→VP→MD rank ladder driven by lifetime deal accumulation; 90-second cooldowns per action with in-character rejection copy.
+- Adaptive pet UI: full animated panel on wide terminals (cols ≥ 112), bordered compact panel on medium terminals (≥ 48), one-line ticker surfacing the worst stat on tiny terminals.
+- Compact panel routes stats through the existing satirical level ladder (peak/good/ok/low/critical) instead of bare percentages so it matches the Deal Desk surface.
+- Pet save is now atomic (temp file + rename); dead-pet command guard prevents stat mutation during the death exit timer; frame interval pauses when the pet has died.
+- Hardened launch flow: validate CLI flags and config before the first-run API key prompt with reason-specific errors. Fatal handlers moved off the interactive path so Ink's signal-exit can restore the terminal cleanly.
+- Markdown link parser now balances parentheses, so URLs like `https://en.wikipedia.org/wiki/Foo_(bar)` parse correctly.
+- New informational commands: `/setup` prints config + API key source without leaking the key; `/update` prints upgrade instructions and refuses to run installs.
+- Transcript viewport enforces a hard row budget — oversized cards clip with an explicit `... N lines truncated — PageUp scrollback to read` hint; indicators report row counts in addition to item counts; scrollback keys work while a response is streaming.
+- Command palette Enter on bare argument-parent commands (`/theme`, `/model`, `/startup`, `/retry`, `/export`) now reopens the chooser instead of executing the base form; history navigation preserves the unsent draft.
+- Performance: collapsed duplicate width memos, hoisted divider/carpet constants, memoized StatBar, tightened the pet panel frame loop.
+
 ## 0.2.14
 
 - Added a startup Mood panel with a stable boot gauge, percentage-only loading row, and rotating mood-specific posture/detail copy.

package/README.md

@@ -64,11 +64,17 @@ Paste the key, hit return. Drexler saves it to `~/.config/drexler/config.json` (
 
 ## Update
 
+```bash
+bun update -g drexler --latest
+```
+
+If your Bun install does not have the package in its global lockfile, reinstall it instead:
+
 ```bash
 bun install -g drexler@latest
 ```
 
-Global installs replace the existing `drexler` package in Bun's global install location; they do not keep stacking duplicate app copies.
+Global updates replace the existing `drexler` package in Bun's global install location; they do not keep stacking duplicate app copies.
 
 ## Uninstall
 
@@ -85,6 +91,8 @@ rm -rf ~/.config/drexler   # optional: wipe stored key + settings
 
 Drexler runs as an Ink terminal UI when both stdin and stdout are TTYs. The normal launch shows one integrated startup panel with the mascot, tips, a **Mood** readout, and the **Drexler Deal Desk**. Short terminals automatically suppress oversized startup chrome so the chat stays usable.
 
+After startup, the pet UI adapts to the terminal instead of disappearing. Wide terminals show the animated **Drexler Pet Desk** as a right-side panel. Medium terminals show a compact pet panel below the Deal Desk. Tiny terminals show a one-line pet ticker so pet status remains visible without crushing the chat.
+
 The startup panel is designed to stay stable while it boots: the mascot loading bar and Mood gauge animate without changing width, greeting copy is held in a fixed slot, and the Mood and Deal Desk boxes stay aligned when the greeting wraps. After boot, Mood resolves into a rotating Drexler-flavored posture with a short satirical subtext line.
 
 The Deal Desk is intentionally not a frontier-model telemetry panel. It shows mood-shaped corporate nonsense like boardroom status, memo count, mandate, risk, fees, and counsel posture. Values rotate by mood and session so repeated moods still feel alive.
@@ -128,6 +136,14 @@ Keyboard notes:
 | `/clear`       | shred conversation history (system prompt pinned) |
 | `/exit`        | meeting adjourned                                |
 | `/synergy`     | run a rotating animated morale event             |
+| `/feed`        | feed Drexler a deal memo                         |
+| `/play`        | corporate synergy game with Drexler              |
+| `/work`        | Drexler grinds the deal pipeline                 |
+| `/praise`      | affirm Drexler's contributions                   |
+| `/rest`        | strategic nap                                    |
+| `/vibe`        | let Drexler choose his own adventure             |
+| `/name [name]` | view or assign Drexler's pet name                |
+| `/profile`     | print Drexler's personnel file                   |
 | `/model`       | show current model, or `/model 26b` to switch   |
 | `/theme`       | show/switch theme; append `save` to persist, e.g. `/theme midnight save` |
 | `/startup fast\|no-intro\|normal` | persist startup behavior for future launches |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drexler",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "CLI chat with Drexler, a corporate-executive AI persona built on OpenRouter Gemma 4 31B.",
   "license": "MIT",
   "author": "showOS",

package/src/commands.ts

@@ -1,7 +1,13 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, writeFileSync } from "node:fs";
 import { resolve as pathResolve } from "node:path";
-import { resolveModel } from "./config.ts";
+import {
+  getConfigPath,
+  getDrexlerVersion,
+  getResolvedConfigPath,
+  isValidApiKey,
+  resolveModel,
+} from "./config.ts";
 import type { Conversation } from "./conversation.ts";
 import { error, resetMarkedTheme } from "./renderer.ts";
 import { THEME_NAMES, type Config, type ThemeName } from "./types.ts";
@@ -17,6 +23,14 @@ export type CommandAction =
   | { type: "exit"; message?: string }
   | { type: "regenerate"; instruction?: string; removedAssistant: boolean };
 
+export type CommandGroup =
+  | "directives"
+  | "themes"
+  | "models"
+  | "startup"
+  | "retry"
+  | "export";
+
 interface CommandContext {
   conversation: Conversation;
   config: Config;
@@ -33,6 +47,14 @@ const HELP_TEXT = `New memo to staff! Drexler permit following directives:
   /clear         - shred all documents (reset history)
   /exit          - meeting adjourned
   /synergy       - SYNERGY!
+  /feed          - feed Drexler a deal memo
+  /play          - corporate synergy game with Drexler
+  /work          - Drexler grinds the deal pipeline
+  /praise        - affirm Drexler's contributions
+  /rest          - Drexler takes a strategic nap
+  /vibe          - let Drexler choose his own adventure
+  /name [name]   - view or assign Drexler's pet name
+  /profile       - print Drexler's personnel file
   /model         - show or switch model (e.g. /model 26b)
   /theme         - show or switch theme (${THEME_NAMES.join(", ")})
   /startup       - persist startup mode (fast, no-intro, normal)
@@ -46,7 +68,9 @@ const HELP_TEXT = `New memo to staff! Drexler permit following directives:
   /export <fmt> [path] - export as md, txt, json, or html
   /save [path]   - archive conversation to markdown file
   /save-last [path] - save Drexler's last response
-  /copy-last     - copy Drexler's last response to clipboard`;
+  /copy-last     - copy Drexler's last response to clipboard
+  /setup         - show config + API key source
+  /update        - show upgrade instructions`;
 
 const WHITESPACE_RE = /\s+/;
 
@@ -54,27 +78,38 @@ export interface SlashCommand {
   readonly name: string;
   readonly description: string;
   readonly hint?: string;
+  readonly group?: CommandGroup;
 }
 
 export const COMMAND_PALETTE: ReadonlyArray<SlashCommand> = [
-  { name: "/help", description: "Show directives" },
-  { name: "/clear", description: "Reset conversation" },
-  { name: "/exit", description: "Adjourn meeting" },
-  { name: "/synergy", description: "SYNERGY!" },
-  { name: "/model", description: "Show or switch model" },
-  { name: "/theme", description: "Show or switch theme" },
-  { name: "/startup", description: "Persist startup mode" },
-  { name: "/history", description: "Message + token count" },
-  { name: "/regenerate", description: "Re-roll last response" },
-  { name: "/redo", description: "Alias for regenerate" },
-  { name: "/retry", description: "Retry terse or brutal" },
-  { name: "/expand", description: "Print last response" },
-  { name: "/quote", description: "Quote last response" },
-  { name: "/search", description: "Search transcript" },
-  { name: "/export", description: "Export md, txt, json, or html" },
-  { name: "/save", description: "Archive conversation as markdown" },
-  { name: "/save-last", description: "Save last Drexler response" },
-  { name: "/copy-last", description: "Copy last response" },
+  { name: "/help", description: "Show directives", group: "directives" },
+  { name: "/clear", description: "Reset conversation", group: "directives" },
+  { name: "/exit", description: "Adjourn meeting", group: "directives" },
+  { name: "/synergy", description: "SYNERGY!", group: "directives" },
+  { name: "/feed", description: "Feed Drexler a deal memo", group: "directives" },
+  { name: "/play", description: "Play with Drexler", group: "directives" },
+  { name: "/work", description: "Drexler grinds deals", group: "directives" },
+  { name: "/praise", description: "Affirm Drexler", group: "directives" },
+  { name: "/rest", description: "Drexler takes a strategic nap", group: "directives" },
+  { name: "/vibe", description: "Drexler chooses his own adventure", group: "directives" },
+  { name: "/name", description: "Issue or view Drexler's pet name", group: "directives" },
+  { name: "/profile", description: "Print Drexler's personnel file", group: "directives" },
+  { name: "/model", description: "Show or switch model", group: "models" },
+  { name: "/theme", description: "Show or switch theme", group: "themes" },
+  { name: "/startup", description: "Persist startup mode", group: "startup" },
+  { name: "/history", description: "Message + token count", group: "directives" },
+  { name: "/regenerate", description: "Re-roll last response", group: "directives" },
+  { name: "/redo", description: "Alias for regenerate", group: "directives" },
+  { name: "/retry", description: "Retry terse or brutal", group: "retry" },
+  { name: "/expand", description: "Print last response", group: "directives" },
+  { name: "/quote", description: "Quote last response", group: "directives" },
+  { name: "/search", description: "Search transcript", group: "directives" },
+  { name: "/export", description: "Export md, txt, json, or html", group: "export" },
+  { name: "/save", description: "Archive conversation as markdown", group: "directives" },
+  { name: "/save-last", description: "Save last Drexler response", group: "directives" },
+  { name: "/copy-last", description: "Copy last response", group: "directives" },
+  { name: "/setup", description: "Show config + key source", group: "directives" },
+  { name: "/update", description: "Show upgrade instructions", group: "directives" },
 ];
 
 const THEME_PALETTE_COPY: Record<
@@ -265,6 +300,21 @@ export function filterPaletteByPrefix(
   );
 }
 
+const ARGUMENT_BASE_NAMES: ReadonlySet<string> = new Set(
+  ARGUMENT_PALETTE.map((g) => g.command),
+);
+
+/**
+ * True if `name` is a bare command (no space) that has child argument
+ * suggestions. Palette Enter on such a name should NOT execute — it should
+ * open the chooser.
+ */
+export function isArgumentParentCommand(name: string): boolean {
+  if (!name.startsWith("/")) return false;
+  if (name.includes(" ")) return false;
+  return ARGUMENT_BASE_NAMES.has(name.toLowerCase());
+}
+
 export function isSlash(input: string): boolean {
   return input.startsWith("/");
 }
@@ -319,6 +369,19 @@ export function dispatch(input: string, ctx: CommandContext): CommandAction {
       );
       return { type: "continue" };
 
+    case "feed":
+    case "play":
+    case "work":
+    case "praise":
+    case "rest":
+    case "vibe":
+    case "name":
+    case "profile":
+      ctx.print(
+        "Drexler pet directives require the interactive deal desk. Launch Drexler in a TTY.",
+      );
+      return { type: "continue" };
+
     case "model":
       handleModel(args, ctx);
       return { type: "continue" };
@@ -407,6 +470,14 @@ export function dispatch(input: string, ctx: CommandContext): CommandAction {
       return { type: "continue" };
     }
 
+    case "setup":
+      handleSetup(ctx);
+      return { type: "continue" };
+
+    case "update":
+      handleUpdate(ctx);
+      return { type: "continue" };
+
     default:
       ctx.print(
         "Drexler not recognize that corporate directive. Try /help.",
@@ -869,3 +940,39 @@ function handleTheme(args: string[], ctx: CommandContext): CommandAction {
     ? { type: "continue", persistConfig: { theme: requested } }
     : { type: "continue" };
 }
+
+function handleSetup(ctx: CommandContext): void {
+  const envValid = isValidApiKey(process.env.OPENROUTER_API_KEY);
+  const target = getResolvedConfigPath() ?? getConfigPath();
+  const keySourceLabel = envValid
+    ? "(env: OPENROUTER_API_KEY)"
+    : isValidApiKey(ctx.config.apiKey)
+      ? `(config file: ${target})`
+      : "(missing — first-run prompt will request one)";
+
+  const lines = [
+    "Drexler setup ledger:",
+    `  version       : ${getDrexlerVersion()}`,
+    `  config file   : ${target}`,
+    `  API key       : ${keySourceLabel}`,
+    `  model         : ${ctx.config.model}`,
+    `  theme         : ${currentThemeName(ctx.config)}`,
+    `  startup mode  : ${currentStartupMode(ctx.config)}`,
+    `  persona file  : ${ctx.config.personaPath}`,
+  ];
+  ctx.print(lines.join("\n"));
+}
+
+function handleUpdate(ctx: CommandContext): void {
+  const lines = [
+    `Drexler upgrade dossier (drexler v${getDrexlerVersion()}):`,
+    "",
+    "  bun update:    bun update -g drexler --latest",
+    "  bun reinstall: bun install -g drexler@latest",
+    "  npm:           npm install -g drexler@latest",
+    "  pnpm:          pnpm add -g drexler@latest",
+    "",
+    "Drexler will not run installs. Type the command into your shell.",
+  ];
+  ctx.print(lines.join("\n"));
+}

package/src/config.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import {
   chmod,
   lstat,
@@ -16,6 +16,53 @@ import { MODEL_FALLBACK, MODEL_PRIMARY, THEME_NAMES } from "./types.ts";
 
 const DEFAULT_MAX_HISTORY = 50;
 
+export function getDrexlerVersion(): string {
+  try {
+    const pkgPath = join(import.meta.dir, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export function getConfigPath(): string {
+  return configPath();
+}
+
+export function getLegacyConfigPath(): string {
+  return legacyConfigPath();
+}
+
+export function getResolvedConfigPath(): string | null {
+  const cp = configPath();
+  const lp = legacyConfigPath();
+  if (existsSync(cp)) return cp;
+  if (existsSync(lp)) return lp;
+  return null;
+}
+
+export type ApiKeySource = "env" | "config-file" | "missing";
+
+export class LaunchConfigError extends Error {
+  readonly reason:
+    | "model-alias"
+    | "persona-path"
+    | "config-unreadable"
+    | "api-key-empty";
+  readonly detail: Record<string, unknown>;
+  constructor(
+    reason: LaunchConfigError["reason"],
+    message: string,
+    detail: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "LaunchConfigError";
+    this.reason = reason;
+    this.detail = detail;
+  }
+}
+
 function getHome(): string {
   return process.env.HOME ?? process.env.USERPROFILE ?? homedir();
 }
@@ -75,6 +122,35 @@ export function defaultPersonaPath(): string {
   return resolve(import.meta.dir, "..", "prompts", "drexler.md");
 }
 
+async function validatePersonaFile(
+  inputPath: unknown,
+  label: string,
+): Promise<string> {
+  if (typeof inputPath !== "string" || inputPath.trim().length === 0) {
+    throw new LaunchConfigError(
+      "persona-path",
+      `Invalid ${label}: expected a regular .md file path.`,
+      { path: inputPath },
+    );
+  }
+  const resolved = resolve(inputPath);
+  // lstat (not stat) so symlinks pointing to non-.md targets cannot bypass
+  // the extension check via `ln -s /etc/passwd evil.md`.
+  const st = await lstat(resolved).catch(() => null);
+  if (
+    !st?.isFile() ||
+    st.isSymbolicLink() ||
+    !resolved.toLowerCase().endsWith(".md")
+  ) {
+    throw new LaunchConfigError(
+      "persona-path",
+      `Invalid ${label}: ${inputPath} (must be a regular .md file; symlinks rejected).`,
+      { path: inputPath },
+    );
+  }
+  return resolved;
+}
+
 export async function loadConfigFile(): Promise<Partial<Config>> {
   const cp = configPath();
   const lp = legacyConfigPath();
@@ -192,43 +268,38 @@ export async function ensureApiKey(opts?: {
   return apiKey;
 }
 
-export async function resolveConfig(argv: string[]): Promise<Config> {
+export interface LaunchStructural {
+  model: string;
+  personaPath: string;
+  theme?: ThemeName;
+  noIntro?: boolean;
+  fast?: boolean;
+  maxHistory: number;
+  fileCfg: Partial<Config>;
+}
+
+export async function validateLaunchConfig(
+  argv: string[],
+): Promise<LaunchStructural> {
   const flags = parseFlags(argv);
   const fileCfg = await loadConfigFile();
-  const envKey = process.env.OPENROUTER_API_KEY;
   const envModel = process.env.DREXLER_MODEL;
 
-  const apiKey = isValidApiKey(envKey)
-    ? envKey.trim()
-    : isValidApiKey(fileCfg.apiKey)
-    ? fileCfg.apiKey.trim()
-    : "";
-
-  if (!apiKey) {
-    throw new Error(
-      "API key missing. Run drexler interactively to set one, or export OPENROUTER_API_KEY.",
-    );
-  }
-
   const modelInput = flags.model ?? envModel ?? fileCfg.model ?? "31b";
-  const model = resolveModel(modelInput);
-
-  let personaPath: string;
-  if (flags.persona) {
-    const resolved = resolve(flags.persona);
-    // lstat (not stat) so symlinks pointing to non-.md targets cannot bypass
-    // the extension check via `ln -s /etc/passwd evil.md`.
-    const st = await lstat(resolved).catch(() => null);
-    if (!st?.isFile() || !resolved.toLowerCase().endsWith(".md")) {
-      throw new Error(
-        `Invalid --persona: ${flags.persona} (must be a regular .md file; symlinks rejected).`,
-      );
-    }
-    personaPath = resolved;
-  } else {
-    personaPath = fileCfg.personaPath ?? defaultPersonaPath();
+  let model: string;
+  try {
+    model = resolveModel(modelInput);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new LaunchConfigError("model-alias", msg, { input: modelInput });
   }
 
+  const personaPath = flags.persona
+    ? await validatePersonaFile(flags.persona, "--persona")
+    : fileCfg.personaPath !== undefined
+      ? await validatePersonaFile(fileCfg.personaPath, "config personaPath")
+      : await validatePersonaFile(defaultPersonaPath(), "default persona");
+
   const maxHistory =
     typeof fileCfg.maxHistory === "number" &&
     Number.isInteger(fileCfg.maxHistory) &&
@@ -253,5 +324,43 @@ export async function resolveConfig(argv: string[]): Promise<Config> {
     parseOptionalBoolean(process.env.DREXLER_FAST) ??
     parseOptionalBoolean(fileCfg.fast);
 
-  return { apiKey, model, maxHistory, personaPath, theme, noIntro, fast };
+  return { model, personaPath, theme, noIntro, fast, maxHistory, fileCfg };
+}
+
+export async function describeApiKeySource(): Promise<{
+  source: ApiKeySource;
+  configPath: string | null;
+}> {
+  const envKey = process.env.OPENROUTER_API_KEY;
+  if (isValidApiKey(envKey)) return { source: "env", configPath: null };
+  const fileCfg = await loadConfigFile();
+  if (isValidApiKey(fileCfg.apiKey)) {
+    return { source: "config-file", configPath: getResolvedConfigPath() };
+  }
+  return { source: "missing", configPath: null };
+}
+
+export async function resolveConfig(argv: string[]): Promise<Config> {
+  const structural = await validateLaunchConfig(argv);
+  const envKey = process.env.OPENROUTER_API_KEY;
+  const apiKey = isValidApiKey(envKey)
+    ? envKey.trim()
+    : isValidApiKey(structural.fileCfg.apiKey)
+      ? structural.fileCfg.apiKey.trim()
+      : "";
+  if (!apiKey) {
+    throw new LaunchConfigError(
+      "api-key-empty",
+      "API key missing. Run drexler interactively to set one, or export OPENROUTER_API_KEY.",
+    );
+  }
+  return {
+    apiKey,
+    model: structural.model,
+    maxHistory: structural.maxHistory,
+    personaPath: structural.personaPath,
+    theme: structural.theme,
+    noIntro: structural.noIntro,
+    fast: structural.fast,
+  };
 }

package/src/conversation.ts

@@ -63,10 +63,6 @@ export class Conversation {
     return this.messages.length - 1;
   }
 
-  get totalLength(): number {
-    return this.messages.length;
-  }
-
   get userTurns(): number {
     return this.userTurnCount;
   }

package/src/index.ts

@@ -3,7 +3,12 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import React from "react";
 import { render } from "ink";
-import { ensureApiKey, resolveConfig } from "./config.ts";
+import {
+  ensureApiKey,
+  LaunchConfigError,
+  resolveConfig,
+  validateLaunchConfig,
+} from "./config.ts";
 import { Conversation } from "./conversation.ts";
 import { moodLine, pickMood } from "./mood.ts";
 import { loadPersona, pickGreeting } from "./persona.ts";
@@ -52,6 +57,14 @@ Slash commands inside REPL:
   /clear         reset conversation
   /exit          exit
   /synergy       SYNERGY!
+  /feed          feed Drexler a deal memo
+  /play          corporate synergy game (flexing included)
+  /work          Drexler grinds the pipeline
+  /rest          strategic nap (restores energy)
+  /praise        affirm Drexler's contributions
+  /vibe          let Drexler choose his own adventure
+  /name [name]   view or assign Drexler's pet name
+  /profile       print Drexler's personnel file
   /model [id]    show or switch model
   /theme [name]  show or switch theme; append save to persist
   /startup [mode] persist startup mode: fast, no-intro, normal
@@ -66,6 +79,8 @@ Slash commands inside REPL:
   /save [path]   archive conversation as markdown
   /save-last [path] save latest response
   /copy-last     copy latest response to clipboard
+  /setup         show config + API key source
+  /update        show upgrade instructions
 
 Ctrl+C exits gracefully.`;
 
@@ -85,18 +100,39 @@ async function main(): Promise<void> {
   const isInteractive =
     process.stdout.isTTY === true && process.stdin.isTTY === true;
 
-  // Acquire API key. Prompts interactively if missing — runs BEFORE banner.
+  // 1. Validate non-secret config FIRST so a bogus --model or --persona
+  //    fails fast before we ask the user for an API key.
+  try {
+    await validateLaunchConfig(argv);
+  } catch (e) {
+    if (e instanceof LaunchConfigError) {
+      console.error(error(formatLaunchError(e)));
+    } else {
+      console.error(
+        error(`Drexler config tantrum: ${e instanceof Error ? e.message : e}`),
+      );
+    }
+    process.exit(1);
+  }
+
+  // 2. Acquire API key (may prompt). Runs after validation so bad CLI args
+  //    no longer trigger the first-run setup flow.
   await ensureApiKey({
     prompt: isInteractive ? promptForApiKeyWithInk : undefined,
   });
 
+  // 3. Resolve full Config (API key now present).
   let config;
   try {
     config = await resolveConfig(argv);
   } catch (e) {
-    console.error(
-      error(`Drexler config tantrum: ${e instanceof Error ? e.message : e}`),
-    );
+    if (e instanceof LaunchConfigError) {
+      console.error(error(formatLaunchError(e)));
+    } else {
+      console.error(
+        error(`Drexler config tantrum: ${e instanceof Error ? e.message : e}`),
+      );
+    }
     process.exit(1);
   }
 
@@ -154,6 +190,7 @@ async function main(): Promise<void> {
   }
 
   // Non-TTY fallback: linear output, readline-based REPL.
+  installFatalHandlers();
   console.log("");
   if (!skipIntro) {
     console.log(banner());
@@ -172,6 +209,34 @@ async function main(): Promise<void> {
   });
 }
 
+function formatLaunchError(e: LaunchConfigError): string {
+  switch (e.reason) {
+    case "model-alias":
+      return `Bad model alias: ${e.message}`;
+    case "persona-path":
+      return `Bad persona file: ${e.message}`;
+    case "config-unreadable":
+      return `Config file unreadable: ${e.message}`;
+    case "api-key-empty":
+      return `API key required: ${e.message}`;
+  }
+}
+
+// Fatal handlers are installed only in the non-TTY path; the interactive
+// path lets Ink's signal-exit hooks run cleanup so the alt-screen restores.
+function installFatalHandlers(): void {
+  process.on("unhandledRejection", (reason) => {
+    const msg =
+      reason instanceof Error ? (reason.stack ?? reason.message) : String(reason);
+    console.error(error("Unhandled rejection:"), msg);
+    process.exitCode = 1;
+  });
+  process.on("uncaughtException", (err) => {
+    console.error(error("Uncaught exception:"), err.stack ?? err.message);
+    process.exitCode = 1;
+  });
+}
+
 main().catch((e) => {
   console.error(error("Fatal:"), e);
   process.exit(1);