wisp-agents 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-10-19
+
+### Added
+
+- **Switch harness or model in a follow-up.** The follow-up box has a harness button, a small logo next to the mode button. It opens the same harness · model · thinking picker as the launcher. Pick another model and the follow-up resumes the same conversation on it. Pick another harness, say Codex on a task Claude Code started, and Codex starts its own conversation in the same folder. wisp hands it the turns it hasn't seen: each request, the report it got back and the files that were edited. Long histories keep the newest turns, up to about 24k characters. Each harness keeps its own conversation, so switching back to Claude Code resumes its session and only tells it what happened while it was away. Each turn's badge shows the harness that ran it. A queued follow-up keeps its own pick, so the run already going is not affected. On a session that Auto routed, switching counts as a miss for Auto's pick. API: `POST /api/sessions/:id/reply {"text","agent","model","effort"}`; CLI: `wisp reply <id> "…" --agent codex --model …`; MCP: `wisp_reply` takes `agent`, `model` and `effort`.
+- **No harness yet? Install opencode in one click.** When wisp finds no coding-agent CLI on this computer, the launcher shows one line, *No coding agent here yet*, with an **Install opencode** button. opencode's free models need no account, so a new user can go from `npx wisp-agents` to a running task in a few seconds. wisp installs it with npm into its own folder (`~/.wisp/tools`), so it needs no sudo and leaves your shell profile alone, and finds it there. Pressing Enter with no harness shakes that line and keeps your prompt; before, the launch failed with *Auto found no installed harness*. Settings → Agents has the same **Install** button on the opencode row. API: `POST /api/agents/install {"id":"opencode"}`.
+- wisp also finds opencode in `~/.opencode/bin`, where its official install script puts it, when that folder isn't on PATH (common for the desktop app).
+
+- **wisp Cloud preview page** (`cloud.html`, linked from the site's nav and footer, and from a "Let it run while you sleep" section on the home page, between *Also in the box* and the install steps). It introduces a hosted wisp: managed remote machines, persistent queues that keep running while your laptop sleeps, and team dashboards. The local CLI stays free. You can try each part on the page: close the laptop and watch the cloud runs keep going, add machines, drag through one night of the queue, and filter a team dashboard by person. Signups for the waitlist go to PostHog.
+- **One-line install: `curl -fsSL https://mokh.xyz/install.sh | bash`.** The script (`docs/install.sh`, served by the site) checks for macOS or Linux, Node.js 20+ and npm, runs `npm install -g wisp-agents` (set `WISP_VERSION` to pin a release), and confirms that `wisp` is on your PATH. It prints a PATH fix when the npm bin folder isn't in it, and a link to npm's permissions guide when the global install is refused. The site and the README show it next to `npx wisp-agents`.
+- **Homebrew:** `brew install m0xoo/tap/wisp-agents`, from the new [M0xoo/homebrew-tap](https://github.com/M0xoo/homebrew-tap) repo (formula source in `packaging/homebrew/wisp-agents.rb`). It installs the CLI and browser mode; the formula removes the optional Electron package, which would otherwise download its ~300 MB binary into the Homebrew keg on first run.
+- **Install tabs on the site.** The hero command and step 2 of the install section both have tabs (npx, npm, curl, brew), like opencode's install block. Picking a tab in one switches the other, the copy button copies the command shown, and the note under it changes with the tab. Arrow keys, Home and End move between tabs. Type a task into the hero launcher and every tab hands back a command that installs wisp and starts that task (`brew install m0xoo/tap/wisp-agents && wisp "…"`). A command too long for the bar stays on one line and ends in …, and a long typed task no longer makes the page scroll sideways on phones.
+
+### Changed
+
+- **The website moved to [mokh.xyz](https://mokh.xyz/).** Canonical, Open Graph and structured-data URLs, `sitemap.xml`, `robots.txt`, `llms.txt` and the npm `homepage` now use the new domain. The old `m0xoo.github.io/wisp/` address redirects there.
+- **New website.** The site opens on a working copy of the launcher: it types three tasks and sends them off, and their rows move from Working to Asking (answer it right there) to Done. Type your own task and press ↵ to get the `npx wisp-agents "…"` command that runs it for real. Further down it shows the real app instead of animated mock-ups. A scroll-driven "morning with wisp" walks through five real screens with a ticking clock: three tasks launched, a mid-run question with its desktop notification, a report, Ship it, and the merged PR. A Transcript / wisp report switch shows the same run both ways. Also new: a Compare section, a take-over table with each harness's resume command, and a terminal that replays real `wisp` CLI output. Screenshots follow your light or dark theme, and on phones the story becomes a simple timeline.
+
+### Fixed
+
+- **Claude in Chrome now works in Claude Code tasks.** Claude Code only turns the Chrome extension on by itself in interactive sessions; wisp runs it with `-p`, so its `mcp__claude-in-chrome__*` tools were missing. wisp now passes `--chrome` when you have Claude in Chrome enabled by default (`/chrome` in Claude Code, `claudeInChromeDefaultEnabled` in `~/.claude.json`). Set `WISP_CLAUDE_CHROME=1` or `0` to force it on or off.
+- An opencode task on a rate-limited model (often a free one) no longer sits at "Starting up" forever. opencode retries without printing anything, so wisp now reads its error log. If the rate limit hasn't cleared after 60s, wisp stops the task and says what to do: try again later, pick another model, or run `opencode auth login`.
+- wisp no longer crashes when the `claude` CLI quits before reading its prompt (a bad flag, an auth error, a crash on start). The task now ends with Claude's error message. Before, the unread prompt raised an unhandled `EPIPE` that took the whole server down.
+- `config.json` (projects, recipes, triggers, machines, settings) is now written atomically. Before, a crash or power loss mid-write could leave a cut-off file, which loaded as the defaults and was then saved over. Auto's learned state and the learned preferences are written the same way.
+- Idle API connections stay open longer than clients keep them, so a request sent on a connection the server was just closing no longer fails with `ECONNRESET`.
+- Refused requests (bad input, not found) no longer print a stack trace in the terminal running wisp.
+- **Run** / **Re-run** on a terminal, tests or actions block now shows the new output. Before, the command ran but the block kept its old output and an error toast said it failed.
+- **Escape** closes the menu or popover that is open, wherever focus is, and nothing else. Before, it could collapse the card behind a context menu and leave the menu open.
+- Settings switches, project edits, and deleting a recipe, trigger or subagent preset now show the server's error when it refuses the change, and leave things as they were. Before, nothing happened on screen; deleting a preset even said "Deleted".
+- Expanding cards no longer leaves a hidden file picker behind each time, and the launcher no longer adds another listener on every redraw.
+- `openapi.json` now documents subagent presets (`/teams`) and `GET /uploads/{id}`.
+
+### Internal
+
+- The server is split by area: `server/index.js` only wires things together. Routes live in `server/routes/` behind a small route table (`server/http/`), and shared logic lives in `server/services/` (launch, Ship it, Auto, uploads, phone, feedback). Helpers that were copied across files now come from `server/util.js`, and git always runs through one helper that honours `WISP_GIT_BIN`. Adapters are checked against their contract at startup, and `claude.js` uses the same spawn plumbing as the other harnesses. `test/routes.test.js` keeps the route table and `openapi.json` in sync. The HTTP API, CLI, SDK exports and the `~/.wisp` files are unchanged.
+- The web UI's 5,300-line `app.js` is now about 40 modules under `web/js/` (`core/`, `ui/`, `features/`), and `app.css` is 15 stylesheets that, concatenated in link order, are byte-for-byte the old file. A small event bus replaces the hooks that live updates used to reach open dialogs through, and one popover helper replaces about ten copies of open, outside-click and close code. No build step was added.
+
 ## [0.15.0] - 2026-10-18
 
 ### Changed
@@ -262,7 +299,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 - Session queue with follow-ups, answers to agent questions, terminal takeover and mark-as-done.
 - Older turns are folded, with a floating collapse-all button and back-to-top.
 
-[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.15.0...HEAD
+[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/M0xoo/wisp/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/M0xoo/wisp/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/M0xoo/wisp/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/M0xoo/wisp/compare/v0.12.0...v0.13.0

package/README.md

@@ -54,7 +54,7 @@ From there you can **follow up**, **answer its questions**, **take it over** in
 | 🤝 **Subagents** | Give the lead agent a team on other harnesses (e.g. Claude Code hands tests to Codex ×3). It delegates through a `delegate` tool; their edits land in its worktree. See [Subagents](#subagents). |
 | ⏪ **Checkpoints & rollback** | Every turn is snapshotted first. Restore to before any turn, revert a single file, or re-run a command block from the presentation. |
 | ⚖️ **Compare** | Run one task on two harnesses side by side, and keep the better run. |
-| 🧾 **Recipes & triggers** | Saved prompts with `{params}` (`wisp run release 0.15.0`), run by hand, on a schedule, when CI fails, or when an issue is labelled. |
+| 🧾 **Recipes & triggers** | Saved prompts with `{params}` (`wisp run release 0.16.0`), run by hand, on a schedule, when CI fails, or when an issue is labelled. |
 | 📊 **Usage** | Spend, success rate and questions per project and per harness · model. |
 | 📱 **Phone** | Questions and finished tasks on ntfy or Telegram; answer from there, or start a task with `/new`. |
 | 🔐 **Permission modes** | Choose **Plan** (read-only), **Edits** (file edits auto-accepted), or **Full auto** for each launch. `Shift+Tab` in the prompt cycles modes. |
@@ -73,13 +73,18 @@ npx wisp-agents --browser                # or use it in the browser → http://l
 
 The first run downloads Electron for the desktop app; if that isn't possible, wisp opens in the browser instead.
 
-Or install it globally to get the `wisp` command everywhere:
+Or install it globally to get the `wisp` command everywhere. Pick one:
 
 ```sh
-npm install -g wisp-agents
+curl -fsSL https://mokh.xyz/install.sh | bash   # macOS or Linux: checks Node 20+, then npm install -g wisp-agents
+npm install -g wisp-agents                      # any OS with Node 20+
+brew install m0xoo/tap/wisp-agents             # Homebrew: CLI and browser mode, no Electron desktop app
+
 wisp "fix the flaky auth test"
 ```
 
+The Homebrew formula lives in [M0xoo/homebrew-tap](https://github.com/M0xoo/homebrew-tap). `install.sh` honors `WISP_VERSION` to pin a release (`curl -fsSL https://mokh.xyz/install.sh | WISP_VERSION=0.16.0 bash`).
+
 From source:
 
 ```sh
@@ -122,11 +127,11 @@ wisp "add a test" --wait          # block until it finishes, print the presentat
 wisp ls --state running,waiting   # list sessions
 wisp show <id>                    # state + latest presentation
 wisp wait <id>                    # until it finishes or asks you something
-wisp reply <id> "also do X"       # follow up (answers a pending question; --mode to switch)
+wisp reply <id> "also do X"       # follow up (answers a pending question; --mode, --agent, --model to switch)
 wisp stop <id>
 wisp ship <id> [--draft]          # commit, push and open a PR for a worktree task
 wisp merge <id>                   # squash-merge its PR, fast-forward your local main
-wisp run release 0.15.0            # run a recipe; values fill its {params} (or version=0.15.0)
+wisp run release 0.16.0            # run a recipe; values fill its {params} (or version=0.16.0)
 wisp recipes                      # list recipes
 wisp usage [--days 7]             # spend and outcomes
 wisp mcp                          # MCP server for other agents and editors
@@ -216,13 +221,18 @@ wisp/
 ├── bin/
 │   └── wisp.js            # CLI: starts the server or talks to the running one
 ├── server/
-│   ├── index.js           # HTTP API, SSE stream, static UI, uploads
-│   ├── openapi.js         # OpenAPI document for the public API
+│   ├── index.js           # startServer: wires the pieces below together
+│   ├── http/              # route table, JSON responses + SSE, static UI
+│   ├── routes/            # one file per API area: sessions, ship, settings, automations, machines, …
+│   ├── services/          # shared by routes and background jobs: launch, ship, auto, uploads, phone, …
+│   ├── util.js            # small shared helpers (errors, ids, quoting, atomic JSON writes)
+│   ├── openapi.js         # OpenAPI document for the public API (test/routes.test.js keeps it in sync)
 │   ├── client.js          # JS SDK (wisp-agents/client), used by the CLI and MCP server
 │   ├── mcp-wisp.js        # `wisp mcp`: wisp as tools for other agents
 │   ├── render.js          # presentation → markdown
 │   ├── runner.js          # session lifecycle, follow-ups, event normalization
-│   ├── checkpoint.js      # per-turn git checkpoints, file revert, rollback, action exec
+│   ├── checkpoint.js      # per-turn git checkpoints, file revert, rollback
+│   ├── proc.js            # cross-platform spawn, and running a block's command
 │   ├── protocol.js        # system prompt + ```wisp block parser (markdown fallback)
 │   ├── mcp-ask.js         # ask_user MCP server
 │   ├── store.js           # JSON-file persistence in ~/.wisp
@@ -231,6 +241,7 @@ wisp/
 │   ├── triggers.js        # cron schedules and GitHub watchers
 │   ├── remote.js          # phone: ntfy and Telegram, out and back
 │   ├── machines.js        # other computers: SSH, a tunnel to wisp there, relayed sessions
+│   ├── machines/          # known hosts (ssh config, Tailscale) and the bootstrap script
 │   ├── usage.js           # spend and outcomes
 │   ├── terminal.js        # "take over" in your terminal
 │   ├── welcome.js         # the gallery session
@@ -244,10 +255,15 @@ wisp/
 │       ├── antigravity.js # Antigravity CLI adapter
 │       └── grok.js        # Grok Build adapter
 ├── skills/wisp/SKILL.md   # agent skill: how other agents use wisp
-├── web/                   # vanilla JS UI, no build step
+├── web/                   # vanilla JS UI, native ES modules, no build step
 │   ├── index.html
-│   ├── css/app.css
-│   └── js/{app,blocks,diff,md}.js
+│   ├── css/               # one stylesheet per area (tokens, base, feed, blocks, modals, …), linked in order
+│   └── js/
+│       ├── app.js         # boot, top bar, routing
+│       ├── core/          # state, api, event bus, DOM helpers
+│       ├── ui/            # toasts, dialogs, popovers, keyboard hints
+│       ├── features/      # feed, turns, composer, launcher, settings, ship, machines, …
+│       └── {blocks,md,diff,fuzzy,palette}.js   # presentation blocks and their helpers
 └── electron/              # desktop shell
     ├── main.js
     └── preload.cjs
@@ -318,7 +334,7 @@ Before each turn, wisp snapshots the git working tree (pinned at `refs/wisp/chec
 Prepare release {version}: update CHANGELOG, README and docs/, bump package.json, tag v{version}.
 ```
 
-Make one from ⌘K → *Recipes*, or *Save as recipe…* on any card. A recipe may pin a project, harness, model and mode. Run it from ⌘K (*Run: Release*), from the Recipes view, or from a terminal: `wisp run release 0.15.0` fills the fields in order, `wisp run release version=0.15.0` by name.
+Make one from ⌘K → *Recipes*, or *Save as recipe…* on any card. A recipe may pin a project, harness, model and mode. Run it from ⌘K (*Run: Release*), from the Recipes view, or from a terminal: `wisp run release 0.16.0` fills the fields in order, `wisp run release version=0.16.0` by name.
 
 **Triggers** launch sessions on their own while wisp is open (⌘K → *Triggers*):
 

package/bin/wisp.js

@@ -24,7 +24,8 @@ const HELP = `usage:
   wisp ls                       list sessions        (--state running,waiting  --limit N)
   wisp show <id>                state + latest presentation as markdown
   wisp wait <id>                block until it finishes or asks you something
-  wisp reply <id> "text"        follow up (answers a pending question)   (--queue  --mode plan|edits|auto)
+  wisp reply <id> "text"        follow up (answers a pending question)   (--queue  --mode plan|edits|auto
+                                --agent ID  --model ID  --effort LEVEL: switch harness / model from here on)
   wisp stop <id>                stop a run
   wisp ship <id>                commit, push and open a PR for a worktree session   (--draft)
   wisp merge <id>               squash-merge its PR and sync your local base branch
@@ -132,7 +133,7 @@ async function scripted(cmd, args) {
     }
     case 'reply': {
       const id = need(args[0], 'session id');
-      const r = await wisp.reply(id, need(args.slice(1).join(' ').trim(), 'text'), { queue: flags.queue, mode: flags.mode || undefined });
+      const r = await wisp.reply(id, need(args.slice(1).join(' ').trim(), 'text'), { queue: flags.queue, mode: flags.mode || undefined, agent: flags.agent || undefined, model: flags.model ?? undefined, effort: flags.effort ?? undefined });
       if (!flags.wait) return out(r, r.answered ? '  ✓ answered' : r.interrupted ? '  ✓ interrupted; resuming with your message' : r.queued ? '  ✓ queued' : '  ✓ sent');
       return show(id, await wisp.wait(id));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wisp-agents",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Launch coding agents, skip the transcript, read the presentation.",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "app": "node bin/wisp.js",
     "dev": "WISP_DEV=1 node bin/wisp.js",
     "dev:web": "node --watch-path=server bin/wisp.js --no-open",
-    "test": "node --test test/proc.test.js test/terminal.test.js test/adapters.test.js test/e2e.test.js test/fuzzy.test.js test/integrations.test.js test/update.test.js test/learn.test.js test/ship.test.js test/subagents.test.js test/machines.test.js test/feedback.test.js test/router.test.js",
+    "test": "node --test test/proc.test.js test/terminal.test.js test/adapters.test.js test/e2e.test.js test/fuzzy.test.js test/integrations.test.js test/update.test.js test/learn.test.js test/ship.test.js test/subagents.test.js test/machines.test.js test/feedback.test.js test/router.test.js test/routes.test.js test/adapters-exit.test.js test/web-pure.test.js test/install.test.js test/install-script.test.js",
     "test:real": "node test/real-clis.mjs",
     "prepublishOnly": "node --check bin/wisp.js && node --check bin/mac-app.js && node -e \"import('./server/index.js').then(() => import('./server/mcp-wisp.js'))\" && node --check electron/main.js"
   },
@@ -44,7 +44,7 @@
     "type": "git",
     "url": "git+https://github.com/M0xoo/wisp.git"
   },
-  "homepage": "https://github.com/M0xoo/wisp#readme",
+  "homepage": "https://mokh.xyz/",
   "bugs": {
     "url": "https://github.com/M0xoo/wisp/issues"
   },

package/server/adapters/antigravity.js

@@ -7,7 +7,7 @@
 // first message.
 
 import path from 'node:path';
-import { attachmentNote, clip, detectVersion, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+import { attachmentNote, clip, detectVersion, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
 
 const BIN = process.env.WISP_ANTIGRAVITY_BIN || 'agy';
 
@@ -125,7 +125,7 @@ export default {
       },
       onClose({ code, signal, stderr, stopped }) {
         if (sawResult) return;
-        onEvent({ type: 'result', isError: true, stopped, text: stderr || `agy exited with ${signal || `code ${code}`}` });
+        onEvent({ type: 'result', isError: true, stopped, text: stderr || exitText('agy', code, signal) });
       },
     });
   },

package/server/adapters/claude.js

@@ -1,13 +1,25 @@
 // Claude Code adapter — drives `claude -p --output-format stream-json`.
 
-import readline from 'node:readline';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { spawn, killTree } from '../proc.js';
-import { ASK_TIMEOUT_MS, MAX_SNAPSHOT, attachmentNote, clip, detectVersion, flatten, rel } from './common.js';
+import { ASK_TIMEOUT_MS, MAX_SNAPSHOT, attachmentNote, clip, detectVersion, exitText, flatten, rel, spawnJsonl } from './common.js';
 
 const BIN = process.env.WISP_CLAUDE_BIN || 'claude';
 
+// Claude in Chrome turns itself on only in interactive sessions; `-p` needs --chrome. Follow the
+// user's own "enabled by default" choice (/chrome in Claude Code) so a wisp run gets the same tools.
+// WISP_CLAUDE_CHROME=1/0 overrides it.
+export function chromeEnabled(env = process.env) {
+  if (env.WISP_CLAUDE_CHROME) return env.WISP_CLAUDE_CHROME !== '0';
+  const file = env.CLAUDE_CONFIG_DIR ? path.join(env.CLAUDE_CONFIG_DIR, '.claude.json') : path.join(os.homedir(), '.claude.json');
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')).claudeInChromeDefaultEnabled === true;
+  } catch {
+    return false;
+  }
+}
+
 const PERMISSION_MODES = {
   plan: 'plan',
   edits: 'acceptEdits',
@@ -44,6 +56,7 @@ export default {
     ];
     if (model) args.push('--model', model);
     if (effort) args.push('--effort', effort);
+    if (chromeEnabled()) args.push('--chrome');
     if (resumeId) args.push('--resume', resumeId);
     if (Object.keys(mcpServers).length) {
       args.push('--mcp-config', JSON.stringify({ mcpServers }));
@@ -61,12 +74,8 @@ export default {
     delete env.CLAUDE_CODE_ENTRYPOINT;
     env.MCP_TOOL_TIMEOUT ??= String(ASK_TIMEOUT_MS);
 
-    const child = spawn(BIN, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
-    child.stdin.end(prompt);
-
     let sawResult = false;
     let early = null; // an empty result that came before our prompt was answered (see below)
-    let stderr = '';
     const pendingTools = new Map(); // tool_use_id -> name, to flag failed tool results
     // Background tasks (run_in_background shells, background subagents) still running. While any
     // are, the CLI stays up after its result and starts another turn when they finish.
@@ -77,18 +86,7 @@ export default {
       if ([...next.keys()].join(' ') !== was) onEvent({ type: 'background', tasks: [...next.values()] });
     };
 
-    child.stderr.on('data', (d) => {
-      stderr = (stderr + d).slice(-8000);
-    });
-
-    readline.createInterface({ input: child.stdout }).on('line', (line) => {
-      if (!line.trim()) return;
-      let msg;
-      try {
-        msg = JSON.parse(line);
-      } catch {
-        return;
-      }
+    const onJson = (msg) => {
       if (msg.session_id) onEvent({ type: 'session', id: msg.session_id });
 
       if (msg.type === 'assistant') {
@@ -136,39 +134,22 @@ export default {
         sawResult = true;
         onEvent({ ...ev, background: background.size }); // > 0: another turn and result follow when they finish
       }
-    });
-
-    let stopping = false;
-    const done = new Promise((resolve) => {
-      child.on('error', (err) => {
-        onEvent({ type: 'result', isError: true, text: `Could not start \`${BIN}\`: ${err.message}` });
-        sawResult = true;
-        resolve();
-      });
-      child.on('close', (code, signal) => {
-        if (!sawResult && early && !stopping) {
-          sawResult = true;
-          onEvent(early);
-        }
-        if (!sawResult) {
-          onEvent({
-            type: 'result',
-            isError: true,
-            stopped: stopping || signal === 'SIGTERM' || signal === 'SIGINT',
-            text: stderr.trim() || `claude exited with ${signal || `code ${code}`}`,
-          });
-        }
-        resolve();
-      });
-    });
+    };
 
-    return {
-      done,
-      stop() {
-        stopping = true;
-        killTree(child);
+    return spawnJsonl({
+      bin: BIN,
+      args,
+      cwd,
+      env,
+      input: prompt,
+      onEvent,
+      onJson,
+      onClose: ({ code, signal, stderr, stopped, stopRequested }) => {
+        if (sawResult) return;
+        if (early && !stopRequested) return onEvent(early);
+        onEvent({ type: 'result', isError: true, stopped, text: stderr || exitText('claude', code, signal) });
       },
-    };
+    });
   },
 };
 

