codeam-cli 2.16.2 → 2.17.1

package/dist/index.js

@@ -424,7 +424,7 @@ var import_qrcode_terminal = __toESM(require("qrcode-terminal"));
 // package.json
 var package_default = {
   name: "codeam-cli",
-  version: "2.16.2",
+  version: "2.17.1",
   description: "Workflow-continuity bridge for AI coding agents. Wrap Claude Code or Codex in a PTY and supervise, approve, and redirect the session from any device \u2014 async. The terminal companion for CodeAgent Mobile.",
   type: "commonjs",
   main: "dist/index.js",
@@ -1537,9 +1537,253 @@ var WindowsConPtyStrategy = class _WindowsConPtyStrategy {
   };
 };
 
+// src/services/claude-resolver.ts
+var path6 = __toESM(require("path"));
+init_types();
+function buildClaudeLaunch(extraArgs = []) {
+  const found = findInPath("claude") ?? findInPath("claude-code");
+  if (!found) return null;
+  if (process.platform === "win32") {
+    const ext = path6.extname(found).toLowerCase();
+    if (ext === ".cmd" || ext === ".bat") {
+      return { cmd: "cmd.exe", args: ["/c", found, ...extraArgs] };
+    }
+    if (ext === ".ps1") {
+      return {
+        cmd: "powershell.exe",
+        args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", found, ...extraArgs]
+      };
+    }
+  }
+  return { cmd: found, args: extraArgs };
+}
+
+// src/services/agent.service.ts
+var AgentService = class {
+  constructor(runtime, opts) {
+    this.runtime = runtime;
+    this.opts = opts;
+    this.strategyOpts = {
+      onData: (d3) => {
+        if (!this.claudeReady && d3.length > 0) {
+          this.claudeReady = true;
+          setTimeout(() => this.drainPending(), 250);
+        }
+        (opts.onData ?? (() => {
+        }))(d3);
+      },
+      onExit: opts.onExit
+    };
+  }
+  runtime;
+  opts;
+  // Strategy is selected lazily inside spawn() so we can fall back from
+  // ConPTY → legacy pipe at runtime if the native binding fails to load.
+  // Methods called before spawn() (e.g. early kill/SIGINT) no-op safely.
+  strategy = null;
+  strategyOpts;
+  /**
+   * Set once the PTY emits its FIRST batch of output — proxy for
+   * "Claude has rendered its input box and is ready to read keystrokes."
+   * Before this, remote `sendCommand`s are buffered (`pendingInputs`)
+   * and replayed in order on first data. Without this guard, the very
+   * first prompt right after `codeam pair` on Windows lands while
+   * Claude's React Ink tree is still mounting — the input bytes are
+   * accepted by the PTY but never make it to the input field, and
+   * the prompt silently vanishes.
+   */
+  claudeReady = false;
+  pendingInputs = [];
+  drainPending() {
+    if (!this.strategy || this.pendingInputs.length === 0) return;
+    const s = this.strategy;
+    log.trace("claude", `drain pending=${this.pendingInputs.length}`);
+    let offset = 0;
+    for (const text of this.pendingInputs) {
+      setTimeout(() => s.write(text), offset);
+      setTimeout(() => s.write("\r"), offset + 50);
+      offset += 200;
+    }
+    this.pendingInputs.length = 0;
+  }
+  async spawn() {
+    let launch;
+    try {
+      launch = await this.runtime.prepareLaunch();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `
+  \u2717 ${this.runtime.meta.displayName} could not be launched.
+    ${msg}
+`
+      );
+      process.exit(1);
+    }
+    if (process.platform === "win32") {
+      log.trace("claude", `spawn (win32) cmd=${launch.cmd} args=${launch.args.join(" ")}`);
+      const conpty = WindowsConPtyStrategy.tryCreate(this.strategyOpts);
+      if (conpty) {
+        try {
+          conpty.spawn(launch.cmd, this.opts.cwd, launch.args);
+          this.strategy = conpty;
+          log.trace("claude", "ConPTY spawn ok");
+          return;
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          try {
+            conpty.dispose();
+          } catch {
+          }
+          console.error(`
+  \u26A0 ConPTY launch failed (${msg.split("\n")[0]})`);
+          console.error("    Falling back to pipe mode (limited interactivity)\u2026\n");
+        }
+      } else {
+        console.error(
+          '\n  \u26A0 Windows: node-pty unavailable, falling back to pipe mode.\n    Claude may exit with "no stdin data" / "--print" errors.\n    Reinstall the CLI to fetch the prebuilt ConPTY binary, or run inside WSL.\n'
+        );
+      }
+      const pipe = new WindowsPtyStrategy(this.strategyOpts);
+      pipe.spawn(launch.cmd, this.opts.cwd, launch.args);
+      this.strategy = pipe;
+      return;
+    }
+    const unix = new UnixPtyStrategy(this.strategyOpts);
+    unix.spawn(launch.cmd, this.opts.cwd, launch.args);
+    this.strategy = unix;
+  }
+  /**
+   * Send a command to Claude's stdin (remote control from mobile).
+   *
+   * Why two separate writes with a delay?
+   * Same batching problem as selectOption: all bytes arriving in one write()
+   * call are processed by readline in one synchronous run.  React Ink batches
+   * the resulting state updates, so when '\r' fires the input's value is still
+   * the pre-batch (empty/previous) state → Enter submits nothing and the text
+   * stays visible-but-unsubmitted in the input field.
+   *
+   * Sending '\r' in a separate write() ~50 ms later guarantees it arrives on
+   * a fresh event-loop tick, after React has flushed the text into input state.
+   *
+   * The delay scales with line count: Smart Composer outputs are ~500–1500
+   * chars with embedded `\n`s (Task / Context / Steps blocks). Ink's input
+   * field re-flows multi-line content per render and the 50 ms baseline that
+   * worked for single-line prompts isn't enough headroom — the text lands in
+   * the field but `\r` submits stale state and the prompt sits there until
+   * the user hits Enter manually. Adding ~40 ms per extra line (capped at
+   * 300 ms) keeps short prompts snappy while giving multi-line composer
+   * outputs the time they need to settle.
+   */
+  sendCommand(text) {
+    if (!this.strategy) {
+      log.trace("claude", "sendCommand dropped (no strategy)");
+      return;
+    }
+    if (!this.claudeReady) {
+      log.trace("claude", `sendCommand buffered (not ready) text=${text.length}B`);
+      this.pendingInputs.push(text);
+      return;
+    }
+    const s = this.strategy;
+    log.trace("claude", `sendCommand text=${text.length}B`);
+    s.write(text);
+    const lineCount = text.split("\n").length;
+    const delay = Math.min(300, 50 + (lineCount - 1) * 40);
+    setTimeout(() => s.write("\r"), delay);
+  }
+  /**
+   * Navigate a React Ink selector to the given 0-based target index and confirm.
+   *
+   * `fromIndex` is the current highlighted position (defaults to 0 for
+   * numbered selectors which always start at the first option). For list-style
+   * selectors (e.g. /mcp), the CLI sends `currentIndex` in the select_prompt
+   * chunk so the client can pass it back here as `fromIndex`, enabling both
+   * up-arrow and down-arrow navigation without always rewinding to position 0.
+   *
+   * Why not sendCommand(arrows + Enter) in one write()?
+   * All bytes arrive as one chunk → readline fires all keypress events in the
+   * same synchronous run → React Ink batches the state updates → each arrow
+   * sees selectedIndex=0 → final state is still 0 or 1 → wrong option selected.
+   *
+   * Fix: send each arrow in a separate write(), ARROW_MS apart, so React has
+   * time to process and re-render between each keystroke.  Enter is sent
+   * ENTER_MS after the last arrow.
+   */
+  selectOption(targetIndex, fromIndex = 0) {
+    if (!this.strategy) return;
+    const s = this.strategy;
+    const delta = targetIndex - fromIndex;
+    const steps = Math.abs(delta);
+    const arrow = delta >= 0 ? "\x1B[B" : "\x1B[A";
+    const ARROW_MS = 80;
+    const ENTER_MS = 200;
+    if (steps === 0) {
+      s.write("\r");
+      return;
+    }
+    for (let i = 0; i < steps; i++) {
+      setTimeout(() => {
+        s.write(arrow);
+      }, i * ARROW_MS);
+    }
+    setTimeout(() => {
+      s.write("\r");
+    }, steps * ARROW_MS + ENTER_MS);
+  }
+  /**
+   * Write raw bytes to the PTY without any auto-appended `\r` or delay.
+   * Use this when the caller already owns the full input (e.g. the
+   * `ptyInput` returned by `RuntimeStrategy.changeModelInstruction()`
+   * already contains the trailing `\r`).
+   */
+  sendRawPtyInput(text) {
+    if (!this.strategy) {
+      log.trace("claude", "sendRawPtyInput dropped (no strategy)");
+      return;
+    }
+    log.trace("claude", `sendRawPtyInput len=${text.length}`);
+    this.strategy.write(text);
+  }
+  /** Send Escape key to Claude (cancels interactive prompts). */
+  sendEscape() {
+    this.strategy?.write("\x1B");
+  }
+  /** Send Ctrl+C to Claude. */
+  interrupt() {
+    this.strategy?.write("");
+  }
+  kill() {
+    this.strategy?.kill();
+  }
+  /**
+   * Kill the current Claude process and relaunch it resuming the given session.
+   * Pass auto=true to add --dangerously-skip-permissions (no confirmation prompts).
+   *
+   * For agents that use CLI flags (Claude: --resume <id>), `resumeLaunchArgs`
+   * returns a non-empty array and we pass those directly to the binary.
+   * For agents that use a post-spawn PTY instruction (e.g. Codex), `resumeLaunchArgs`
+   * returns [] and `postSpawnInstruction` types the resume command into the PTY.
+   */
+  restart(sessionId, auto = false) {
+    if (!this.strategy) return;
+    const resumeArgs = auto ? this.runtime.resumeLaunchArgs(sessionId) : ["--resume", sessionId];
+    const launch = buildClaudeLaunch(resumeArgs);
+    if (!launch) return;
+    this.strategy.kill();
+    this.strategy.spawn(launch.cmd, this.opts.cwd, launch.args);
+    if (resumeArgs.length === 0 && this.runtime.postSpawnInstruction) {
+      const { ptyInput } = this.runtime.postSpawnInstruction(sessionId);
+      setTimeout(() => {
+        this.strategy?.write(ptyInput);
+      }, 500);
+    }
+  }
+};
+
 // src/services/claude-installer.ts
 var import_child_process4 = require("child_process");
