wtagent 0.1.0 → 0.2.1

package/src/cli/main.js

@@ -3,16 +3,25 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { Command } from "commander";
 import { confirm, select } from "@inquirer/prompts";
-import { ChatGPTWebAdapter } from "../browser/chatgpt-web-adapter.js";
 import { launchNativeLoginBrowser } from "../browser/native-login.js";
+import {
+  createWebAdapter,
+  DEFAULT_PROVIDER,
+  getProvider,
+  getProviderProfileDir,
+  isProviderProfileBasename,
+  listActiveProviderIds,
+  resolveCliProviderSelection,
+  resolveProvider,
+} from "../browser/provider-registry.js";
 import {
   ensureDirectory,
   getAppDataDir,
-  getChromeProfileDir,
   getSessionsDir,
   getTasksDir,
 } from "../platform/paths.js";
 import { discoverChromeExecutable } from "../platform/chrome-discovery.js";
+import { isProcessAlive } from "../browser/cdp-state.js";
 import {
   assertNativeRuntimeSupported,
   collectDoctorReport,
@@ -25,9 +34,11 @@ import { createDefaultToolRegistry } from "../tools/default-tools.js";
 import { ProcessManager } from "../tools/process-manager.js";
 import { resolveLimits } from "../shared/limits.js";
 import { EXPORTERS } from "../session/session-export.js";
+import { getPackageVersion } from "../shared/package-info.js";
 import { extractAtMentions } from "./at-files.js";
 import {
   classifyChatInput,
+  promptForConfirm,
   promptForText,
   promptForSelect,
   readChatMessage,
@@ -39,13 +50,24 @@ import {
   modeFromPromptChoice,
   normalizeConfiguredMode,
 } from "./mode-choice.js";
+import { runSelfUpdate } from "./self-update.js";
+import { runStartupChecks } from "./startup-notices.js";
+
+// Resolves the app data dir, the provider's dedicated Chrome profile dir, and
+// the sessions dirs. `providerId` selects which profile directory is used
+// (each provider logs in independently); an explicit `--profile-dir` still
+// overrides it. Defaults to the ChatGPT profile so callers that predate
+// multi-provider support are unaffected.
+function withResolvedProviderSelection(options) {
+  return { ...options, ...resolveCliProviderSelection(options) };
+}
 
-function resolveRuntimePaths(options) {
+function resolveRuntimePaths(options, providerId = DEFAULT_PROVIDER) {
   const appDataDir = path.resolve(options.home ?? getAppDataDir());
   return {
     appDataDir,
     profileDir: path.resolve(
-      options.profileDir ?? getChromeProfileDir(appDataDir),
+      options.profileDir ?? getProviderProfileDir(appDataDir, providerId),
     ),
     sessionsDir: getSessionsDir(appDataDir),
     legacyTasksDir: getTasksDir(appDataDir),
@@ -61,21 +83,25 @@ async function assertDirectory(directory) {
 
 async function runLogin(options) {
   assertNativeRuntimeSupported();
-  const { profileDir } = resolveRuntimePaths(options);
+  options = withResolvedProviderSelection(options);
+  const provider = resolveProvider(options.model ?? DEFAULT_PROVIDER);
+  const { profileDir } = resolveRuntimePaths(options, provider.id);
+  const { label, baseUrl } = provider;
   for (;;) {
     console.log(`Opening native Chrome profile: ${profileDir}`);
     console.log(
-      "This window has no CDP flags. Finish until ChatGPT shows your signed-in home/chat history and no Log in button.",
+      `This window has no CDP flags. Finish until ${label} shows your signed-in home/chat history and no Log in button.`,
     );
     const browser = await launchNativeLoginBrowser({
       profileDir,
       chromePath: options.chromePath,
+      url: baseUrl,
     });
 
     try {
       const answer = await promptForText({
         message:
-          "After the signed-in ChatGPT home is visible, press Enter here to save and verify",
+          `After the signed-in ${label} home is visible, press Enter here to save and verify`,
       });
       if (answer == null) {
         return;
@@ -86,7 +112,8 @@ async function runLogin(options) {
       await browser.close();
     }
 
-    const verifier = new ChatGPTWebAdapter({
+    const verifier = createWebAdapter({
+      provider,
       profileDir,
       chromePath: options.chromePath,
     });
@@ -102,7 +129,7 @@ async function runLogin(options) {
         }
       }
       if (authenticated) {
-        console.log("ChatGPT login verified through a fresh CDP connection.");
+        console.log(`${label} login verified through a fresh CDP connection.`);
         return;
       }
     } finally {
@@ -110,17 +137,22 @@ async function runLogin(options) {
     }
 
     console.log(
-      "ChatGPT is still in guest mode. Reopening native Chrome; complete the final ChatGPT sign-in/continue step.",
+      `${label} is still in guest mode. Reopening native Chrome; complete the final ${label} sign-in/continue step.`,
     );
   }
 }
 
 // Resets local login by deleting the dedicated Chrome profile. Login state for
-// this app lives entirely in that profile (chatgpt.com cookies + localStorage),
-// so removing it returns wtagent to a clean guest state — useful for testing the
+// this app lives entirely in that profile (provider cookies + localStorage), so
+// removing it returns wtagent to a clean guest state — useful for testing the
 // full login → run flow. It never touches the real account server-side.
 async function runLogout(options) {
-  const { profileDir } = resolveRuntimePaths(options);
+  // `logout` targets one provider's profile; unknown ids are rejected but a
+  // "planned" provider is still allowed (its profile may exist from a prior
+  // login attempt), so use getProvider rather than resolveProvider.
+  options = withResolvedProviderSelection(options);
+  const provider = getProvider(options.model ?? DEFAULT_PROVIDER);
+  const { profileDir } = resolveRuntimePaths(options, provider.id);
   const exists = await fs.stat(profileDir)
     .then((stat) => stat.isDirectory())
     .catch(() => false);
@@ -129,13 +161,13 @@ async function runLogout(options) {
     return;
   }
 
-  // Guard: only ever delete something that is actually the dedicated profile.
+  // Guard: only ever delete something that is actually a dedicated profile.
   // A profile Chrome has used contains a "Default" profile directory; otherwise
-  // require the conventional "chrome-profile" basename before removing.
+  // require a known provider profile basename before removing.
   const looksLikeProfile = await fs.stat(path.join(profileDir, "Default"))
     .then((stat) => stat.isDirectory())
     .catch(() => false);
-  if (!looksLikeProfile && path.basename(profileDir) !== "chrome-profile") {
+  if (!looksLikeProfile && !isProviderProfileBasename(path.basename(profileDir))) {
     throw new Error(
       `Refusing to delete ${profileDir}: it does not look like a wtagent Chrome profile.`,
     );
@@ -144,7 +176,7 @@ async function runLogout(options) {
   if (!options.yes) {
     const confirmed = await confirm({
       message:
-        `This deletes the local ChatGPT session (Chrome profile at ${profileDir}) `
+        `This deletes the local ${provider.label} session (Chrome profile at ${profileDir}) `
         + "and requires a new login. Continue?",
       default: false,
     });
@@ -156,7 +188,11 @@ async function runLogout(options) {
 
   await fs.rm(profileDir, { recursive: true, force: true });
   console.log(`Logged out. Removed ${profileDir}.`);
-  console.log("Run `wtagent login` to sign in again.");
+  console.log(
+    provider.id === DEFAULT_PROVIDER
+      ? "Run `wtagent login` to sign in again."
+      : `Run \`wtagent login --model ${provider.id}\` to sign in again.`,
+  );
 }
 
 async function runDoctor(options) {
@@ -172,7 +208,14 @@ async function runDoctor(options) {
   }
   console.log(`Data: ${paths.appDataDir}`);
   console.log(`Profile: ${paths.profileDir}`);
-  console.log(report.exitCode === 0 ? "Doctor: OK" : "Doctor: FAILED");
+  const hasWarnings = report.items.some((item) => item.status === "degraded");
+  console.log(
+    report.exitCode !== 0
+      ? "Doctor: FAILED"
+      : hasWarnings
+        ? "Doctor: OK (with warnings)"
+        : "Doctor: OK",
+  );
   process.exitCode = report.exitCode;
 }
 
@@ -184,24 +227,29 @@ class ConversationRunner {
   constructor({ session, options, interactive = false }) {
     this.session = session;
     this.options = options;
-    this.paths = resolveRuntimePaths(options);
+    // A conversation belongs to exactly one provider (recorded at creation).
+    // The profile dir and adapter follow from it, so resumes reuse the right
+    // login even when the CLI is invoked without --model.
+    const provider = resolveProvider(session.state.provider ?? DEFAULT_PROVIDER);
+    this.paths = resolveRuntimePaths(options, provider.id);
     this.limits = resolveLimits({
       modelTurnTimeoutMs: options.modelTurnTimeoutMs,
     });
     this.processManager = new ProcessManager();
-    this.renderer = createRenderer();
-    // "Always allow" decisions from the approval prompt persist here across
-    // turns, resumes, and separate sessions.
+    this.renderer = createRenderer({ providerLabel: provider.label });
+    // "Always allow" decisions are scoped to this saved session. They persist
+    // across turns and `resume`, but never carry over into a different session.
     this.approvalStore = new ApprovalStore({
-      filePath: path.join(this.paths.appDataDir, "approvals.json"),
+      filePath: path.join(this.session.directory, "approvals.json"),
     });
-    this.adapter = new ChatGPTWebAdapter({
+    this.adapter = createWebAdapter({
+      provider,
       profileDir: this.paths.profileDir,
       chromePath: options.chromePath,
       debug: options.debug,
       // Minimize by default; `--no-minimize` sets options.minimize === false.
       minimized: options.minimize !== false,
-      // ESC cancels the in-flight turn while ChatGPT is processing. Only in
+      // ESC cancels the in-flight turn while the model is processing. Only in
       // interactive TTY sessions where stdin is available to listen on.
       cancelOnEsc: interactive,
     });
@@ -242,14 +290,15 @@ class ConversationRunner {
           this.approvalStore.setAlwaysAllowedTool(toolCall.name);
           await this.approvalStore.save();
           console.log(
-            `Saved: ${toolCall.name} will always be allowed `
+            `Saved for this session: ${toolCall.name} will always be allowed `
             + `(${this.approvalStore.filePath}).`,
           );
         } else if (choice === "always-all") {
           this.approvalStore.setAlwaysAllowAll();
           await this.approvalStore.save();
           console.log(
-            `Saved: every tool will always be allowed (${this.approvalStore.filePath}).`,
+            `Saved for this session: every tool will always be allowed `
+            + `(${this.approvalStore.filePath}).`,
           );
         }
         return true;
@@ -340,6 +389,15 @@ class ConversationRunner {
     this.renderer.finish();
     await this.processManager.stopAll().catch(() => {});
     if (keepBrowser) {
+      // Only offer to keep Chrome when this run actually launched one. A run
+      // that failed before launch (e.g. the provider profile lock was held by
+      // another live session) has no window to inspect.
+      if (!this.adapter.cdpChrome) {
+        return;
+      }
+      await this.adapter.detach().catch((error) => {
+        console.error(`Warning: ${error.message}`);
+      });
       console.log(
         "The run failed; Chrome was left open for debugging. "
           + "Inspect the page and close it manually, or just run "
@@ -353,6 +411,56 @@ class ConversationRunner {
   }
 }
 
+async function waitForProcessToExit(pid, timeoutMs = 60_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  return !isProcessAlive(pid);
+}
+
+// A live session holds the provider's Chrome profile lock. In an interactive
+// session, ask the user how to proceed instead of failing outright: kill the
+// other session, or have the user close its Chrome window so that session
+// fails and releases the profile. Returns true when the turn should be retried.
+async function promptToResolveProfileLock(error) {
+  const pid = Number(error.details?.pid);
+  console.log(`\n${"\x1b[33m"}${error.message}${"\x1b[0m"}`);
+  const choice = await promptForSelect({
+    message: "How should this be handled?",
+    choices: [
+      { name: "Kill that session and continue", value: "kill" },
+      { name: "I closed its Chrome window; retry", value: "retry" },
+      { name: "Quit", value: "quit" },
+    ],
+  });
+  if (choice == null || choice === "quit") {
+    return false;
+  }
+  if (choice === "kill" && Number.isSafeInteger(pid) && pid > 0) {
+    console.log(`Stopping pid=${pid}...`);
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // Already gone.
+    }
+    if (!await waitForProcessToExit(pid, 5_000)) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+  // Either the holder was killed or the user closed its Chrome window: wait
+  // for the other session to release the profile, then retry the turn.
+  await waitForProcessToExit(pid, 60_000);
+  return true;
+}
+
 async function executeSession({
   session,
   options,
@@ -367,14 +475,19 @@ async function executeSession({
   const interactive = !options.once && process.stdin.isTTY && process.stdout.isTTY;
   const runner = new ConversationRunner({ session, options, interactive });
 
-  const onInterrupt = async () => {
+  const onInterrupt = () => {
     if (runner.interrupted) {
-      return;
+      console.log("\nForce quitting.");
+      // process.exit skips the finally block, so repeat the session/resume
+      // hint here — the user should always know how to continue.
+      console.log(`Session saved at: ${session.directory}`);
+      printResumeHint(session.sessionId);
+      process.exit(130);
     }
     runner.interrupted = true;
+    runner.adapter.escCancelRequested = true;
     runner.renderer.stopSpinner();
-    console.log("\nStopping managed processes and Chrome…");
-    await runner.close();
+    console.log("\nCtrl+C — cancelling. Press again to force quit.");
     process.exitCode = 130;
   };
   process.on("SIGINT", onInterrupt);
@@ -394,13 +507,27 @@ async function executeSession({
     let turnInPlaceRecovery = false;
 
     for (;;) {
-      const result = await runner.runTurn({
-        resume: turnResume,
-        instruction: turnInstruction,
-        files: turnFiles,
-        inPlaceRecovery: turnInPlaceRecovery,
-        mode,
-      });
+      let result;
+      try {
+        result = await runner.runTurn({
+          resume: turnResume,
+          instruction: turnInstruction,
+          files: turnFiles,
+          inPlaceRecovery: turnInPlaceRecovery,
+          mode,
+        });
+      } catch (error) {
+        // Another live session holds the provider profile lock. Interactively,
+        // offer to resolve it and retry the same turn; otherwise fail cleanly
+        // (the top-level handler prints the actionable message).
+        if (error?.code === "PROFILE_LOCKED" && interactive) {
+          if (await promptToResolveProfileLock(error)) {
+            continue;
+          }
+          return null;
+        }
+        throw error;
+      }
       if (runner.interrupted) {
         break;
       }
@@ -418,7 +545,7 @@ async function executeSession({
           throw result.error;
         }
         runner.renderer.hint(
-          "Type /retry to ask ChatGPT to continue again, enter a new instruction, or quit.",
+          `Type /retry to ask ${runner.renderer.providerLabel} to continue again, enter a new instruction, or quit`,
         );
         const next = await promptForNextMessage(runner, activeChatInput);
         if (next == null) {
@@ -536,23 +663,69 @@ async function resolveMessageAttachments(runner, text) {
   return files;
 }
 
+function isInteractiveSession(options) {
+  return !options.once && process.stdin.isTTY && process.stdout.isTTY;
+}
+
+async function promptForUpdate({ currentVersion, latest }) {
+  return await promptForConfirm({
+    message: `Update WTAgent from ${currentVersion} to ${latest} now?`,
+    default: true,
+  });
+}
+
+async function maybeRunStartupChecks(options) {
+  return await runStartupChecks({
+    appDataDir: resolveRuntimePaths(options).appDataDir,
+    interactive: isInteractiveSession(options),
+    promptUpdate: promptForUpdate,
+  });
+}
+
+async function runUpdate() {
+  const result = await runSelfUpdate();
+  if (result.status === "error") {
+    process.exitCode = 1;
+  }
+  return result;
+}
+
 async function runAgent(taskParts, options) {
   assertNativeRuntimeSupported();
+  options = withResolvedProviderSelection(options);
   const projectRoot = path.resolve(options.project ?? process.cwd());
   await assertDirectory(projectRoot);
-  const interactive = !options.once && process.stdin.isTTY && process.stdout.isTTY;
+
+  // Fail fast on an unknown/unsupported --model before any startup work.
+  const provider = resolveProvider(options.model ?? DEFAULT_PROVIDER);
+
+  const startup = await maybeRunStartupChecks(options);
+  if (startup === "updated" || startup === "aborted") {
+    return null;
+  }
+
+  const interactive = isInteractiveSession(options);
   const chatInput = interactive ? new ShellChatInput() : null;
 
   if (interactive) {
-    printChatBanner(projectRoot);
+    printChatBanner(projectRoot, provider);
   }
 
+  // Mode selection is abstracted per provider: some prompt (ChatGPT's
+  // Pro/Current), others silently apply their configured default at
+  // conversation start (DeepSeek → 专家模式 + 深度思考). The chosen value is
+  // handed to the adapter's selectMode() by the runtime.
   let requestedMode;
-  if (options.mode != null) {
+  if (!provider.promptsForMode) {
+    if (options.mode != null) {
+      console.log(`Note: --mode is ignored for ${provider.label}.`);
+    }
+    requestedMode = provider.defaultMode;
+  } else if (options.mode != null) {
     requestedMode = normalizeConfiguredMode(options.mode);
   } else if (interactive) {
     const modeChoice = await promptForSelect({
-      message: "ChatGPT mode",
+      message: `${provider.label} mode`,
       choices: CHATGPT_MODE_CHOICES,
     });
     if (modeChoice == null) {
@@ -587,12 +760,13 @@ async function runAgent(taskParts, options) {
     chatInput.remember(task);
   }
 
-  const paths = resolveRuntimePaths(options);
+  const paths = resolveRuntimePaths(options, provider.id);
   await ensureDirectory(paths.sessionsDir);
   const session = await AgentSession.create({
     sessionsDir: paths.sessionsDir,
     task,
     projectRoot,
+    provider: provider.id,
     mode: requestedMode,
   });
 
@@ -616,13 +790,13 @@ async function runAgent(taskParts, options) {
   return await executeSession({ session, options, files, chatInput });
 }
 
-function printChatBanner(projectRoot) {
+function printChatBanner(projectRoot, provider) {
   const CYAN = "\x1b[36m";
   const DIM = "\x1b[2m";
   const RESET = "\x1b[0m";
   console.log("");
-  console.log(`${CYAN}WTAgent${RESET} ${DIM}· GPT Web · ${projectRoot}${RESET}`);
-  console.log(`${DIM}Enter sends · Shift+Enter newline · ESC cancels processing · multiline paste · ↑/↓ history · "exit", Ctrl+C, or Ctrl+D quits${RESET}`);
+  console.log(`${CYAN}WTAgent${RESET} ${DIM}· ${provider.label} · ${projectRoot}${RESET}`);
+  console.log(`${DIM}Enter sends · Shift+Enter or Ctrl+J newline · ESC cancels processing · multiline paste · ↑/↓ history · "exit", Ctrl+C, or Ctrl+D quits${RESET}`);
   console.log("");
 }
 
@@ -645,17 +819,39 @@ async function loadSession(paths, sessionId) {
 
 async function runResume(sessionId, instructionParts, options) {
   assertNativeRuntimeSupported();
+  options = withResolvedProviderSelection(options);
+  // Loading only needs the sessions dir (provider-independent); the provider is
+  // then read from the session so the run reuses the right adapter + profile.
   const paths = resolveRuntimePaths(options);
   await ensureDirectory(paths.sessionsDir);
   const session = await loadSession(paths, sessionId);
   await assertDirectory(session.state.projectRoot);
 
-  // Like a fresh run, interactive resumes offer a mode choice, defaulting to
-  // the mode the conversation is already on. `--mode` overrides it and also
-  // works non-interactively. This matters after a usage limit, where switching
-  // thinking levels (Pro vs Current) before retrying can get past the block.
+  const provider = resolveProvider(session.state.provider ?? DEFAULT_PROVIDER);
+  // A conversation belongs to one provider. --model on resume is only allowed
+  // if it names the same provider; switching mid-conversation is rejected.
+  if (options.model != null && getProvider(options.model).id !== provider.id) {
+    throw new Error(
+      `Session ${sessionId} uses ${provider.label}; `
+        + `--model ${options.model} cannot change a conversation's provider.`,
+    );
+  }
+
+  const startup = await maybeRunStartupChecks(options);
+  if (startup === "updated" || startup === "aborted") {
+    return null;
+  }
+
+  // Like a fresh run, interactive resumes offer a mode choice (prompting
+  // providers only), defaulting to the mode the conversation is already on.
+  // `--mode` overrides it and also works non-interactively. This matters after
+  // a usage limit, where switching thinking levels can get past the block.
+  // Non-prompting providers (e.g. DeepSeek) keep the mode the existing
+  // conversation was created with — it does not need re-asserting on resume.
   let requestedMode;
-  if (options.mode != null) {
+  if (!provider.promptsForMode) {
+    requestedMode = null;
+  } else if (options.mode != null) {
     requestedMode = normalizeConfiguredMode(options.mode);
   } else if (
     !options.once
@@ -663,7 +859,7 @@ async function runResume(sessionId, instructionParts, options) {
     && process.stdout.isTTY
   ) {
     const modeChoice = await promptForSelect({
-      message: "ChatGPT mode",
+      message: `${provider.label} mode`,
       choices: CHATGPT_MODE_CHOICES,
       default: session.state.activeMode === "Pro" ? "pro" : "current",
     });
@@ -774,14 +970,18 @@ async function runExport(sessionId, options) {
 const program = new Command()
   .name("wtagent")
   .description("Turn your web AI session into a local tool-using agent.")
-  .version("0.1.0")
+  .version(getPackageVersion())
   .option("--home <path>", "Application data directory")
   .option("--profile-dir <path>", "Dedicated Chrome profile directory")
   .option("--chrome-path <path>", "Chrome/Chromium executable")
   .option("-C, --project <path>", "Project directory", process.cwd())
+  .option(
+    "--model <provider>",
+    `Web AI provider: ${listActiveProviderIds().join(", ")} (default: ${DEFAULT_PROVIDER})`,
+  )
   .option(
     "--mode <name>",
-    'ChatGPT mode: "Pro" selects Pro; "Current" keeps the web setting',
+    "ChatGPT mode (Pro/Current), or a provider alias such as kimi",
   )
   .option(
     "--once",
@@ -790,7 +990,7 @@ const program = new Command()
   )
   .option(
     "--model-turn-timeout-ms <milliseconds>",
-    "Maximum wait for one ChatGPT response (default: 1200000)",
+    "Maximum wait for one model response (default: 10 minutes; 16 minutes for ChatGPT Pro)",
   )
   .option(
     "--no-minimize",
@@ -805,6 +1005,11 @@ const program = new Command()
     await runAgent(task, command.optsWithGlobals());
   });
 
+program
+  .command("update")
+  .description("Install the latest WTAgent from npm.")
+  .action(async () => runUpdate());
+
 program
   .command("doctor")
   .description("Check Node, Chrome, and local data directories.")
@@ -812,12 +1017,12 @@ program
 
 program
   .command("login")
-  .description("Open the dedicated Chrome profile and wait for ChatGPT login.")
+  .description("Open the dedicated Chrome profile and wait for provider login (use --model to pick a provider).")
   .action(async (_, command) => runLogin(command.optsWithGlobals()));
 
 program
   .command("logout")
-  .description("Delete the local Chrome profile to reset the ChatGPT session.")
+  .description("Delete the local Chrome profile to reset a provider session (use --model to pick a provider).")
   .option("--yes", "Skip the confirmation prompt", false)
   .action(async (options, command) => {
     await runLogout({ ...command.optsWithGlobals(), ...options });
@@ -830,7 +1035,7 @@ program
   .argument("[instruction...]", "Optional follow-up instruction")
   .option(
     "--mode <name>",
-    'ChatGPT mode: "Pro" selects Pro; "Current" keeps the web setting',
+    "ChatGPT mode (Pro/Current), or a provider alias such as kimi",
   )
   .action(async (sessionId, instruction, _, command) => {
     await runResume(
@@ -859,6 +1064,25 @@ program
   });
 
 program.parseAsync().catch((error) => {
+  // Expected, actionable failures carry a plain message instead of a stack
+  // trace (e.g. the provider's Chrome profile is locked by another session).
+  if (error?.code === "PROFILE_LOCKED") {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
   console.error(error.stack ?? error.message);
   process.exitCode = 1;
+}).finally(() => {
+  // By the time every command finishes, all per-command cleanup (browser
+  // detach/close, stdin raw-mode restore, process stop) has already run. A
+  // stray tty handle (e.g. a keypress-machinery listener left behind on a
+  // failed turn) can still pin the event loop, leaving a dead prompt that
+  // never returns to the shell — exit hard instead of relying on the loop
+  // to drain naturally.
+  if (process.exitCode != null && process.exitCode !== 0) {
+    process.stdin.setRawMode?.(false);
+    process.stdin.pause?.();
+    process.exit(process.exitCode);
+  }
 });