package/server/adapters/codex.js

@@ -1,7 +1,7 @@
 // Codex CLI adapter — drives `codex exec --json` (JSONL thread/turn/item events).
 
 import path from 'node:path';
-import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, rel, spawnJsonl, withProtocol } from './common.js';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, rel, spawnJsonl, withProtocol } from './common.js';
 
 const BIN = process.env.WISP_CODEX_BIN || 'codex';
 const IMAGE = /^image\/(png|jpe?g|gif|webp)$/;
@@ -157,7 +157,7 @@ export default {
           type: 'result',
           isError: !ok,
           stopped,
-          text: ok ? lastMessage : failure || lastError || stderr || `codex exited with ${signal || `code ${code}`}`,
+          text: ok ? lastMessage : failure || lastError || stderr || exitText('codex', code, signal),
           stats: {
             durationMs: Date.now() - started,
             inputTokens: usage?.input_tokens,

package/server/adapters/common.js

@@ -1,12 +1,13 @@
 // Helpers shared by the adapters: process plumbing, labels, and diff capture.
 
-import { execFileSync } from 'node:child_process';
 import readline from 'node:readline';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, execFile, killTree } from '../proc.js';
+import { gitSync } from '../git.js';
+import { MAX_SNAPSHOT, rel } from '../paths.js';
+import { clip } from '../util.js';
 
-export const MAX_SNAPSHOT = 256 * 1024;
 export const ASK_TIMEOUT_MS = 7 * 24 * 3600 * 1000; // ask_user may wait for the human a long time
 
 export function detectVersion(bin, args = ['--version']) {
@@ -25,8 +26,10 @@ export function quietOutput(bin, args, timeout = 15_000) {
 }
 
 // Spawn a CLI that prints one JSON object per line. onJson gets each parsed line;
-// onClose({ code, signal, stderr }) must emit the final `result` if the stream didn't.
-export function spawnJsonl({ bin, args, cwd, env, input, onJson, onClose, onEvent }) {
+// onClose({ code, signal, stderr, stopped, stopRequested }) must emit the final `result` if the
+// stream didn't. stopped: killed by stop() or a signal; stopRequested: by stop() only.
+// onStderr (optional) sees stderr as it comes, for CLIs that only report trouble there.
+export function spawnJsonl({ bin, args, cwd, env, input, onJson, onClose, onEvent, onStderr }) {
   // Some CLIs (opencode) take their working directory from $PWD rather than the real cwd.
   const child = spawn(bin, args, { cwd, env: { ...env, PWD: cwd }, stdio: ['pipe', 'pipe', 'pipe'] });
   child.stdin.on('error', () => {}); // the CLI may exit before reading stdin
@@ -35,6 +38,7 @@ export function spawnJsonl({ bin, args, cwd, env, input, onJson, onClose, onEven
   let stderr = '';
   child.stderr.on('data', (d) => {
     stderr = (stderr + d).slice(-8000);
+    onStderr?.(String(d));
   });
   readline.createInterface({ input: child.stdout }).on('line', (line) => {
     if (!line.trim()) return;
@@ -56,7 +60,7 @@ export function spawnJsonl({ bin, args, cwd, env, input, onJson, onClose, onEven
       resolve();
     });
     child.on('close', (code, signal) => {
-      if (!failed) onClose({ code, signal, stderr: stderr.trim(), stopped: stopping || signal === 'SIGTERM' || signal === 'SIGINT' });
+      if (!failed) onClose({ code, signal, stderr: stderr.trim(), stopped: stopping || signal === 'SIGTERM' || signal === 'SIGINT', stopRequested: stopping });
       resolve();
     });
   });
@@ -70,6 +74,9 @@ export function spawnJsonl({ bin, args, cwd, env, input, onJson, onClose, onEven
   };
 }
 
+// The result text for a CLI that ended without saying why.
+export const exitText = (bin, code, signal) => `${bin} exited with ${signal || `code ${code}`}`;
+
 export function attachmentNote(files, how = 'Read images and PDFs with your file-reading tool') {
   if (!files.length) return '';
   const lines = files.map((f) => `- ${f.path}  (${f.mime}, ${Math.max(1, Math.round(f.size / 1024))} KB)`);
@@ -82,34 +89,7 @@ export function withProtocol(prompt, systemPrompt, resumeId) {
   return resumeId ? prompt : `${systemPrompt.trim()}\n\n---\n\n# Task\n\n${prompt}`;
 }
 
-const realDirs = new Map();
-function realDir(dir) {
-  if (!realDirs.has(dir)) {
-    try {
-      realDirs.set(dir, fs.realpathSync(dir));
-    } catch {
-      realDirs.set(dir, dir);
-    }
-  }
-  return realDirs.get(dir);
-}
-
-// Path relative to cwd, or the path as given if it lies outside. Harnesses may report paths
-// through the resolved cwd (/private/tmp vs /tmp on macOS), so both spellings count.
-export function rel(file, cwd) {
-  if (!file) return '';
-  const abs = path.resolve(cwd, file);
-  for (const base of [cwd, realDir(cwd)]) {
-    const r = path.relative(base, abs);
-    if (r && !r.startsWith('..') && !path.isAbsolute(r)) return r;
-  }
-  return file;
-}
-
-export function clip(s, n = 80) {
-  s = String(s ?? '').replace(/\s+/g, ' ').trim();
-  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
-}
+export { clip, MAX_SNAPSHOT, rel };
 
 export function flatten(content) {
   if (typeof content === 'string') return content;
@@ -136,7 +116,7 @@ export function fileTracker(cwd) {
   const known = new Map(); // rel path -> content after our last change() (null = missing)
   const announced = new Map(); // rel path -> content when the harness announced an edit
   let base;
-  const git = (args, opts = {}) => execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, ...opts });
+  const git = (args, opts) => gitSync(cwd, args, opts);
   try {
     // Pinned before the agent starts writing.
     base = git(['stash', 'create']).toString().trim() || git(['rev-parse', '--verify', 'HEAD']).toString().trim();

package/server/adapters/cursor.js

@@ -3,7 +3,7 @@
 // cursor-agent has no flag to inject an MCP server (it only reads .cursor/mcp.json), so wisp's
 // ask_user tool isn't available here; the protocol tells the agent to end with a question block.
 
-import { attachmentNote, clip, detectVersion, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+import { attachmentNote, clip, detectVersion, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
 
 const BIN = process.env.WISP_CURSOR_BIN || 'cursor-agent';
 
@@ -91,7 +91,7 @@ export default {
       },
       onClose({ code, signal, stderr, stopped }) {
         if (sawResult) return;
-        onEvent({ type: 'result', isError: true, stopped, text: stderr || `cursor-agent exited with ${signal || `code ${code}`}` });
+        onEvent({ type: 'result', isError: true, stopped, text: stderr || exitText('cursor-agent', code, signal) });
       },
     });
   },

package/server/adapters/grok.js

@@ -9,7 +9,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, flatten, quietOutput, rel, spawnJsonl } from './common.js';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, flatten, quietOutput, rel, spawnJsonl } from './common.js';
 
 const BIN = process.env.WISP_GROK_BIN || 'grok';
 
@@ -137,7 +137,7 @@ export default {
       },
       onClose({ code, signal, stderr, stopped }) {
         if (sawResult) return;
-        onEvent({ type: 'result', isError: true, stopped, text: error || stderr || `grok exited with ${signal || `code ${code}`}` });
+        onEvent({ type: 'result', isError: true, stopped, text: error || stderr || exitText('grok', code, signal) });
       },
     });
     handle.done.finally(() => fs.rmSync(tmp, { recursive: true, force: true }));

package/server/adapters/index.js

@@ -31,7 +31,22 @@ import cursor from './cursor.js';
 import antigravity from './antigravity.js';
 import grok from './grok.js';
 
-export const adapters = Object.fromEntries([claude, codex, opencode, cursor, antigravity, grok].map((a) => [a.id, a]));
+// The shape above, checked when wisp starts: a missing piece fails loudly here, not mid-run.
+function checked(a) {
+  const missing = [
+    typeof a.id !== 'string' && 'id',
+    typeof a.name !== 'string' && 'name',
+    !Array.isArray(a.models) && 'models',
+    a.askTool !== null && a.askTool !== undefined && typeof a.askTool !== 'string' && 'askTool',
+    typeof a.detect !== 'function' && 'detect()',
+    typeof a.run !== 'function' && 'run()',
+    a.resumeCommand !== undefined && typeof a.resumeCommand !== 'function' && 'resumeCommand()',
+  ].filter(Boolean);
+  if (missing.length) throw new Error(`adapter ${a.id || '?'}: missing or wrong ${missing.join(', ')}`);
+  return a;
+}
+
+export const adapters = Object.fromEntries([claude, codex, opencode, cursor, antigravity, grok].map((a) => [a.id, checked(a)]));
 
 const detected = new Map();
 

package/server/adapters/opencode.js

@@ -1,8 +1,22 @@
 // opencode adapter — drives `opencode run --format json` (one JSON event per line).
 
-import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { toolsDir } from '../util.js';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
 
-const BIN = process.env.WISP_OPENCODE_BIN || 'opencode';
+const exe = process.platform === 'win32' ? 'opencode.cmd' : 'opencode';
+// Where opencode lives when it isn't on PATH: the copy wisp installs (POST /agents/install),
+// and the official install script's folder (it edits your shell profile, which an app started
+// from the Dock or a service never reads).
+export const fallbackBins = () => [path.join(toolsDir(), 'node_modules', '.bin', exe), path.join(os.homedir(), '.opencode', 'bin', process.platform === 'win32' ? 'opencode.exe' : 'opencode')];
+let BIN = process.env.WISP_OPENCODE_BIN || 'opencode';
+// Rate-limited (the free models, mostly), `opencode run` keeps retrying and prints nothing, so
+// the task would sit at "Starting up" for good. Its error log says so: give it this long to get
+// through, then stop and tell the user what to do.
+const rateLimitGrace = () => Number(process.env.WISP_RATE_LIMIT_GRACE_MS) || 60_000;
+const RATE_LIMITED = /Rate limit exceeded|Too Many Requests|status(?:Code)?[=: ]+429\b/i;
 
 export default {
   id: 'opencode',
@@ -16,7 +30,16 @@ export default {
   },
 
   async detect() {
-    const found = await detectVersion(BIN);
+    let found = await detectVersion(BIN);
+    if (!found.available && !process.env.WISP_OPENCODE_BIN) {
+      for (const bin of fallbackBins().filter((b) => fs.existsSync(b))) {
+        const there = await detectVersion(bin);
+        if (!there.available) continue;
+        BIN = bin;
+        found = there;
+        break;
+      }
+    }
     if (!found.available) return found;
     // `opencode models --verbose` prints each provider/model id followed by its JSON metadata;
     // the metadata's `variants` are the reasoning efforts `run --variant` accepts for that model.
@@ -40,7 +63,8 @@ export default {
 
   run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, mcpServers = {}, delegating = false, onEvent }) {
     // The prompt goes on stdin; `run` appends piped stdin to the (empty) message.
-    const args = ['run', '--format', 'json'];
+    // Errors to stderr: the only place a rate limit shows up (see RATE_LIMITED).
+    const args = ['run', '--format', 'json', '--print-logs', '--log-level', 'ERROR'];
     if (mode === 'plan') args.push('--agent', 'plan');
     if (mode === 'auto') args.push('--auto');
     if (model) args.push('--model', model);
@@ -75,14 +99,22 @@ export default {
     const tokens = { input: 0, output: 0 };
     let cost = 0;
 
-    return spawnJsonl({
+    let limitTimer = null;
+    let limited = false;
+    const proc = spawnJsonl({
       bin: BIN,
       args,
       cwd,
       env,
       input,
       onEvent,
+      onStderr(chunk) {
+        if (limitTimer || limited || !RATE_LIMITED.test(chunk)) return;
+        limitTimer = setTimeout(() => ((limited = true), proc.stop()), rateLimitGrace());
+      },
       onJson(msg) {
+        // Anything coming through means a retry got an answer.
+        if (limitTimer && msg.type !== 'error') (clearTimeout(limitTimer), (limitTimer = null));
         if (msg.sessionID && msg.sessionID !== session) onEvent({ type: 'session', id: (session = msg.sessionID) });
         const part = msg.part || {};
         switch (msg.type) {
@@ -118,19 +150,28 @@ export default {
         }
       },
       onClose({ code, signal, stderr, stopped }) {
+        clearTimeout(limitTimer);
+        if (limited) {
+          const which = model ? `\`${model}\`` : 'opencode’s default model';
+          return onEvent({ type: 'result', isError: true, text: `${which} is rate-limited right now: opencode kept retrying for ${Math.round(rateLimitGrace() / 1000)}s without an answer. Try again in a few minutes, pick another model, or connect your own provider with \`opencode auth login\`.`, stats: { durationMs: Date.now() - started } });
+        }
         const ok = code === 0 && !error;
         onEvent({
           type: 'result',
           isError: !ok,
           stopped,
-          text: ok ? text.join('\n') : error || stderr || `opencode exited with ${signal || `code ${code}`}`,
+          text: ok ? text.join('\n') : error || lastLoggedError(stderr) || exitText('opencode', code, signal),
           stats: { durationMs: Date.now() - started, costUsd: cost || undefined, inputTokens: tokens.input, outputTokens: tokens.output },
         });
       },
     });
+    return proc;
   },
 };
 
+// stderr with --print-logs: the last logged error's message, else stderr as it is.
+const lastLoggedError = (stderr) => [...stderr.matchAll(/error\.error="((?:[^"\\]|\\.)*)"/g)].at(-1)?.[1] || stderr;
+
 function safeJson(s) {
   try {
     return JSON.parse(s) || {};