-var path6 = __toESM(require("path"));
+var path7 = __toESM(require("path"));
 var os5 = __toESM(require("os"));
 
 // ../../node_modules/@clack/prompts/dist/index.mjs
@@ -3406,387 +3650,130 @@ ${h.value}` : h.value;
     $2(false), h.result = f, c2 && g();
   };
   return { message(h, f) {
-    m(a[0], h, f);
-  }, group(h) {
-    const f = { header: h, value: "", full: "" };
-    return a.push(f), { message(v, T2) {
-      m(f, v, T2);
-    }, error(v) {
-      S2(f, { status: "error", message: v });
-    }, success(v) {
-      S2(f, { status: "success", message: v });
-    } };
-  }, error(h, f) {
-    $2(true), O2.error(h, { output: i, secondarySymbol: r, spacing: 1 }), f?.showLog !== false && p2(), a.splice(1, a.length - 1), a[0].value = "", a[0].full = "";
-  }, success(h, f) {
-    $2(true), O2.success(h, { output: i, secondarySymbol: r, spacing: 1 }), f?.showLog === true && p2(), a.splice(1, a.length - 1), a[0].value = "", a[0].full = "";
-  } };
-};
-var Ot = (e) => new at({ validate: e.validate, placeholder: e.placeholder, defaultValue: e.defaultValue, initialValue: e.initialValue, output: e.output, signal: e.signal, input: e.input, render() {
-  const i = e?.withGuide ?? u.withGuide, s = `${`${i ? `${(0, import_node_util2.styleText)("gray", d2)}
-` : ""}${V2(this.state)}  `}${e.message}
-`, r = e.placeholder ? (0, import_node_util2.styleText)("inverse", e.placeholder[0]) + (0, import_node_util2.styleText)("dim", e.placeholder.slice(1)) : (0, import_node_util2.styleText)(["inverse", "hidden"], "_"), u2 = this.userInput ? this.userInputWithCursor : r, n = this.value ?? "";
-  switch (this.state) {
-    case "error": {
-      const o = this.error ? `  ${(0, import_node_util2.styleText)("yellow", this.error)}` : "", c2 = i ? `${(0, import_node_util2.styleText)("yellow", d2)}  ` : "", a = i ? (0, import_node_util2.styleText)("yellow", E2) : "";
-      return `${s.trim()}
-${c2}${u2}
-${a}${o}
-`;
-    }
-    case "submit": {
-      const o = n ? `  ${(0, import_node_util2.styleText)("dim", n)}` : "", c2 = i ? (0, import_node_util2.styleText)("gray", d2) : "";
-      return `${s}${c2}${o}`;
-    }
-    case "cancel": {
-      const o = n ? `  ${(0, import_node_util2.styleText)(["strikethrough", "dim"], n)}` : "", c2 = i ? (0, import_node_util2.styleText)("gray", d2) : "";
-      return `${s}${c2}${o}${n.trim() ? `
-${c2}` : ""}`;
-    }
-    default: {
-      const o = i ? `${(0, import_node_util2.styleText)("cyan", d2)}  ` : "", c2 = i ? (0, import_node_util2.styleText)("cyan", E2) : "";
-      return `${s}${o}${u2}
-${c2}
-`;
-    }
-  }
-} }).prompt();
-
-// src/services/claude-installer.ts
-init_types();
-function probeInstallDirs() {
-  const home = os5.homedir();
-  if (process.platform === "win32") {
-    return [
-      path6.join(home, ".claude", "local"),
-      path6.join(home, "AppData", "Local", "AnthropicClaude"),
-      path6.join(home, "AppData", "Local", "Programs", "AnthropicClaude")
-    ];
-  }
-  return [
-    path6.join(home, ".local", "bin"),
-    path6.join(home, ".claude", "local"),
-    "/usr/local/bin"
-  ];
-}
-function isAvailable() {
-  return findInPath("claude") !== null || findInPath("claude-code") !== null;
-}
-function augmentPath() {
-  const dirs = probeInstallDirs();
-  const sep2 = path6.delimiter;
-  const current = process.env.PATH ?? "";
-  const existing = new Set(current.split(sep2).filter(Boolean));
-  const additions = dirs.filter((d3) => !existing.has(d3));
-  if (additions.length === 0) return;
-  process.env.PATH = additions.join(sep2) + sep2 + current;
-}
-function runInstaller() {
-  const isWindows = process.platform === "win32";
-  const cmd = isWindows ? "powershell.exe" : "bash";
-  const args2 = isWindows ? [
-    "-NoProfile",
-    "-ExecutionPolicy",
-    "Bypass",
-    "-Command",
-    "irm https://claude.ai/install.ps1 | iex"
-  ] : ["-c", "curl -fsSL https://claude.ai/install.sh | bash"];
-  return new Promise((resolve3) => {
-    const proc = (0, import_child_process4.spawn)(cmd, args2, { stdio: "inherit" });
-    proc.on("error", (err) => {
-      console.error(`
-  \u2717 Installer failed to launch: ${err.message}`);
-      resolve3(false);
-    });
-    proc.on("exit", (code) => {
-      resolve3(code === 0);
-    });
-  });
-}
-async function ensureClaudeInstalled() {
-  if (isAvailable()) return true;
-  const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-  if (isInteractive) {
-    const proceed = await ot2({
-      message: "Claude Code is not installed on this machine. Install it now using the official installer?",
-      initialValue: true
-    });
-    if (q(proceed) || proceed === false) return false;
-  } else {
-    console.log("\n  Claude Code not found \u2014 running the official installer...\n");
-  }
-  console.log();
-  const ok = await runInstaller();
-  if (!ok) {
-    console.error("\n  \u2717 Claude Code installation failed. See the installer output above.");
-    return false;
-  }
-  augmentPath();
-  if (!isAvailable()) {
-    console.error(
-      "\n  \u26A0 Claude Code installed but the binary is still not on PATH for this process.\n    This usually means the installer registered a new directory that only takes\n    effect in a fresh shell. Restart your terminal and run `codeam pair` again."
-    );
-    return false;
-  }
-  return true;
-}
-
-// src/services/claude-resolver.ts
-var path7 = __toESM(require("path"));
-init_types();
-function buildClaudeLaunch(extraArgs = []) {
-  const found = findInPath("claude") ?? findInPath("claude-code");
-  if (!found) return null;
-  if (process.platform === "win32") {
-    const ext = path7.extname(found).toLowerCase();
-    if (ext === ".cmd" || ext === ".bat") {
-      return { cmd: "cmd.exe", args: ["/c", found, ...extraArgs] };
-    }
-    if (ext === ".ps1") {
-      return {
-        cmd: "powershell.exe",
-        args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", found, ...extraArgs]
-      };
-    }
-  }
-  return { cmd: found, args: extraArgs };
-}
-
-// src/services/agent.service.ts
-var AgentService = class {
-  constructor(runtime, opts) {
-    this.runtime = runtime;
-    this.opts = opts;
-    this.strategyOpts = {
-      onData: (d3) => {
-        if (!this.claudeReady && d3.length > 0) {
-          this.claudeReady = true;
-          setTimeout(() => this.drainPending(), 250);
-        }
-        (opts.onData ?? (() => {
-        }))(d3);
-      },
-      onExit: opts.onExit
-    };
-  }
-  runtime;
-  opts;
-  // Strategy is selected lazily inside spawn() so we can fall back from
-  // ConPTY → legacy pipe at runtime if the native binding fails to load.
-  // Methods called before spawn() (e.g. early kill/SIGINT) no-op safely.
-  strategy = null;
-  strategyOpts;
-  /**
-   * Set once the PTY emits its FIRST batch of output — proxy for
-   * "Claude has rendered its input box and is ready to read keystrokes."
-   * Before this, remote `sendCommand`s are buffered (`pendingInputs`)
-   * and replayed in order on first data. Without this guard, the very
-   * first prompt right after `codeam pair` on Windows lands while
-   * Claude's React Ink tree is still mounting — the input bytes are
-   * accepted by the PTY but never make it to the input field, and
-   * the prompt silently vanishes.
-   */
-  claudeReady = false;
-  pendingInputs = [];
-  drainPending() {
-    if (!this.strategy || this.pendingInputs.length === 0) return;
-    const s = this.strategy;
-    log.trace("claude", `drain pending=${this.pendingInputs.length}`);
-    let offset = 0;
-    for (const text of this.pendingInputs) {
-      setTimeout(() => s.write(text), offset);
-      setTimeout(() => s.write("\r"), offset + 50);
-      offset += 200;
-    }
-    this.pendingInputs.length = 0;
-  }
-  async spawn() {
-    let launch;
-    try {
-      launch = await this.runtime.prepareLaunch();
-    } catch {
-      const installed = await ensureClaudeInstalled();
-      if (installed) {
-        try {
-          launch = await this.runtime.prepareLaunch();
-        } catch {
-          launch = null;
-        }
-      } else {
-        launch = null;
-      }
-      if (!launch) {
-        const cmd = process.platform === "win32" ? "irm https://claude.ai/install.ps1 | iex" : "curl -fsSL https://claude.ai/install.sh | bash";
-        console.error(
-          `
-  \u2717 claude is required to continue. Install it manually with:
-    ${cmd}
-    Then restart your terminal and run \`codeam pair\` again.
-`
-        );
-        process.exit(1);
-      }
-    }
-    if (process.platform === "win32") {
-      log.trace("claude", `spawn (win32) cmd=${launch.cmd} args=${launch.args.join(" ")}`);
-      const conpty = WindowsConPtyStrategy.tryCreate(this.strategyOpts);
-      if (conpty) {
-        try {
-          conpty.spawn(launch.cmd, this.opts.cwd, launch.args);
-          this.strategy = conpty;
-          log.trace("claude", "ConPTY spawn ok");
-          return;
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          try {
-            conpty.dispose();
-          } catch {
-          }
-          console.error(`
-  \u26A0 ConPTY launch failed (${msg.split("\n")[0]})`);
-          console.error("    Falling back to pipe mode (limited interactivity)\u2026\n");
-        }
-      } else {
-        console.error(
-          '\n  \u26A0 Windows: node-pty unavailable, falling back to pipe mode.\n    Claude may exit with "no stdin data" / "--print" errors.\n    Reinstall the CLI to fetch the prebuilt ConPTY binary, or run inside WSL.\n'
-        );
-      }
-      const pipe = new WindowsPtyStrategy(this.strategyOpts);
-      pipe.spawn(launch.cmd, this.opts.cwd, launch.args);
-      this.strategy = pipe;
-      return;
-    }
-    const unix = new UnixPtyStrategy(this.strategyOpts);
-    unix.spawn(launch.cmd, this.opts.cwd, launch.args);
-    this.strategy = unix;
-  }
-  /**
-   * Send a command to Claude's stdin (remote control from mobile).
-   *
-   * Why two separate writes with a delay?
-   * Same batching problem as selectOption: all bytes arriving in one write()
-   * call are processed by readline in one synchronous run.  React Ink batches
-   * the resulting state updates, so when '\r' fires the input's value is still
-   * the pre-batch (empty/previous) state → Enter submits nothing and the text
-   * stays visible-but-unsubmitted in the input field.
-   *
-   * Sending '\r' in a separate write() ~50 ms later guarantees it arrives on
-   * a fresh event-loop tick, after React has flushed the text into input state.
-   *
-   * The delay scales with line count: Smart Composer outputs are ~500–1500
-   * chars with embedded `\n`s (Task / Context / Steps blocks). Ink's input
-   * field re-flows multi-line content per render and the 50 ms baseline that
-   * worked for single-line prompts isn't enough headroom — the text lands in
-   * the field but `\r` submits stale state and the prompt sits there until
-   * the user hits Enter manually. Adding ~40 ms per extra line (capped at
-   * 300 ms) keeps short prompts snappy while giving multi-line composer
-   * outputs the time they need to settle.
-   */
-  sendCommand(text) {
-    if (!this.strategy) {
-      log.trace("claude", "sendCommand dropped (no strategy)");
-      return;
-    }
-    if (!this.claudeReady) {
-      log.trace("claude", `sendCommand buffered (not ready) text=${text.length}B`);
-      this.pendingInputs.push(text);
-      return;
-    }
-    const s = this.strategy;
-    log.trace("claude", `sendCommand text=${text.length}B`);
-    s.write(text);
-    const lineCount = text.split("\n").length;
-    const delay = Math.min(300, 50 + (lineCount - 1) * 40);
-    setTimeout(() => s.write("\r"), delay);
-  }
-  /**
-   * Navigate a React Ink selector to the given 0-based target index and confirm.
-   *
-   * `fromIndex` is the current highlighted position (defaults to 0 for
-   * numbered selectors which always start at the first option). For list-style
-   * selectors (e.g. /mcp), the CLI sends `currentIndex` in the select_prompt
-   * chunk so the client can pass it back here as `fromIndex`, enabling both
-   * up-arrow and down-arrow navigation without always rewinding to position 0.
-   *
-   * Why not sendCommand(arrows + Enter) in one write()?
-   * All bytes arrive as one chunk → readline fires all keypress events in the
-   * same synchronous run → React Ink batches the state updates → each arrow
-   * sees selectedIndex=0 → final state is still 0 or 1 → wrong option selected.
-   *
-   * Fix: send each arrow in a separate write(), ARROW_MS apart, so React has
-   * time to process and re-render between each keystroke.  Enter is sent
-   * ENTER_MS after the last arrow.
-   */
-  selectOption(targetIndex, fromIndex = 0) {
-    if (!this.strategy) return;
-    const s = this.strategy;
-    const delta = targetIndex - fromIndex;
-    const steps = Math.abs(delta);
-    const arrow = delta >= 0 ? "\x1B[B" : "\x1B[A";
-    const ARROW_MS = 80;
-    const ENTER_MS = 200;
-    if (steps === 0) {
-      s.write("\r");
-      return;
+    m(a[0], h, f);
+  }, group(h) {
+    const f = { header: h, value: "", full: "" };
+    return a.push(f), { message(v, T2) {
+      m(f, v, T2);
+    }, error(v) {
+      S2(f, { status: "error", message: v });
+    }, success(v) {
+      S2(f, { status: "success", message: v });
+    } };
+  }, error(h, f) {
+    $2(true), O2.error(h, { output: i, secondarySymbol: r, spacing: 1 }), f?.showLog !== false && p2(), a.splice(1, a.length - 1), a[0].value = "", a[0].full = "";
+  }, success(h, f) {
+    $2(true), O2.success(h, { output: i, secondarySymbol: r, spacing: 1 }), f?.showLog === true && p2(), a.splice(1, a.length - 1), a[0].value = "", a[0].full = "";
+  } };
+};
+var Ot = (e) => new at({ validate: e.validate, placeholder: e.placeholder, defaultValue: e.defaultValue, initialValue: e.initialValue, output: e.output, signal: e.signal, input: e.input, render() {
+  const i = e?.withGuide ?? u.withGuide, s = `${`${i ? `${(0, import_node_util2.styleText)("gray", d2)}
+` : ""}${V2(this.state)}  `}${e.message}
+`, r = e.placeholder ? (0, import_node_util2.styleText)("inverse", e.placeholder[0]) + (0, import_node_util2.styleText)("dim", e.placeholder.slice(1)) : (0, import_node_util2.styleText)(["inverse", "hidden"], "_"), u2 = this.userInput ? this.userInputWithCursor : r, n = this.value ?? "";
+  switch (this.state) {
+    case "error": {
+      const o = this.error ? `  ${(0, import_node_util2.styleText)("yellow", this.error)}` : "", c2 = i ? `${(0, import_node_util2.styleText)("yellow", d2)}  ` : "", a = i ? (0, import_node_util2.styleText)("yellow", E2) : "";
+      return `${s.trim()}
+${c2}${u2}
+${a}${o}
+`;
     }
-    for (let i = 0; i < steps; i++) {
-      setTimeout(() => {
-        s.write(arrow);
-      }, i * ARROW_MS);
+    case "submit": {
+      const o = n ? `  ${(0, import_node_util2.styleText)("dim", n)}` : "", c2 = i ? (0, import_node_util2.styleText)("gray", d2) : "";
+      return `${s}${c2}${o}`;
     }
-    setTimeout(() => {
-      s.write("\r");
-    }, steps * ARROW_MS + ENTER_MS);
-  }
-  /**
-   * Write raw bytes to the PTY without any auto-appended `\r` or delay.
-   * Use this when the caller already owns the full input (e.g. the
-   * `ptyInput` returned by `RuntimeStrategy.changeModelInstruction()`
-   * already contains the trailing `\r`).
-   */
-  sendRawPtyInput(text) {
-    if (!this.strategy) {
-      log.trace("claude", "sendRawPtyInput dropped (no strategy)");
-      return;
+    case "cancel": {
+      const o = n ? `  ${(0, import_node_util2.styleText)(["strikethrough", "dim"], n)}` : "", c2 = i ? (0, import_node_util2.styleText)("gray", d2) : "";
+      return `${s}${c2}${o}${n.trim() ? `
+${c2}` : ""}`;
+    }
+    default: {
+      const o = i ? `${(0, import_node_util2.styleText)("cyan", d2)}  ` : "", c2 = i ? (0, import_node_util2.styleText)("cyan", E2) : "";
+      return `${s}${o}${u2}
+${c2}
+`;
     }
-    log.trace("claude", `sendRawPtyInput len=${text.length}`);
-    this.strategy.write(text);
   }
-  /** Send Escape key to Claude (cancels interactive prompts). */
-  sendEscape() {
-    this.strategy?.write("\x1B");
+} }).prompt();
+
+// src/services/claude-installer.ts
+init_types();
+function probeInstallDirs() {
+  const home = os5.homedir();
+  if (process.platform === "win32") {
+    return [
+      path7.join(home, ".claude", "local"),
+      path7.join(home, "AppData", "Local", "AnthropicClaude"),
+      path7.join(home, "AppData", "Local", "Programs", "AnthropicClaude")
+    ];
   }
-  /** Send Ctrl+C to Claude. */
-  interrupt() {
-    this.strategy?.write("");
+  return [
+    path7.join(home, ".local", "bin"),
+    path7.join(home, ".claude", "local"),
+    "/usr/local/bin"
+  ];
+}
+function isAvailable() {
+  return findInPath("claude") !== null || findInPath("claude-code") !== null;
+}
+function augmentPath() {
+  const dirs = probeInstallDirs();
+  const sep2 = path7.delimiter;
+  const current = process.env.PATH ?? "";
+  const existing = new Set(current.split(sep2).filter(Boolean));
+  const additions = dirs.filter((d3) => !existing.has(d3));
+  if (additions.length === 0) return;
+  process.env.PATH = additions.join(sep2) + sep2 + current;
+}
+function runInstaller() {
+  const isWindows = process.platform === "win32";
+  const cmd = isWindows ? "powershell.exe" : "bash";
+  const args2 = isWindows ? [
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-Command",
+    "irm https://claude.ai/install.ps1 | iex"
+  ] : ["-c", "curl -fsSL https://claude.ai/install.sh | bash"];
+  return new Promise((resolve3) => {
+    const proc = (0, import_child_process4.spawn)(cmd, args2, { stdio: "inherit" });
+    proc.on("error", (err) => {
+      console.error(`
+  \u2717 Installer failed to launch: ${err.message}`);
+      resolve3(false);
+    });
+    proc.on("exit", (code) => {
+      resolve3(code === 0);
+    });
+  });
+}
+async function ensureClaudeInstalled() {
+  if (isAvailable()) return true;
+  const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (isInteractive) {
+    const proceed = await ot2({
+      message: "Claude Code is not installed on this machine. Install it now using the official installer?",
+      initialValue: true
+    });
+    if (q(proceed) || proceed === false) return false;
+  } else {
+    console.log("\n  Claude Code not found \u2014 running the official installer...\n");
   }
-  kill() {
-    this.strategy?.kill();
+  console.log();
+  const ok = await runInstaller();
+  if (!ok) {
+    console.error("\n  \u2717 Claude Code installation failed. See the installer output above.");
+    return false;
   }
-  /**
-   * Kill the current Claude process and relaunch it resuming the given session.
-   * Pass auto=true to add --dangerously-skip-permissions (no confirmation prompts).
-   *
-   * For agents that use CLI flags (Claude: --resume <id>), `resumeLaunchArgs`
-   * returns a non-empty array and we pass those directly to the binary.
-   * For agents that use a post-spawn PTY instruction (e.g. Codex), `resumeLaunchArgs`
-   * returns [] and `postSpawnInstruction` types the resume command into the PTY.
-   */
-  restart(sessionId, auto = false) {
-    if (!this.strategy) return;
-    const resumeArgs = auto ? this.runtime.resumeLaunchArgs(sessionId) : ["--resume", sessionId];
-    const launch = buildClaudeLaunch(resumeArgs);
-    if (!launch) return;
-    this.strategy.kill();
-    this.strategy.spawn(launch.cmd, this.opts.cwd, launch.args);
-    if (resumeArgs.length === 0 && this.runtime.postSpawnInstruction) {
-      const { ptyInput } = this.runtime.postSpawnInstruction(sessionId);
-      setTimeout(() => {
-        this.strategy?.write(ptyInput);
-      }, 500);
-    }
+  augmentPath();
+  if (!isAvailable()) {
+    console.error(
+      "\n  \u26A0 Claude Code installed but the binary is still not on PATH for this process.\n    This usually means the installer registered a new directory that only takes\n    effect in a fresh shell. Restart your terminal and run `codeam pair` again."
+    );
+    return false;
   }
-};
+  return true;
+}
 
 // src/agents/claude/quota.ts
 var fs5 = __toESM(require("fs"));
@@ -4272,8 +4259,19 @@ var ClaudeRuntimeStrategy = class {
   id = "claude";
   meta = getAgent("claude");
   async prepareLaunch() {
-    const launch = buildClaudeLaunch();
-    if (!launch) throw new Error("claude binary not found in PATH");
+    let launch = buildClaudeLaunch();
+    if (!launch) {
+      const installed = await ensureClaudeInstalled();
+      if (installed) launch = buildClaudeLaunch();
+    }
+    if (!launch) {
+      const cmd = process.platform === "win32" ? "irm https://claude.ai/install.ps1 | iex" : "curl -fsSL https://claude.ai/install.sh | bash";
+      throw new Error(
+        `Claude Code is required to continue. Install it manually with:
+    ${cmd}
+    Then restart your terminal and run \`codeam pair\` again.`
+      );
+    }
     return { cmd: launch.cmd, args: launch.args };
   }
   resumeLaunchArgs(sessionId) {
@@ -4537,6 +4535,7 @@ var ClaudeDeployStrategy = class {
 
 // src/agents/codex/runtime.ts
 var import_node_child_process = require("child_process");
+var path13 = __toESM(require("path"));
 init_types();
 
 // src/agents/codex/history.ts
@@ -5062,16 +5061,26 @@ var CodexRuntimeStrategy = class {
   id = "codex";
   meta = getAgent("codex");
   async prepareLaunch() {
-    const binary = findInPath("codex");
-    if (!binary) {
+    let binary = findInPath("codex");
+    if (binary) return { cmd: binary, args: [] };
+    console.log("\n  Codex CLI not found \u2014 installing via `npm install -g @openai/codex`...\n");
+    try {
       await installCodexViaNpm();
-      const afterInstall = findInPath("codex");
-      if (!afterInstall) {
-        throw new Error(
-          "Could not find 'codex' on PATH after running 'npm install -g @openai/codex'. Install it manually and retry."
-        );
-      }
-      return { cmd: afterInstall, args: [] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Failed to install Codex CLI automatically (${msg}).
+    Install it manually with:
+      npm install -g @openai/codex
+    Then run \`codeam pair\` again.`
+      );
+    }
+    augmentNpmGlobalBin();
+    binary = findInPath("codex");
+    if (!binary) {
+      throw new Error(
+        "Codex CLI was installed but the binary is not visible on PATH for this process.\n    Restart your terminal and run `codeam pair` again."
+      );
     }
     return { cmd: binary, args: [] };
   }
@@ -5141,9 +5150,35 @@ async function installCodexViaNpm() {
       if (code === 0) resolve3();
       else reject(new Error(`npm install -g @openai/codex exited ${code}`));
     });
-    proc.on("error", reject);
+    proc.on("error", (err) => {
+      const code = err.code;
+      if (code === "ENOENT") {
+        reject(new Error("`npm` is not on PATH. Install Node.js first, then retry."));
+      } else {
+        reject(err);
+      }
+    });
   });
 }
+function augmentNpmGlobalBin() {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  try {
+    const result = (0, import_node_child_process.spawnSync)(npm, ["prefix", "-g"], {
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (result.status !== 0) return;
+    const prefix = result.stdout.toString().trim();
+    if (!prefix) return;
+    const binDir = process.platform === "win32" ? prefix : path13.join(prefix, "bin");
+    const sep2 = path13.delimiter;
+    const current = process.env.PATH ?? "";
+    const existing = new Set(current.split(sep2).filter(Boolean));
+    if (!existing.has(binDir)) {
+      process.env.PATH = binDir + sep2 + current;
+    }
+  } catch {
+  }
+}
 
 // src/agents/codex/credentials.ts
 var import_node_fs3 = __toESM(require("fs"));
@@ -5772,7 +5807,7 @@ var OutputService = class _OutputService {
 
 // src/services/history.service.ts
 var fs11 = __toESM(require("fs"));
-var path14 = __toESM(require("path"));
+var path15 = __toESM(require("path"));
 var os12 = __toESM(require("os"));
 var https4 = __toESM(require("https"));
 var http4 = __toESM(require("http"));
@@ -5935,7 +5970,7 @@ var HistoryService = class _HistoryService {
     return this._quotaPercent === null || Date.now() - this._quotaFetchedAt > ttlMs;
   }
   get projectDir() {
-    return this.runtime.resolveHistoryDir(this.cwd) ?? path14.join(os12.homedir(), ".claude", "projects", encodeCwd(this.cwd));
+    return this.runtime.resolveHistoryDir(this.cwd) ?? path15.join(os12.homedir(), ".claude", "projects", encodeCwd(this.cwd));
   }
   /** Set the current Claude conversation ID (extracted from /cost command or session start) */
   setCurrentConversationId(id) {
@@ -5947,7 +5982,7 @@ var HistoryService = class _HistoryService {
   /** Return the current message count in the active conversation. */
   getCurrentMessageCount() {
     if (!this.currentConversationId) return 0;
-    const filePath = path14.join(this.projectDir, `${this.currentConversationId}.jsonl`);
+    const filePath = path15.join(this.projectDir, `${this.currentConversationId}.jsonl`);
     return parseJsonl(filePath).length;
   }
   /**
@@ -5958,7 +5993,7 @@ var HistoryService = class _HistoryService {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       if (!this.currentConversationId) return null;
-      const filePath = path14.join(this.projectDir, `${this.currentConversationId}.jsonl`);
+      const filePath = path15.join(this.projectDir, `${this.currentConversationId}.jsonl`);
       const messages = parseJsonl(filePath);
       if (messages.length > previousCount) {
         for (let i = messages.length - 1; i >= previousCount; i--) {
@@ -5986,14 +6021,14 @@ var HistoryService = class _HistoryService {
     try {
       const files = fs11.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => {
         try {
-          const stat3 = fs11.statSync(path14.join(dir, e.name));
+          const stat3 = fs11.statSync(path15.join(dir, e.name));
           return { name: e.name, mtime: stat3.mtimeMs, birthtime: stat3.birthtimeMs };
         } catch {
           return { name: e.name, mtime: 0, birthtime: 0 };
         }
       }).filter((f) => f.birthtime >= cutoff).sort((a, b) => b.mtime - a.mtime);
       if (files.length > 0) {
-        this.currentConversationId = path14.basename(files[0].name, ".jsonl");
+        this.currentConversationId = path15.basename(files[0].name, ".jsonl");
       }
     } catch {
     }
@@ -6033,7 +6068,7 @@ var HistoryService = class _HistoryService {
     }
     const files = entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => {
       try {
-        const stat3 = fs11.statSync(path14.join(dir, e.name));
+        const stat3 = fs11.statSync(path15.join(dir, e.name));
         return { name: e.name, mtime: stat3.mtimeMs, birthtime: stat3.birthtimeMs };
       } catch {
         return { name: e.name, mtime: 0, birthtime: 0 };
@@ -6042,7 +6077,7 @@ var HistoryService = class _HistoryService {
     if (files.length === 0) return null;
     const targetFile = this.currentConversationId ? `${this.currentConversationId}.jsonl` : files[0].name;
     if (!files.some((f) => f.name === targetFile)) return null;
-    return this.extractUsageFromFile(path14.join(dir, targetFile));
+    return this.extractUsageFromFile(path15.join(dir, targetFile));
   }
   extractUsageFromFile(filePath) {
     let raw;
@@ -6094,7 +6129,7 @@ var HistoryService = class _HistoryService {
     try {
       files = fs11.readdirSync(projectDir).filter((f) => f.endsWith(".jsonl")).filter((f) => {
         try {
-          return fs11.statSync(path14.join(projectDir, f)).mtimeMs >= monthStartMs;
+          return fs11.statSync(path15.join(projectDir, f)).mtimeMs >= monthStartMs;
         } catch {
           return false;
         }
@@ -6105,7 +6140,7 @@ var HistoryService = class _HistoryService {
     for (const file of files) {
       let raw;
       try {
-        raw = fs11.readFileSync(path14.join(projectDir, file), "utf8");
+        raw = fs11.readFileSync(path15.join(projectDir, file), "utf8");
       } catch {
         continue;
       }
@@ -6147,8 +6182,8 @@ var HistoryService = class _HistoryService {
     const sessions3 = [];
     for (const entry of entries) {
       if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
-      const id = path14.basename(entry.name, ".jsonl");
-      const filePath = path14.join(dir, entry.name);
+      const id = path15.basename(entry.name, ".jsonl");
+      const filePath = path15.join(dir, entry.name);
       let mtime = Date.now();
       try {
         mtime = fs11.statSync(filePath).mtimeMs;
@@ -6189,7 +6224,7 @@ var HistoryService = class _HistoryService {
    * showing an empty conversation.
    */
   async loadConversation(sessionId) {
-    const filePath = path14.join(this.projectDir, `${sessionId}.jsonl`);
+    const filePath = path15.join(this.projectDir, `${sessionId}.jsonl`);
     const messages = parseJsonl(filePath);
     if (messages.length === 0) return;
     const totalBatches = Math.ceil(messages.length / CONVERSATION_BATCH_SIZE);
@@ -6232,7 +6267,7 @@ var HistoryService = class _HistoryService {
       if (!this.currentConversationId) return 0;
     }
     const sessionId = this.currentConversationId;
-    const filePath = path14.join(this.projectDir, `${sessionId}.jsonl`);
+    const filePath = path15.join(this.projectDir, `${sessionId}.jsonl`);
     const messages = parseJsonl(filePath);
     if (messages.length === 0) return 0;
     const marker = this.lastUploadedUuid.get(sessionId);
@@ -6263,7 +6298,7 @@ var HistoryService = class _HistoryService {
 // src/services/file-watcher.service.ts
 var import_child_process7 = require("child_process");
 var os13 = __toESM(require("os"));
-var path15 = __toESM(require("path"));
+var path16 = __toESM(require("path"));
 
 // src/services/file-watcher/diff-parser.ts
 var HUNK_HEADER_RE = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
@@ -6587,7 +6622,7 @@ var FileWatcherService = class {
   }
   async emitForFile(absPath, changeType) {
     if (this.stopped) return;
-    const relPath = path15.relative(this.opts.workingDir, absPath);
+    const relPath = path16.relative(this.opts.workingDir, absPath);
     if (!relPath || relPath.startsWith("..")) {
       return;
     }
@@ -7262,7 +7297,7 @@ function buildKeepAlive(ctx) {
 // src/commands/start/handlers.ts
 var fs14 = __toESM(require("fs"));
 var os14 = __toESM(require("os"));
-var path19 = __toESM(require("path"));
+var path20 = __toESM(require("path"));
 var import_crypto3 = require("crypto");
 var import_child_process11 = require("child_process");
 
@@ -7321,7 +7356,7 @@ function parsePayload(schema, raw) {
 
 // src/services/file-ops.service.ts
 var fs12 = __toESM(require("fs/promises"));
-var path16 = __toESM(require("path"));
+var path17 = __toESM(require("path"));
 var MAX_FILE_BYTES = 5 * 1024 * 1024;
 var MAX_WALK_DEPTH = 6;
 var MAX_VISITED_DIRS = 5e3;
@@ -7356,8 +7391,8 @@ var SUBDIR_IGNORE = /* @__PURE__ */ new Set([
   "__pycache__"
 ]);
 function isUnder(parent, candidate) {
-  const rel = path16.relative(parent, candidate);
-  return rel === "" || !rel.startsWith("..") && !path16.isAbsolute(rel);
+  const rel = path17.relative(parent, candidate);
+  return rel === "" || !rel.startsWith("..") && !path17.isAbsolute(rel);
 }
 async function isExistingFile(absPath) {
   try {
@@ -7380,7 +7415,7 @@ async function walkForSuffix(dir, needleVariants, depth, ctx) {
   }
   for (const e of entries) {
     if (!e.isFile()) continue;
-    const full = path16.join(dir, e.name);
+    const full = path17.join(dir, e.name);
     if (needleVariants.some((needle) => full.endsWith(needle))) {
       ctx.matches.push(full);
       if (ctx.matches.length >= ctx.cap) return;
@@ -7390,21 +7425,21 @@ async function walkForSuffix(dir, needleVariants, depth, ctx) {
     if (!e.isDirectory()) continue;
     if (SUBDIR_IGNORE.has(e.name)) continue;
     if (e.name.startsWith(".") && SUBDIR_IGNORE.has(e.name)) continue;
-    await walkForSuffix(path16.join(dir, e.name), needleVariants, depth + 1, ctx);
+    await walkForSuffix(path17.join(dir, e.name), needleVariants, depth + 1, ctx);
     if (ctx.matches.length >= ctx.cap) return;
   }
 }
 async function findFile(rawPath) {
   const cwd = process.cwd();
-  if (path16.isAbsolute(rawPath)) {
-    const abs = path16.normalize(rawPath);
+  if (path17.isAbsolute(rawPath)) {
+    const abs = path17.normalize(rawPath);
     if (isUnder(cwd, abs) && await isExistingFile(abs)) return abs;
   }
-  const direct = path16.resolve(cwd, rawPath);
+  const direct = path17.resolve(cwd, rawPath);
   if (isUnder(cwd, direct) && await isExistingFile(direct)) return direct;
-  const normalized = path16.normalize(rawPath).replace(/^[./\\]+/, "");
+  const normalized = path17.normalize(rawPath).replace(/^[./\\]+/, "");
   const needles = [
-    `${path16.sep}${normalized}`,
+    `${path17.sep}${normalized}`,
     `/${normalized}`
   ].filter((v, i, a) => a.indexOf(v) === i);
   const ctx = { visited: 0, matches: [], cap: 16 };
@@ -7418,7 +7453,7 @@ async function findWriteTarget(rawPath) {
   const found = await findFile(rawPath);
   if (found) return found;
   const cwd = process.cwd();
-  const fallback = path16.isAbsolute(rawPath) ? path16.normalize(rawPath) : path16.resolve(cwd, rawPath);
+  const fallback = path17.isAbsolute(rawPath) ? path17.normalize(rawPath) : path17.resolve(cwd, rawPath);
   if (!isUnder(cwd, fallback)) return null;
   return fallback;
 }
@@ -7458,7 +7493,7 @@ async function writeProjectFile(rawPath, content) {
     if (Buffer.byteLength(content, "utf-8") > MAX_FILE_BYTES) {
       return { error: "Content too large." };
     }
-    await fs12.mkdir(path16.dirname(abs), { recursive: true });
+    await fs12.mkdir(path17.dirname(abs), { recursive: true });
     await fs12.writeFile(abs, content, "utf-8");
     return { ok: true };
   } catch (e) {
@@ -7471,7 +7506,7 @@ async function writeProjectFile(rawPath, content) {
 var import_child_process9 = require("child_process");
 var import_util2 = require("util");
 var fs13 = __toESM(require("fs/promises"));
-var path17 = __toESM(require("path"));
+var path18 = __toESM(require("path"));
 var execFileP2 = (0, import_util2.promisify)(import_child_process9.execFile);
 var PROJECT_IGNORE = /* @__PURE__ */ new Set([
   "node_modules",
@@ -7529,12 +7564,12 @@ async function listProjectFiles(opts = {}) {
         return;
       }
       if (PROJECT_IGNORE.has(e.name)) continue;
-      const full = path17.join(dir, e.name);
+      const full = path18.join(dir, e.name);
       if (e.isDirectory()) {
         if (depth >= 12) continue;
         await walk(full, depth + 1);
       } else if (e.isFile()) {
-        const rel = path17.relative(root, full);
+        const rel = path18.relative(root, full);
         if (q2 && !rel.toLowerCase().includes(q2) && !e.name.toLowerCase().includes(q2)) {
           continue;
         }
@@ -7642,7 +7677,7 @@ async function gitStatus(cwd) {
   let hasMergeInProgress = false;
   try {
     const gitDir = (await git(["rev-parse", "--git-dir"], root)).stdout.trim();
-    const mergeHead = path17.isAbsolute(gitDir) ? path17.join(gitDir, "MERGE_HEAD") : path17.join(root, gitDir, "MERGE_HEAD");
+    const mergeHead = path18.isAbsolute(gitDir) ? path18.join(gitDir, "MERGE_HEAD") : path18.join(root, gitDir, "MERGE_HEAD");
     await fs13.access(mergeHead);
     hasMergeInProgress = true;
   } catch {
@@ -7789,7 +7824,7 @@ async function jsSearchFiles(opts, cwd, cap) {
     }
     let content = "";
     try {
-      content = await fs13.readFile(path17.join(cwd, f.path), "utf8");
+      content = await fs13.readFile(path18.join(cwd, f.path), "utf8");
     } catch {
       continue;
     }
@@ -8069,7 +8104,7 @@ function closeTerminal(sessionId) {
 function saveFilesTemp(files) {
   return files.filter(({ base64 }) => base64 && base64.length > 0).map(({ filename, base64 }) => {
     const safeName = filename.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80);
-    const tmpPath = path19.join(os14.tmpdir(), `codeam-${(0, import_crypto3.randomUUID)()}-${safeName}`);
+    const tmpPath = path20.join(os14.tmpdir(), `codeam-${(0, import_crypto3.randomUUID)()}-${safeName}`);
     fs14.writeFileSync(tmpPath, Buffer.from(base64, "base64"));
     return tmpPath;
   });
@@ -8592,8 +8627,9 @@ async function promptForAgent(initialValue) {
 // src/commands/pair.ts
 async function pair(args2 = []) {
   const config = loadCliConfig();
+  const dryRun = args2.includes("--dry-run");
   const flagAgent = parseAgentFlag(args2);
-  const agentId = flagAgent ?? await promptForAgent(config.preferredAgent ?? "claude");
+  const agentId = dryRun ? flagAgent ?? config.preferredAgent ?? "claude" : flagAgent ?? await promptForAgent(config.preferredAgent ?? "claude");
   showIntro();
   const pluginId = (0, import_crypto4.randomUUID)();
   const spin = dist_exports.spinner();
@@ -8605,6 +8641,20 @@ async function pair(args2 = []) {
     process.exit(1);
   }
   spin.stop("Got pairing code");
+  if (dryRun) {
+    const codeOk = typeof result.code === "string" && result.code.trim().length > 0;
+    const expiresOk = typeof result.expiresAt === "number" && result.expiresAt > 0;
+    if (!codeOk || !expiresOk) {
+      showError(
+        `Pair dry-run: backend response shape unexpected (codeType=${typeof result.code}, codeEmpty=${!codeOk}, expiresType=${typeof result.expiresAt}, expiresPositive=${expiresOk}).`
+      );
+      process.exit(1);
+    }
+    showSuccess(
+      `Pair dry-run OK \u2014 backend reachable, response shape valid (codeLength=${result.code.length}, expiresAt=${result.expiresAt}, agent=${agentId}).`
+    );
+    process.exit(0);
+  }
   showPairingCode(result.code);
   console.log(import_picocolors3.default.dim("  Scan the QR code or enter the code in CodeAgent Mobile."));
   console.log("");
@@ -8675,12 +8725,12 @@ function readTokenFromArgs(args2) {
   }
   const fileFlag = args2.find((a) => a.startsWith("--token-file="));
   if (fileFlag) {
-    const path28 = fileFlag.slice("--token-file=".length);
+    const path29 = fileFlag.slice("--token-file=".length);
     try {
-      const content = fs15.readFileSync(path28, "utf8").trim();
-      if (content.length === 0) fail(`--token-file ${path28} is empty`);
+      const content = fs15.readFileSync(path29, "utf8").trim();
+      if (content.length === 0) fail(`--token-file ${path29} is empty`);
       try {
-        fs15.unlinkSync(path28);
+        fs15.unlinkSync(path29);
       } catch {
       }
       return content;
@@ -8854,7 +8904,7 @@ var import_picocolors9 = __toESM(require("picocolors"));
 var import_child_process12 = require("child_process");
 var import_util3 = require("util");
 var import_picocolors7 = __toESM(require("picocolors"));
-var path20 = __toESM(require("path"));
+var path21 = __toESM(require("path"));
 var execFileP3 = (0, import_util3.promisify)(import_child_process12.execFile);
 var MAX_BUFFER = 8 * 1024 * 1024;
 function resetStdinForChild() {
@@ -9343,7 +9393,7 @@ var GitHubCodespacesProvider = class {
     });
   }
   async uploadFile(workspaceId, remotePath, contents, options = {}) {
-    const remoteDir = path20.posix.dirname(remotePath);
+    const remoteDir = path21.posix.dirname(remotePath);
     const parts = [
       `mkdir -p ${shellQuote(remoteDir)}`,
       `cat > ${shellQuote(remotePath)}`
@@ -9413,7 +9463,7 @@ function shellQuote(s) {
 // src/services/providers/gitpod.ts
 var import_child_process13 = require("child_process");
 var import_util4 = require("util");
-var path21 = __toESM(require("path"));
+var path22 = __toESM(require("path"));
 var import_picocolors8 = __toESM(require("picocolors"));
 var execFileP4 = (0, import_util4.promisify)(import_child_process13.execFile);
 var MAX_BUFFER2 = 8 * 1024 * 1024;
@@ -9653,7 +9703,7 @@ var GitpodProvider = class {
     });
   }
   async uploadFile(workspaceId, remotePath, contents, options = {}) {
-    const remoteDir = path21.posix.dirname(remotePath);
+    const remoteDir = path22.posix.dirname(remotePath);
     const parts = [
       `mkdir -p ${shellQuote2(remoteDir)}`,
       `cat > ${shellQuote2(remotePath)}`
@@ -9689,7 +9739,7 @@ function shellQuote2(s) {
 // src/services/providers/gitlab-workspaces.ts
 var import_child_process14 = require("child_process");
 var import_util5 = require("util");
-var path22 = __toESM(require("path"));
+var path23 = __toESM(require("path"));
 var execFileP5 = (0, import_util5.promisify)(import_child_process14.execFile);
 var MAX_BUFFER3 = 8 * 1024 * 1024;
 var GITLAB_API_BASE = process.env.CODEAM_GITLAB_API_URL ?? "https://gitlab.com/api/v4";
@@ -9949,7 +9999,7 @@ Docs: https://docs.gitlab.com/ee/user/workspace/configuration.html`
   }
   async uploadFile(workspaceId, remotePath, contents, options = {}) {
     const sshHost = process.env.CODEAM_GITLAB_SSH_HOST ?? "workspaces.gitlab.com";
-    const remoteDir = path22.posix.dirname(remotePath);
+    const remoteDir = path23.posix.dirname(remotePath);
     const parts = [`mkdir -p ${shellQuote3(remoteDir)}`, `cat > ${shellQuote3(remotePath)}`];
     if (options.mode != null) {
       parts.push(`chmod ${options.mode.toString(8)} ${shellQuote3(remotePath)}`);
@@ -10017,7 +10067,7 @@ function shellQuote3(s) {
 // src/services/providers/railway.ts
 var import_child_process15 = require("child_process");
 var import_util6 = require("util");
-var path23 = __toESM(require("path"));
+var path24 = __toESM(require("path"));
 var execFileP6 = (0, import_util6.promisify)(import_child_process15.execFile);
 var MAX_BUFFER4 = 8 * 1024 * 1024;
 function resetStdinForChild4() {
@@ -10253,7 +10303,7 @@ var RailwayProvider = class {
     if (!projectId || !serviceId) {
       throw new Error("Invalid Railway workspace id (expected projectId/serviceId).");
     }
-    const remoteDir = path23.posix.dirname(remotePath);
+    const remoteDir = path24.posix.dirname(remotePath);
     const parts = [`mkdir -p ${shellQuote4(remoteDir)}`, `cat > ${shellQuote4(remotePath)}`];
     if (options.mode != null) {
       parts.push(`chmod ${options.mode.toString(8)} ${shellQuote4(remotePath)}`);
@@ -10796,7 +10846,7 @@ async function stopWorkspaceFromLocal(target) {
 var import_node_child_process3 = require("child_process");
 var import_node_crypto = require("crypto");
 var fs18 = __toESM(require("fs"));
-var path26 = __toESM(require("path"));
+var path27 = __toESM(require("path"));
 var import_chokidar = __toESM(require("chokidar"));
 var import_picocolors11 = __toESM(require("picocolors"));
 
@@ -10804,7 +10854,7 @@ var import_picocolors11 = __toESM(require("picocolors"));
 var import_node_child_process2 = require("child_process");
 var fs16 = __toESM(require("fs"));
 var os16 = __toESM(require("os"));
-var path24 = __toESM(require("path"));
+var path25 = __toESM(require("path"));
 var import_node_util3 = require("util");
 var execFileP7 = (0, import_node_util3.promisify)(import_node_child_process2.execFile);
 var KEYCHAIN_SERVICE_NAMES = [
@@ -10816,8 +10866,8 @@ var KEYCHAIN_SERVICE_NAMES = [
 function claudeCredentialsPaths() {
   const home = os16.homedir();
   return [
-    path24.join(home, ".claude", ".credentials.json"),
-    path24.join(home, ".config", "claude", ".credentials.json")
+    path25.join(home, ".claude", ".credentials.json"),
+    path25.join(home, ".config", "claude", ".credentials.json")
   ];
 }
 async function extractLocalClaudeToken() {
@@ -10850,9 +10900,9 @@ async function extractLocalClaudeToken() {
 // src/agents/codex/local-token.ts
 var fs17 = __toESM(require("fs"));
 var os17 = __toESM(require("os"));
-var path25 = __toESM(require("path"));
+var path26 = __toESM(require("path"));
 function codexCredentialsPath() {
-  return path25.join(os17.homedir(), ".codex", "auth.json");
+  return path26.join(os17.homedir(), ".codex", "auth.json");
 }
 async function extractLocalCodexToken() {
   const file = codexCredentialsPath();
@@ -10920,11 +10970,12 @@ function parseLinkArgs(args2) {
     );
   }
   const reuseExisting = args2.includes("--reuse-existing");
+  const dryRun = args2.includes("--dry-run");
   const apiKeyArg = args2.find((a) => a.startsWith("--api-key="));
   const apiKey = apiKeyArg ? apiKeyArg.slice("--api-key=".length) : null;
   const tokenFileArg = args2.find((a) => a.startsWith("--token-file="));
   const tokenFile = tokenFileArg ? tokenFileArg.slice("--token-file=".length) : null;
-  return { agent: normalised, reuseExisting, apiKey, tokenFile };
+  return { agent: normalised, reuseExisting, apiKey, tokenFile, dryRun };
 }
 async function link(args2 = []) {
   const parsed = parseLinkArgs(args2);
@@ -10934,6 +10985,10 @@ async function link(args2 = []) {
     import_picocolors11.default.bold(`  Link ${meta.displayName}`) + import_picocolors11.default.dim(`  \xB7  ${meta.vendor}`)
   );
   console.log("");
+  if (parsed.dryRun) {
+    await linkDryRunPreflight(meta);
+    return;
+  }
   const pluginId = (0, import_node_crypto.randomUUID)();
   const spin = dist_exports.spinner();
   spin.start("Requesting pairing code...");
@@ -11001,7 +11056,7 @@ async function link(args2 = []) {
     return;
   }
   if (parsed.tokenFile) {
-    const credential = fs18.readFileSync(path26.resolve(parsed.tokenFile), "utf8").trim();
+    const credential = fs18.readFileSync(path27.resolve(parsed.tokenFile), "utf8").trim();
     if (!credential) {
       showError(`--token-file ${parsed.tokenFile} is empty.`);
       process.exit(1);
@@ -11153,11 +11208,42 @@ async function uploadAndSucceed(meta, paired, pluginId, token) {
   );
   console.log("");
 }
+async function linkDryRunPreflight(meta) {
+  const spin = dist_exports.spinner();
+  spin.start(`Probing ${meta.publicId} link endpoint...`);
+  const result = await postLinkCredential({
+    agentId: meta.publicId,
+    sessionId: "dryrun-session",
+    pluginId: "dryrun-plugin",
+    pluginAuthToken: "dryrun-token",
+    method: "oauth",
+    credential: "dryrun-credential"
+  });
+  if (result.ok) {
+    spin.stop("Unexpected 2xx");
+    showError(
+      "Link dry-run: backend accepted a stub credential (2xx). PluginAuthGuard appears to be disabled \u2014 investigate api-v2."
+    );
+    process.exit(1);
+  }
+  if (result.status === 401) {
+    spin.stop("Endpoint OK");
+    showSuccess(
+      `Link dry-run OK \u2014 /api/plugin/agents/${meta.publicId}/link reachable and auth-gated (401 as expected).`
+    );
+    process.exit(0);
+  }
+  spin.stop("Failed");
+  showError(
+    `Link dry-run: unexpected response from /api/plugin/agents/${meta.publicId}/link (status=${result.status}, message=${result.message}). Expected 401.`
+  );
+  process.exit(1);
+}
 
 // src/commands/version.ts
 var import_picocolors12 = __toESM(require("picocolors"));
 function version() {
-  const v = true ? "2.16.2" : "unknown";
+  const v = true ? "2.17.1" : "unknown";
   console.log(`${import_picocolors12.default.bold("codeam-cli")} ${import_picocolors12.default.cyan(v)}`);
 }
 
@@ -11198,19 +11284,81 @@ function help() {
   process.stdout.write(lines.join("\n") + "\n");
 }
 
+// src/commands/subcommand-help.ts
+var import_picocolors14 = __toESM(require("picocolors"));
+var HELPS = {
+  pair: () => print([
+    `  ${import_picocolors14.default.bold("codeam pair")}  ${import_picocolors14.default.dim("\u2014 pair a mobile device with this CLI")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam pair")}                  ${import_picocolors14.default.dim("interactive pairing (prompts for the agent)")}`,
+    `     ${import_picocolors14.default.cyan("codeam pair --agent <id>")}     ${import_picocolors14.default.dim("pair non-interactively (agent: claude | codex)")}`,
+    `     ${import_picocolors14.default.cyan("codeam pair --dry-run")}        ${import_picocolors14.default.dim("request a pairing code, validate the response, exit")}`
+  ]),
+  "pair-auto": () => print([
+    `  ${import_picocolors14.default.bold("codeam pair-auto")}  ${import_picocolors14.default.dim("\u2014 non-interactive variant of pair for scripted setups")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam pair-auto --agent <id>")}  ${import_picocolors14.default.dim("pair using the supplied agent id; exit on success or timeout")}`
+  ]),
+  link: () => print([
+    `  ${import_picocolors14.default.bold("codeam link <agent>")}  ${import_picocolors14.default.dim("\u2014 upload a local agent token (Claude or Codex) to your vault")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam link claude")}`,
+    `     ${import_picocolors14.default.cyan("codeam link codex")}`,
+    "",
+    `     ${import_picocolors14.default.white("--api-key=<key>")}      ${import_picocolors14.default.dim("paste an API key directly (skip the local auth flow)")}`,
+    `     ${import_picocolors14.default.white("--reuse-existing")}     ${import_picocolors14.default.dim("upload existing creds without re-launching the agent login")}`,
+    `     ${import_picocolors14.default.white("--token-file=<path>")}  ${import_picocolors14.default.dim("manual credential blob path for unusual vendor locations")}`,
+    `     ${import_picocolors14.default.white("--dry-run")}            ${import_picocolors14.default.dim("probe the /api/plugin/agents/<agent>/link endpoint and exit")}`
+  ]),
+  sessions: () => print([
+    `  ${import_picocolors14.default.bold("codeam sessions")}  ${import_picocolors14.default.dim("\u2014 list, switch, or delete paired mobile sessions")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam sessions")}              ${import_picocolors14.default.dim("list all paired sessions on this machine")}`,
+    `     ${import_picocolors14.default.cyan("codeam sessions switch")}       ${import_picocolors14.default.dim("interactively switch the active session")}`,
+    `     ${import_picocolors14.default.cyan("codeam sessions delete <id>")}  ${import_picocolors14.default.dim("remove a specific paired session")}`
+  ]),
+  deploy: () => print([
+    `  ${import_picocolors14.default.bold("codeam deploy")}  ${import_picocolors14.default.dim("\u2014 provision a cloud workspace (GitHub Codespaces) and pair it")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam deploy")}                ${import_picocolors14.default.dim("start a new deploy (prompts for repo + agent)")}`,
+    `     ${import_picocolors14.default.cyan("codeam deploy ls | list")}      ${import_picocolors14.default.dim("list deployed cloud workspaces")}`,
+    `     ${import_picocolors14.default.cyan("codeam deploy stop | remove")}  ${import_picocolors14.default.dim("pick a workspace and stop its codeam-pair session")}`
+  ]),
+  status: () => print([
+    `  ${import_picocolors14.default.bold("codeam status")}  ${import_picocolors14.default.dim("\u2014 show the active session, agent, and connection info")}`
+  ]),
+  logout: () => print([
+    `  ${import_picocolors14.default.bold("codeam logout")}  ${import_picocolors14.default.dim("\u2014 remove every paired session from this machine")}`
+  ])
+};
+function print(lines) {
+  process.stdout.write(["", ...lines, ""].join("\n") + "\n");
+}
+function isHelpFlag(arg) {
+  return arg === "--help" || arg === "-h";
+}
+function tryShowSubcommandHelp(cmd, args2) {
+  if (!isHelpFlag(args2[0])) return false;
+  const renderer = HELPS[cmd];
+  if (!renderer) return false;
+  renderer();
+  return true;
+}
+var _subcommandHelpKeys = Object.keys(HELPS);
+
 // src/lib/updateNotifier.ts
 var fs19 = __toESM(require("fs"));
 var os18 = __toESM(require("os"));
-var path27 = __toESM(require("path"));
+var path28 = __toESM(require("path"));
 var https7 = __toESM(require("https"));
-var import_picocolors14 = __toESM(require("picocolors"));
+var import_picocolors15 = __toESM(require("picocolors"));
 var PKG_NAME = "codeam-cli";
 var REGISTRY_URL = `https://registry.npmjs.org/${PKG_NAME}/latest`;
 var TTL_MS = 24 * 60 * 60 * 1e3;
 var REQUEST_TIMEOUT_MS = 1500;
 function cachePath() {
-  const dir = path27.join(os18.homedir(), ".codeam");
-  return path27.join(dir, "update-check.json");
+  const dir = path28.join(os18.homedir(), ".codeam");
+  return path28.join(dir, "update-check.json");
 }
 function readCache() {
   try {
@@ -11225,7 +11373,7 @@ function readCache() {
 function writeCache(cache) {
   try {
     const file = cachePath();
-    fs19.mkdirSync(path27.dirname(file), { recursive: true });
+    fs19.mkdirSync(path28.dirname(file), { recursive: true });
     fs19.writeFileSync(file, JSON.stringify(cache));
   } catch {
   }
@@ -11282,11 +11430,11 @@ function fetchLatest() {
 }
 function notifyIfStale(currentVersion, latest) {
   if (compareSemver(latest, currentVersion) <= 0) return;
-  const arrow = import_picocolors14.default.dim("\u2192");
-  const cmd = import_picocolors14.default.cyan("npm install -g codeam-cli");
+  const arrow = import_picocolors15.default.dim("\u2192");
+  const cmd = import_picocolors15.default.cyan("npm install -g codeam-cli");
   const lines = [
     "",
-    `  ${import_picocolors14.default.yellow("\u25CF")} ${import_picocolors14.default.bold("Update available")} ${import_picocolors14.default.dim(currentVersion)} ${arrow} ${import_picocolors14.default.green(latest)}`,
+    `  ${import_picocolors15.default.yellow("\u25CF")} ${import_picocolors15.default.bold("Update available")} ${import_picocolors15.default.dim(currentVersion)} ${arrow} ${import_picocolors15.default.green(latest)}`,
     `    Run ${cmd} to upgrade.`,
     ""
   ];
@@ -11297,7 +11445,7 @@ function checkForUpdates() {
   if (process.env.CODEAM_DISABLE_UPDATE_CHECK === "1") return;
   if (process.env.CI) return;
   if (!process.stdout.isTTY) return;
-  const current = true ? "2.16.2" : null;
+  const current = true ? "2.17.1" : null;
   if (!current) return;
   const cache = readCache();
   const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
@@ -11316,6 +11464,9 @@ var [, , command, ...args] = process.argv;
 async function main() {
   const isMetaCommand = command === "--version" || command === "-v" || command === "version" || command === "--help" || command === "-h" || command === "help";
   if (!isMetaCommand) checkForUpdates();
+  if (typeof command === "string" && tryShowSubcommandHelp(command, args)) {
+    return;
+  }
   switch (command) {
     case "--version":
     case "-v":