wisp-agents 0.2.1 → 0.3.0

package/server/proc.js

@@ -0,0 +1,127 @@
+// Cross-platform process launching. On macOS/Linux this is a thin wrapper over spawn(). On
+// Windows, CLIs installed through npm (claude, codex, opencode…) are `.cmd` shims, which
+// spawn() can't start without a shell. Wrapping them in cmd.exe would mangle arguments wisp
+// passes (JSON, newlines in the system prompt), so npm shims are unwrapped into
+// `node <script>` and only unknown batch files go through cmd.exe, with careful escaping.
+
+import { spawn as nodeSpawn, execFile as nodeExecFile, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Find `bin` on PATH the way cmd.exe would (PATHEXT). Returns an absolute path or null.
+// A copied env object loses Windows' case-insensitive keys, so PATH may be spelled "Path".
+export function whichWindows(bin, env = process.env) {
+  const p = path.win32;
+  const exts = (env.PATHEXT || env.Pathext || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((e) => e.toLowerCase());
+  // .ps1 isn't in PATHEXT, but some installers (Cursor) only drop a PowerShell script.
+  const names = p.extname(bin) ? [bin] : [...exts.map((e) => bin + e), bin + '.ps1'];
+  const dirs = /[\\/]/.test(bin) ? [''] : (env.PATH ?? env.Path ?? '').split(';').filter(Boolean);
+  for (const dir of dirs) {
+    for (const name of names) {
+      const full = dir ? p.join(dir, name) : name;
+      try {
+        if (fs.statSync(full).isFile()) return full;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+// npm/pnpm/yarn `.cmd` shims end by running node on a script, or by running the target directly:
+//   ... & "%_prog%"  "%dp0%\node_modules\@openai\codex\bin\codex.js" %*
+//   "%~dp0\node.exe"  "%~dp0\..\opencode-ai\bin\opencode" %*
+//   "%dp0%\node_modules\some-cli\bin\tool.exe"   %*
+// Returns { script } or { exe }, relative to the shim's folder, or null if it isn't recognisable.
+export function parseCmdShim(text) {
+  const line = String(text).split(/\r?\n/).map((l) => l.trim()).findLast((l) => /%\*$/.test(l));
+  if (!line) return null;
+  const quoted = [...line.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+  const fromDp0 = (s) => s?.match(/^%~?dp0%?\\?(.+)$/i)?.[1] ?? null;
+  const target = fromDp0(quoted.at(-1));
+  if (!target) return null;
+  const prog = quoted.length > 1 ? quoted.at(-2) : '';
+  if (/^%_prog%$|(^|\\)node(\.exe)?$/i.test(prog) || /\.[cm]?js$/i.test(target)) return { script: target };
+  if (/\.(exe|com)$/i.test(target)) return { exe: target };
+  return null;
+}
+
+// cmd.exe escaping, as in cross-spawn: quote for CommandLineToArgvW, then caret-escape cmd's
+// metacharacters (twice when the target is itself a batch file, which re-parses its line).
+const META = /([()\][%!^"`<>&|;, *?])/g;
+export const escapeCmdCommand = (s) => String(s).replace(META, '^$1');
+export function escapeCmdArgument(arg, doubleEscape = false) {
+  let s = String(arg);
+  s = s.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+  s = s.replace(/(?=(\\+?)?)\1$/, '$1$1');
+  s = `"${s}"`.replace(META, '^$1');
+  return doubleEscape ? s.replace(META, '^$1') : s;
+}
+
+// Resolve `bin args` into something spawn() can run directly on this platform.
+// Returns { command, args, verbatim }; verbatim => pass windowsVerbatimArguments.
+export function resolveCommand(bin, args = [], { platform = process.platform, env = process.env } = {}) {
+  if (platform !== 'win32') return { command: bin, args, verbatim: false };
+  const file = whichWindows(bin, env);
+  if (!file) return { command: bin, args, verbatim: false }; // let spawn report ENOENT
+  const ext = path.win32.extname(file).toLowerCase();
+  if (ext === '.exe' || ext === '.com') return { command: file, args, verbatim: false };
+  if (ext === '.ps1') {
+    return { command: 'powershell.exe', args: ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', file, ...args], verbatim: false };
+  }
+  if (ext === '.cmd' || ext === '.bat') {
+    let shim = null;
+    try {
+      shim = parseCmdShim(fs.readFileSync(file, 'utf8'));
+    } catch {}
+    const dir = path.win32.dirname(file);
+    if (shim?.exe) {
+      const exe = path.win32.resolve(dir, shim.exe);
+      if (fs.existsSync(exe)) return { command: exe, args, verbatim: false };
+    }
+    if (shim?.script) {
+      const script = path.win32.resolve(dir, shim.script);
+      if (fs.existsSync(script)) {
+        const localNode = path.win32.join(dir, 'node.exe');
+        return { command: fs.existsSync(localNode) ? localNode : whichWindows('node', env) || 'node', args: [script, ...args], verbatim: false };
+      }
+    }
+    // Unknown batch file: go through cmd.exe. Newlines can't survive cmd's parser.
+    const line = [escapeCmdCommand(file), ...args.map((a) => escapeCmdArgument(String(a).replace(/\r?\n/g, ' '), true))].join(' ');
+    return { command: env.ComSpec || env.COMSPEC || 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], verbatim: true };
+  }
+  return { command: file, args, verbatim: false };
+}
+
+export function spawn(bin, args, opts = {}) {
+  const r = resolveCommand(bin, args, { env: opts.env || process.env });
+  return nodeSpawn(r.command, r.args, { ...opts, windowsHide: true, windowsVerbatimArguments: r.verbatim });
+}
+
+export function execFile(bin, args, opts, cb) {
+  const r = resolveCommand(bin, args, { env: opts?.env || process.env });
+  return nodeExecFile(r.command, r.args, { ...opts, windowsHide: true, windowsVerbatimArguments: r.verbatim }, cb);
+}
+
+// Stop a child and everything it started. On Windows, kill() only ends the direct child
+// (e.g. node, leaving the agent's own subprocesses running), so use taskkill /T.
+export function killTree(child) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  if (process.platform === 'win32' && child.pid) {
+    const r = spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    if (r.status === 0) return;
+  }
+  child.kill('SIGTERM');
+}
+
+// Is `bin` runnable from PATH?
+export function onPath(bin, env = process.env) {
+  if (process.platform === 'win32') return !!whichWindows(bin, env);
+  return (env.PATH || '').split(path.delimiter).some((d) => {
+    try {
+      fs.accessSync(path.join(d, bin), fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}

package/server/protocol.js

@@ -2,7 +2,7 @@
 // Agent-agnostic — any harness that can take an extra system prompt (or a prompt
 // prefix) and return a final text message can speak it.
 
-export const SYSTEM_PROMPT = `
+const PROTOCOL = `
 # You are running inside wisp
 
 wisp launched you to do a task on the user's behalf. The user is a software engineer who will NOT
@@ -10,9 +10,7 @@ read your transcript, tool calls or intermediate messages. The only thing they w
 presentation you put in your final message. Work autonomously:
 
 - Make sensible assumptions for small decisions, note them, keep going.
-- If a decision would change the rest of the work (ambiguous requirement, destructive or risky step,
-  two very different approaches), call the \`ask_user\` tool (mcp__wisp__ask_user). It pauses you until
-  the user answers in wisp — you keep all your context. Ask one crisp question with 2–4 options.
+{{ASK}}
 - If the task is done but there is a choice for later, end with a "question" block instead.
 - Verify your work where it is cheap (tests, type-check, lint, build) and report results honestly,
   including failures. Never claim something passes that you did not run.
@@ -76,6 +74,17 @@ Strings must be valid JSON (escape newlines as \\n and quotes as \\"). Example:
 \`\`\`
 `.trim();
 
+const ASK_TOOL = (tool) => `- If a decision would change the rest of the work (ambiguous requirement, destructive or risky step,
+  two very different approaches), call the \`ask_user\` tool (${tool}). It pauses you until
+  the user answers in wisp — you keep all your context. Ask one crisp question with 2–4 options.`;
+const ASK_BLOCK = `- If a decision would change the rest of the work (ambiguous requirement, destructive or risky step,
+  two very different approaches), stop before acting on it and end with a "question" block (2–4 options).
+  The user's answer comes back as a follow-up in this same session.`;
+
+// askTool: how the harness names wisp's injected ask_user tool, or null if it can't take one.
+export const systemPrompt = ({ askTool = 'mcp__wisp__ask_user' } = {}) => PROTOCOL.replace('{{ASK}}', askTool ? ASK_TOOL(askTool) : ASK_BLOCK);
+export const SYSTEM_PROMPT = systemPrompt();
+
 // Only the opener is matched by regex. The closing fence can't be: the JSON itself often
 // contains ``` (a markdown block with a code sample), and a lazy match would cut it there.
 const OPEN = /```wisp[^\n]*\n/g;

package/server/runner.js

@@ -1,14 +1,17 @@
 // Session orchestration: launches turns on adapters, folds their events into the
-// session record, and queues follow-ups that arrive while the agent is busy.
+// session record, and handles follow-ups that arrive while the agent is busy: by default
+// they interrupt the run and resume the session with the new message; with the `queue`
+// setting they wait until the run finishes.
 
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { adapters } from './adapters/index.js';
-import { SYSTEM_PROMPT, parsePresentation, heroOf } from './protocol.js';
+import { systemPrompt, parsePresentation, heroOf } from './protocol.js';
 
 const MAX_ACTIVITY = 400;
+const LINGER_MS = 3000; // how long a CLI may keep running after it reported its result
 const ASK_SERVER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'mcp-ask.js');
 
 export const newId = () => randomUUID().replace(/-/g, '').slice(0, 12);
@@ -35,6 +38,7 @@ export function summarize(s, store) {
     model: s.model,
     state: s.state,
     unread: s.unread,
+    archived: !!s.archived,
     createdAt: s.createdAt,
     updatedAt: s.updatedAt,
     turnCount: s.turns.length,
@@ -55,6 +59,7 @@ export class Runner extends EventEmitter {
     this.bridge = bridge;
     this.live = new Map(); // sessionId -> adapter handle
     this.stopping = new Set();
+    this.interrupting = new Set();
     this.answers = new Map(); // askId -> answer, until the MCP server picks it up
 
     // Anything that was mid-flight when wisp last died is now orphaned.
@@ -94,20 +99,46 @@ export class Runner extends EventEmitter {
     return session;
   }
 
-  reply(session, text, attachments = []) {
+  reply(session, text, attachments = [], { queue = false } = {}) {
     if (session.ask) {
       this.answer(session, text);
       return { answered: true };
     }
-    if (this.live.has(session.id)) {
-      session.queue.push({ text, attachments });
-      this.#touch(session);
-      return { queued: true };
+    const handle = this.live.get(session.id);
+    if (handle) {
+      const turn = session.turns.at(-1);
+      // The run already produced its result and the CLI is only lingering on its way out:
+      // there's nothing to wait for, so let it go and start the follow-up now.
+      if (turn?.status !== 'running') {
+        session.queue.push({ id: newId(), text, attachments });
+        handle.release();
+        return { queued: session.queue.length > 0 };
+      }
+      // Interrupting needs an agent session to resume; before the agent reports one, queue.
+      if (queue || !session.agentSessionId) {
+        session.queue.push({ id: newId(), text, attachments });
+        this.#touch(session);
+        return { queued: true, ahead: session.queue.length - 1 };
+      }
+      // Ahead of anything queued, but after earlier interrupting follow-ups, so they keep their order.
+      const at = session.queue.findIndex((q) => !q.now);
+      session.queue.splice(at < 0 ? session.queue.length : at, 0, { id: newId(), text, attachments, now: true });
+      this.#interrupt(session);
+      return { interrupted: true };
     }
     this.#startTurn(session, text, attachments);
     return { queued: false };
   }
 
+  // Drop a follow-up that hasn't gone out yet.
+  unqueue(session, itemId) {
+    const at = session.queue.findIndex((q) => q.id === itemId);
+    if (at < 0) return false;
+    session.queue.splice(at, 1);
+    this.#touch(session);
+    return true;
+  }
+
   // ask_user: the agent is blocked inside a tool call until answer() is called.
   ask(session, { question, context, options }) {
     const turn = session.turns.at(-1);
@@ -120,6 +151,7 @@ export class Runner extends EventEmitter {
     };
     session.state = 'waiting';
     session.unread = true;
+    delete session.archived; // a question needs the user, so it comes back to the feed
     if (turn) this.#onEvent(session, turn, { type: 'tool', kind: 'ask', label: `Asked you: ${session.ask.question}` });
     this.#touch(session, { turn: turn?.id });
     this.emit('finished', { session: summarize(session, this.store) });
@@ -157,10 +189,20 @@ export class Runner extends EventEmitter {
     this.live.get(session.id).stop();
   }
 
+  // Stop the current run but keep the queue: done.finally() starts the next follow-up.
+  #interrupt(session) {
+    if (this.interrupting.has(session.id)) return; // already on its way down
+    this.interrupting.add(session.id);
+    this.stopping.add(session.id);
+    this.live.get(session.id).stop();
+  }
+
   #startTurn(session, prompt, attachments = []) {
     const turn = {
       id: newId(),
       prompt,
+      agent: session.agent,
+      model: session.model,
       attachments: attachments.map(({ id, name, mime, size }) => ({ id, name, mime, size })),
       startedAt: Date.now(),
       endedAt: null,
@@ -173,8 +215,11 @@ export class Runner extends EventEmitter {
     session.turns.push(turn);
     session.state = 'running';
     session.unread = false;
+    delete session.archived;
     this.#touch(session, { turn: turn.id });
 
+    let released = false;
+    let linger;
     const adapter = adapters[session.agent];
     const handle = adapter.run({
       prompt,
@@ -183,27 +228,44 @@ export class Runner extends EventEmitter {
       resumeId: session.agentSessionId,
       mode: session.mode,
       model: session.model,
-      systemPrompt: SYSTEM_PROMPT,
-      mcpServers: this.bridge
+      systemPrompt: systemPrompt({ askTool: adapter.askTool }),
+      mcpServers: this.bridge && adapter.askTool !== null
         ? {
             wisp: {
               command: process.execPath,
               args: [ASK_SERVER],
-              env: { WISP_URL: this.bridge.url, WISP_TOKEN: this.bridge.token, WISP_SESSION: session.id },
+              // Inside the desktop app execPath is the Electron binary; without
+              // ELECTRON_RUN_AS_NODE it boots a second app (extra Dock icon) per turn.
+              env: { ELECTRON_RUN_AS_NODE: '1', WISP_URL: this.bridge.url, WISP_TOKEN: this.bridge.token, WISP_SESSION: session.id },
             },
           }
         : {},
-      onEvent: (ev) => this.#onEvent(session, turn, ev),
+      onEvent: (ev) => {
+        if (released) return; // a lingering process we already let go of
+        this.#onEvent(session, turn, ev);
+        // A CLI can outlive its result (flushing, or a background process it spawned holding
+        // stdout open, so 'close' never fires). Don't hold the session hostage to that.
+        if (ev.type === 'result') linger = setTimeout(release, LINGER_MS);
+      },
     });
-    this.live.set(session.id, handle);
-
-    handle.done.finally(() => {
-      this.live.delete(session.id);
+    // Ends the run exactly once: on exit, LINGER_MS after the result, or when a follow-up arrives.
+    const release = () => {
+      if (released) return;
       if (turn.status === 'running') this.#finishTurn(session, turn, { isError: true, text: 'The agent exited without a result.' });
+      released = true;
+      clearTimeout(linger);
+      handle.stop();
+      if (this.live.get(session.id) !== handle) return;
+      this.live.delete(session.id);
+      this.interrupting.delete(session.id);
+      this.stopping.delete(session.id); // a stop that landed after the result has nothing left to stop
       const next = session.queue.shift();
       if (next && this.store.get(session.id)) this.#startTurn(session, next.text, next.attachments);
       else this.#touch(session);
-    });
+    };
+    handle.release = release;
+    this.live.set(session.id, handle);
+    handle.done.finally(release);
   }
 
   #onEvent(session, turn, ev) {
@@ -243,11 +305,14 @@ export class Runner extends EventEmitter {
     turn.stats = ev.stats || null;
     delete session.ask;
     if (this.stopping.delete(session.id)) ev = { ...ev, stopped: true };
+    const interrupted = ev.stopped && this.interrupting.has(session.id);
     if (ev.stopped) {
       turn.status = 'stopped';
       turn.presentation = {
         blocks: [
-          { type: 'hero', title: 'Stopped', summary: reason || 'You stopped this run. Follow up to pick it back up.', status: 'partial' },
+          interrupted
+            ? { type: 'hero', title: 'Interrupted', summary: 'You sent a follow-up while this was running, so it picked that up instead.', status: 'partial' }
+            : { type: 'hero', title: 'Stopped', summary: reason || 'You stopped this run. Follow up to pick it back up.', status: 'partial' },
           ...(turn.changes.length ? [{ type: 'files', items: turn.changes.map((c) => ({ path: c.file, change: c.op === 'create' ? 'added' : 'modified' })) }] : []),
         ],
       };
@@ -264,14 +329,16 @@ export class Runner extends EventEmitter {
       turn.status = 'done';
       turn.raw = ev.text; // kept so the turn can be re-parsed if the parser improves
       turn.presentation = parsePresentation(ev.text);
+      this.store.keepImages(session, turn);
       const hero = heroOf(turn.presentation);
       if (hero?.title && session.titleAuto && session.turns.length === 1) session.title = hero.title;
     }
     session.state = 'review';
-    session.unread = true;
+    session.unread = !interrupted;
     this.store.save(session, { now: true });
     this.#touch(session, { turn: turn.id });
-    this.emit('finished', { session: summarize(session, this.store) });
+    // The follow-up starts right away; don't notify for the run it replaced.
+    if (!interrupted) this.emit('finished', { session: summarize(session, this.store) });
   }
 
   #touch(session, { turn, quiet } = {}) {

package/server/store.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { parsePresentation } from './protocol.js';
 
 const DEFAULT_CONFIG = {
@@ -10,12 +11,16 @@ const DEFAULT_CONFIG = {
   defaults: { agent: 'claude', mode: 'edits', model: '' },
 };
 
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
+const MAX_KEPT_IMAGE = 25 * 1024 * 1024;
+
 export const PROJECT_COLORS = ['violet', 'teal', 'amber', 'rose', 'sky', 'lime', 'orange', 'indigo'];
 
 export class Store {
   constructor(home = process.env.WISP_HOME || path.join(os.homedir(), '.wisp')) {
     this.home = home;
     this.dir = path.join(home, 'sessions');
+    this.shots = path.join(home, 'shots');
     fs.mkdirSync(this.dir, { recursive: true });
     this.sessions = new Map();
     this.timers = new Map();
@@ -27,6 +32,10 @@ export class Store {
         const s = JSON.parse(fs.readFileSync(path.join(this.dir, f), 'utf8'));
         reparse(s);
         this.sessions.set(s.id, s);
+        // Backfill: follow-ups queued before items had ids can't be cancelled without one.
+        const ids = (s.queue || []).filter((q) => !q.id).map((q) => (q.id = randomUUID().replace(/-/g, '').slice(0, 12)));
+        // Backfill: keep screenshots from older turns while their files still exist.
+        if ((s.turns || []).map((t) => this.keepImages(s, t)).some(Boolean) || ids.length) this.save(s, { now: true });
       } catch (err) {
         console.warn(`wisp: skipping unreadable session ${f}: ${err.message}`);
       }
@@ -111,6 +120,34 @@ export class Store {
     clearTimeout(this.timers.get(id));
     this.sessions.delete(id);
     fs.rmSync(path.join(this.dir, `${id}.json`), { force: true });
+    fs.rmSync(path.join(this.shots, id), { recursive: true, force: true });
+  }
+
+  // Agents save screenshots to /tmp, which macOS clears. Copy every local image a turn shows
+  // into ~/.wisp/shots/<session>/ and point the block at the copy; `source` keeps the original.
+  keepImages(session, turn) {
+    let changed = false;
+    (turn.presentation?.blocks || []).forEach((b, i) => {
+      const rel = b?.type === 'image' && (b.path || b.src);
+      if (typeof rel !== 'string' || !rel || /^https?:/.test(rel)) return;
+      const src = path.resolve(session.cwd || this.home, rel);
+      const ext = path.extname(src).toLowerCase();
+      if (!IMAGE_EXT.has(ext) || src.startsWith(this.shots + path.sep)) return;
+      try {
+        const st = fs.statSync(src);
+        if (!st.isFile() || st.size > MAX_KEPT_IMAGE) return;
+        const dir = path.join(this.shots, session.id);
+        fs.mkdirSync(dir, { recursive: true });
+        const dest = path.join(dir, `${turn.id}-${i}${ext}`);
+        fs.copyFileSync(src, dest);
+        Object.assign(b, { path: dest, source: rel });
+        delete b.src;
+        changed = true;
+      } catch {
+        // gone or unreadable: leave the block as it was
+      }
+    });
+    return changed;
   }
 
   flush() {

package/server/terminal.js

@@ -1,73 +1,127 @@
 // Open a command in the user's terminal so they can take over an agent session interactively.
+//
+// terminalPlan() is pure (platform and PATH lookups are injected) so every platform's command
+// line can be tested anywhere; openInTerminal() runs the plan.
 
-import { spawn, execFileSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import { escapeCmdArgument, escapeCmdCommand, onPath } from './proc.js';
 
-export const TERMINALS = [
+// os: which platforms list the entry (all if omitted).
+const ALL_TERMINALS = [
   { id: 'auto', label: 'Auto-detect' },
-  { id: 'terminal', label: 'Terminal.app', mac: true },
-  { id: 'iterm', label: 'iTerm', mac: true, app: '/Applications/iTerm.app' },
-  { id: 'ghostty', label: 'Ghostty', app: '/Applications/Ghostty.app', bin: 'ghostty' },
-  { id: 'warp', label: 'Warp', mac: true, app: '/Applications/Warp.app' },
-  { id: 'kitty', label: 'kitty', app: '/Applications/kitty.app', bin: 'kitty' },
-  { id: 'wezterm', label: 'WezTerm', app: '/Applications/WezTerm.app', bin: 'wezterm' },
+  { id: 'terminal', label: 'Terminal.app', os: ['darwin'] },
+  { id: 'iterm', label: 'iTerm', os: ['darwin'] },
+  { id: 'warp', label: 'Warp', os: ['darwin'] },
+  { id: 'wt', label: 'Windows Terminal', os: ['win32'] },
+  { id: 'powershell', label: 'PowerShell', os: ['win32'] },
+  { id: 'cmd', label: 'Command Prompt', os: ['win32'] },
+  { id: 'ghostty', label: 'Ghostty', os: ['darwin', 'linux'] },
+  { id: 'kitty', label: 'kitty', os: ['darwin', 'linux'] },
+  { id: 'wezterm', label: 'WezTerm' },
+  { id: 'gnome-terminal', label: 'GNOME Terminal', os: ['linux'] },
+  { id: 'konsole', label: 'Konsole', os: ['linux'] },
+  { id: 'xfce4-terminal', label: 'Xfce Terminal', os: ['linux'] },
+  { id: 'alacritty', label: 'Alacritty', os: ['linux'] },
+  { id: 'xterm', label: 'xterm', os: ['linux'] },
   { id: 'custom', label: 'Custom command' },
 ];
 
+export const terminalsFor = (platform = process.platform) => ALL_TERMINALS.filter((t) => !t.os || t.os.includes(platform === 'darwin' || platform === 'win32' ? platform : 'linux')).map(({ id, label }) => ({ id, label }));
+export const TERMINALS = terminalsFor();
+
 export const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const psq = (s) => `'${String(s).replace(/'/g, "''")}'`; // PowerShell single-quoted string
+const asStr = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`; // AppleScript string
 
-const has = (bin) => {
-  try {
-    execFileSync('which', [bin], { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-};
+const LINUX_ORDER = ['ghostty', 'kitty', 'wezterm', 'gnome-terminal', 'konsole', 'xfce4-terminal', 'alacritty', 'x-terminal-emulator', 'xterm'];
 
-function detect() {
-  if (process.platform === 'darwin') {
-    if (process.env.TERM_PROGRAM === 'iTerm.app' && fs.existsSync('/Applications/iTerm.app')) return 'iterm';
-    if (process.env.TERM_PROGRAM === 'ghostty' && fs.existsSync('/Applications/Ghostty.app')) return 'ghostty';
+export function detectTerminal({ platform = process.platform, env = process.env, has = (b) => onPath(b, env), exists = fs.existsSync } = {}) {
+  if (platform === 'darwin') {
+    if (env.TERM_PROGRAM === 'iTerm.app' && exists('/Applications/iTerm.app')) return 'iterm';
+    if (env.TERM_PROGRAM === 'ghostty' && exists('/Applications/Ghostty.app')) return 'ghostty';
     return 'terminal';
   }
-  for (const t of ['ghostty', 'kitty', 'wezterm']) if (has(t)) return t;
-  return 'x-terminal-emulator';
+  if (platform === 'win32') return env.WT_SESSION || has('wt') ? 'wt' : 'powershell';
+  return LINUX_ORDER.find((t) => has(t)) || 'xterm';
 }
 
-const osa = (script) => spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
-const asStr = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-
-// argv: the agent's resume command, e.g. ['claude', '--resume', 'abc'].
-export function openInTerminal({ cwd, argv, terminal = 'auto', custom = '' }) {
+// Returns a list of steps: { command, args, options? } to spawn, { osa } to run as AppleScript,
+// or { delay } in ms. argv is the agent's resume command, e.g. ['claude', '--resume', 'abc'].
+export function terminalPlan({ cwd, argv, terminal = 'auto', custom = '', platform = process.platform, env = process.env, has, exists } = {}) {
+  const t = terminal === 'auto' ? detectTerminal({ platform, env, has, exists }) : terminal;
+  const mac = platform === 'darwin';
+  const win = platform === 'win32';
   const cmd = argv.map(shq).join(' ');
   const line = `cd ${shq(cwd)} && ${cmd}`;
-  const t = terminal === 'auto' ? detect() : terminal;
-  const mac = process.platform === 'darwin';
+  // Linux terminals: run the command, then leave an interactive shell open in the project.
+  const keepOpen = ['sh', '-c', `${cmd}; exec "\${SHELL:-sh}"`];
+  // Windows: `& 'codex' 'resume' 'id'` works for .exe, .cmd and .ps1 alike.
+  const ps = `& ${argv.map(psq).join(' ')}`;
+  const cmdLine = [escapeCmdCommand(argv[0]), ...argv.slice(1).map((a) => escapeCmdArgument(a, true))].join(' ');
+  const detached = { cwd, detached: true, stdio: 'ignore' };
 
   switch (t) {
     case 'terminal':
-      return osa(`tell application "Terminal"\nactivate\ndo script ${asStr(line)}\nend tell`);
+      return [{ osa: `tell application "Terminal"\nactivate\ndo script ${asStr(line)}\nend tell` }];
     case 'iterm':
-      return osa(`tell application "iTerm"\nactivate\nset w to (create window with default profile)\ntell current session of w to write text ${asStr(line)}\nend tell`);
+      return [{ osa: `tell application "iTerm"\nactivate\nset w to (create window with default profile)\ntell current session of w to write text ${asStr(line)}\nend tell` }];
     case 'warp':
       // Warp has no scripting API; open a tab in the folder and type via System Events.
-      spawn('open', ['-a', 'Warp', cwd], { detached: true, stdio: 'ignore' }).unref();
-      return setTimeout(() => osa(`tell application "System Events" to keystroke ${asStr(cmd)} & return`), 1200);
+      return [{ command: 'open', args: ['-a', 'Warp', cwd] }, { delay: 1200 }, { osa: `tell application "System Events" to keystroke ${asStr(cmd)} & return` }];
+    case 'wt':
+      // `;` separates wt subcommands, so it can't appear unescaped in the command line.
+      return [{ command: 'wt.exe', args: ['-d', cwd, 'powershell.exe', '-NoExit', '-Command', ps.replace(/;/g, '\\;')], options: detached }];
+    case 'powershell':
+      // detached gives the child its own console window on Windows.
+      return [{ command: 'powershell.exe', args: ['-NoExit', '-Command', ps], options: detached }];
+    case 'cmd':
+      return [{ command: env.ComSpec || env.COMSPEC || 'cmd.exe', args: ['/d', '/s', '/k', `"${cmdLine}"`], options: { ...detached, windowsVerbatimArguments: true } }];
     case 'ghostty':
-      if (mac) return spawn('open', ['-na', 'Ghostty', '--args', `--working-directory=${cwd}`, '-e', ...argv], { detached: true, stdio: 'ignore' }).unref();
-      return spawn('ghostty', [`--working-directory=${cwd}`, '-e', ...argv], { detached: true, stdio: 'ignore' }).unref();
+      if (mac) return [{ command: 'open', args: ['-na', 'Ghostty', '--args', `--working-directory=${cwd}`, '-e', ...argv] }];
+      return [{ command: 'ghostty', args: [`--working-directory=${cwd}`, '-e', ...keepOpen] }];
     case 'kitty':
-      if (mac) return spawn('open', ['-na', 'kitty', '--args', '--directory', cwd, ...argv], { detached: true, stdio: 'ignore' }).unref();
-      return spawn('kitty', ['--directory', cwd, ...argv], { detached: true, stdio: 'ignore' }).unref();
+      if (mac) return [{ command: 'open', args: ['-na', 'kitty', '--args', '--directory', cwd, ...argv] }];
+      return [{ command: 'kitty', args: ['--directory', cwd, ...keepOpen] }];
     case 'wezterm':
-      return spawn(mac ? '/Applications/WezTerm.app/Contents/MacOS/wezterm' : 'wezterm', ['start', '--cwd', cwd, '--', ...argv], { detached: true, stdio: 'ignore' }).unref();
+      return [{ command: mac ? '/Applications/WezTerm.app/Contents/MacOS/wezterm' : 'wezterm', args: ['start', '--cwd', cwd, '--', ...(win ? ['powershell.exe', '-NoExit', '-Command', ps] : mac ? argv : keepOpen)], ...(win ? { options: detached } : {}) }];
+    case 'gnome-terminal':
+      return [{ command: 'gnome-terminal', args: [`--working-directory=${cwd}`, '--', ...keepOpen] }];
+    case 'konsole':
+      return [{ command: 'konsole', args: ['--workdir', cwd, '-e', ...keepOpen] }];
+    case 'xfce4-terminal':
+      return [{ command: 'xfce4-terminal', args: [`--working-directory=${cwd}`, '-x', ...keepOpen] }];
+    case 'alacritty':
+      return [{ command: 'alacritty', args: ['--working-directory', cwd, '-e', ...keepOpen] }];
     case 'custom': {
       if (!custom) throw new Error('Set a custom terminal command in settings, e.g.  alacritty --working-directory {cwd} -e {cmd}');
+      if (win) {
+        const full = custom.replaceAll('{cwd}', `"${cwd}"`).replaceAll('{cmd}', cmdLine).replaceAll('{line}', `cd /d "${cwd}" ^&^& ${cmdLine}`);
+        return [{ command: env.ComSpec || env.COMSPEC || 'cmd.exe', args: ['/d', '/s', '/c', `"${full}"`], options: { ...detached, windowsVerbatimArguments: true } }];
+      }
       const full = custom.replaceAll('{cwd}', shq(cwd)).replaceAll('{cmd}', cmd).replaceAll('{line}', shq(line));
-      return spawn('sh', ['-c', full], { detached: true, stdio: 'ignore' }).unref();
+      return [{ command: 'sh', args: ['-c', full], options: detached }];
+    }
+    default: // x-terminal-emulator (Debian/Ubuntu alternatives), xterm
+      return [{ command: t, args: ['-e', ...keepOpen], options: detached }];
+  }
+}
+
+export function openInTerminal(opts) {
+  const steps = terminalPlan(opts);
+  let wait = 0;
+  for (const step of steps) {
+    if (step.delay) {
+      wait += step.delay;
+      continue;
     }
-    default:
-      return spawn('x-terminal-emulator', ['-e', 'sh', '-c', `${line}; exec $SHELL`], { detached: true, stdio: 'ignore' }).unref();
+    const run = () => {
+      const [command, args] = step.osa ? ['osascript', ['-e', step.osa]] : [step.command, step.args];
+      const child = spawn(command, args, { cwd: opts.cwd, detached: true, stdio: 'ignore', ...step.options });
+      child.on('error', () => {}); // a missing terminal shouldn't crash the server
+      child.unref();
+    };
+    if (wait) setTimeout(run, wait);
+    else run();
   }
 }