wisp-agents 0.23.0 → 0.24.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.24.1] - 2026-10-20
+
+### Fixed
+
+- **Update now updates, however you installed wisp.** **Update to X** installs the new version and restarts wisp for every install route: `npx`, `npm install -g`, the `install.sh` script, and now Homebrew. On a Homebrew install it used to run `npm install -g` and then restart the old keg. Now it runs `brew upgrade m0xoo/tap/wisp-agents` and restarts from the new keg. If the install leaves wisp on the same version (the tap doesn't have the release yet, or npm installed into a different folder), the button says so instead of restarting into the old version and then reporting that wisp didn't come back. A git clone of the repo no longer shows the button or tells you to run `git pull`. `GET /update` no longer returns `auto`, and the method can now be `brew`.
+
+## [0.24.0] - 2026-10-20
+
+### Added
+
+- **How to get a missing harness, where you look for it.** Settings → Agents now shows, for each harness wisp didn't find, what to do on that computer's OS: a one-line tip (e.g. that the ChatGPT app is enough for Codex on macOS and Linux but not on Windows, or that the Antigravity and Cursor editors don't include their CLIs), the install command to copy with one click, and a **Docs** link. In the harness picker, hovering a greyed-out harness shows the same tip, and clicking it (or arrowing onto it) shows the steps in place of its models, with **Re-check** (and **Install** for opencode). It still can't be picked. API: unavailable harnesses in `GET /agents` carry `setup: { tip, command?, url }`; adapters provide it through an optional `setup(platform)`.
+- **Codex and Claude Code from their desktop apps, no CLI install needed.** If `codex` isn't on PATH, wisp uses the Codex CLI the ChatGPT desktop app ships: `ChatGPT.app/Contents/Resources/codex-cli/bin/codex` on macOS (or `Codex.app/Contents/Resources/codex` from the older Codex app), in `/Applications` or `~/Applications`, and `/usr/lib/chatgpt/resources/codex` from the Linux `.deb`. It shares `~/.codex`, so the app's sign-in carries over. The Windows app is a Store package whose files can't be run from outside it, so on Windows Codex still needs the CLI. If `claude` isn't on PATH, wisp uses the newest copy the Claude desktop app downloads for its Code tab, on macOS and Windows (`<app data>/Claude/claude-code/<version>/…`, including the Store installs' folders). That copy is signed in only while the app runs it, so run it once and `/login`. Both adapters also look in the CLIs' own install folders (`~/.codex/packages/standalone/current/bin`, `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin`, `~/.local/bin`, `~/.claude/local`), which an app started from the Dock or Start menu may not have on PATH. A `WISP_CODEX_BIN` or `WISP_CLAUDE_BIN` override still wins.
+
+### Changed
+
+- **The website shows moving a task to another computer or agent.** A new landing-page section, *Start on your laptop. Finish on the dev box.*, has a working copy of a task card's follow-up box: pick a computer under **Runs on** and an agent, press ↵, and it packs the work, hands the history over and carries on there, the way the app does. It plays once by itself when it comes into view; click anything to try it. A new guide, [Move a task to another machine or agent, mid-way](https://trywisp.dev/guides/move-a-task-to-another-machine-or-agent.html), covers doing it by hand with `git bundle`, what wisp moves, what each agent is told when you switch harness, model or computer, and the CLI and API. The landing FAQ answers it too, and *Machines* is in the landing nav. In *Also in the box*, the Machines tile became *Several folders*, since machines now have their own section. The landing nav no longer wraps onto two lines between 960 and 1200px wide; it drops Control and CLI there.
+
+### Fixed
+
+- **The site builds the same on Windows.** With a CRLF checkout, the integrations page kept its markdown title as a second `<h1>` and the changelog page repeated each release heading, because `scripts/site.mjs` matched `\n` line ends only. It now normalizes line ends when reading `docs/integrations.md` and `CHANGELOG.md`, and the site test passes on Windows CI.
+- **Done and Archived count every task and load more as you scroll.** Their headings always said 60 once you had more than that, and the older tasks never showed. The headings now count them all, the lists show 60 cards at first and add the next 60 as you scroll near the end (or click **Show 60 more · N left**), and opening an older task from a notification or ⌘K shows the cards down to it.
+
 ## [0.23.0] - 2026-10-20
 
 ### Changed
@@ -420,7 +442,9 @@ 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.23.0...HEAD
+[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.24.1...HEAD
+[0.24.1]: https://github.com/M0xoo/wisp/compare/v0.24.0...v0.24.1
+[0.24.0]: https://github.com/M0xoo/wisp/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/M0xoo/wisp/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/M0xoo/wisp/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/M0xoo/wisp/compare/v0.20.0...v0.21.0

package/README.md

@@ -56,7 +56,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.23.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.24.1`), 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** (no permission prompts, the default) for each launch. `Shift+Tab` in the prompt cycles modes. In Edits mode, anything the permissions block comes to you: Claude Code waits for **Allow / Always / Deny**, and the other harnesses show an **Allow & retry** card. |
@@ -65,7 +65,7 @@ From there you can **follow up**, **answer its questions**, **take it over** in
 
 ## Quick start
 
-> **Requirements:** macOS, Linux, or Windows; Node.js ≥ 20; and at least one harness installed and signed in: [Claude Code](https://claude.com/claude-code) (`claude`), [Codex](https://github.com/openai/codex) (`codex`), [opencode](https://opencode.ai) (`opencode`), [Cursor CLI](https://cursor.com/cli) (`cursor-agent`), [Antigravity CLI](https://antigravity.google/docs/cli/headless/) (`agy`), or [Grok Build](https://x.ai/cli) (`grok`). Override a binary path with `WISP_CLAUDE_BIN`, `WISP_CODEX_BIN`, `WISP_OPENCODE_BIN`, `WISP_CURSOR_BIN`, or `WISP_ANTIGRAVITY_BIN`.
+> **Requirements:** macOS, Linux, or Windows; Node.js ≥ 20; and at least one harness installed and signed in: [Claude Code](https://claude.com/claude-code) (`claude`), [Codex](https://github.com/openai/codex) (`codex`), [opencode](https://opencode.ai) (`opencode`), [Cursor CLI](https://cursor.com/cli) (`cursor-agent`), [Antigravity CLI](https://antigravity.google/docs/cli/headless/) (`agy`), or [Grok Build](https://x.ai/cli) (`grok`). No CLI? The [ChatGPT desktop app](https://chatgpt.com/download) is enough for Codex on macOS and Linux, and the [Claude desktop app](https://claude.com/download) for Claude Code on macOS and Windows once you've opened its Code tab and signed that CLI in once: wisp uses the CLI each app ships when the command isn't on PATH. Override a binary path with `WISP_CLAUDE_BIN`, `WISP_CODEX_BIN`, `WISP_OPENCODE_BIN`, `WISP_CURSOR_BIN`, or `WISP_ANTIGRAVITY_BIN`.
 
 ```sh
 npx wisp-agents                          # open the wisp desktop app
@@ -85,7 +85,7 @@ brew install m0xoo/tap/wisp-agents             # Homebrew: CLI and browser mode,
 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://trywisp.dev/install.sh | WISP_VERSION=0.23.0 bash`).
+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://trywisp.dev/install.sh | WISP_VERSION=0.24.1 bash`).
 
 From source:
 
@@ -135,7 +135,7 @@ wisp btw <id> "did you do X?"     # ask on the side without interrupting the run
 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.23.0            # run a recipe; values fill its {params} (or version=0.23.0)
+wisp run release 0.24.1            # run a recipe; values fill its {params} (or version=0.24.1)
 wisp recipes                      # list recipes
 wisp usage [--days 7]             # spend and outcomes
 wisp mcp                          # MCP server for other agents and editors
@@ -354,7 +354,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.23.0` fills the fields in order, `wisp run release version=0.23.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.24.1` fills the fields in order, `wisp run release version=0.24.1` by name.
 
 **Triggers** launch sessions on their own while wisp is open (⌘K → *Triggers*):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wisp-agents",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Run Claude Code, Codex, Cursor and other coding agents in parallel, in the background, on any of your machines. Skip the transcript, read the report.",
   "type": "module",
   "bin": {

package/server/adapters/antigravity.js

@@ -37,6 +37,11 @@ export default {
     return [BIN, ...(resumeId ? ['--conversation', resumeId] : []), ...(model ? ['--model', model] : []), ...(effort ? ['--effort', effort] : [])];
   },
 
+  // How to get it, shown in Settings → Agents and the picker while it isn't found (this OS's steps).
+  setup() {
+    return { tip: 'Install the Antigravity CLI (agy) and sign in. The Antigravity app doesn’t include it', url: 'https://antigravity.google/docs/cli/headless/' };
+  },
+
   async detect() {
     const found = await detectVersion(BIN);
     if (!found.available) return found;

package/server/adapters/claude.js

@@ -3,10 +3,46 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { ASK_TIMEOUT_MS, MAX_SNAPSHOT, attachmentNote, clip, detectVersion, exitText, flatten, rel, spawnJsonl } from './common.js';
+import { ASK_TIMEOUT_MS, MAX_SNAPSHOT, attachmentNote, clip, detectFirst, exitText, flatten, rel, spawnJsonl } from './common.js';
 import { describeCommand } from './commands.js';
 
-const BIN = process.env.WISP_CLAUDE_BIN || 'claude';
+const DEFAULT_BIN = process.env.WISP_CLAUDE_BIN || 'claude';
+let BIN = DEFAULT_BIN;
+// Where claude lives when it isn't on PATH: the native installer's folders (an app started from
+// the Dock never reads the shell profile that adds them), then the copies the Claude desktop app
+// downloads for its Code tab into <userData>/claude-code/<version>/<sha12>/ (older builds: straight
+// into <version>/; macOS builds may wrap it in claude.app), newest version first. That copy is
+// signed in only while the app runs it, so on its own it needs one sign-in.
+const newestFirst = (dir) => {
+  try {
+    return fs.readdirSync(dir).sort((a, b) => b.localeCompare(a, 'en', { numeric: true }));
+  } catch {
+    return [];
+  }
+};
+export const fallbackBins = () => {
+  const home = os.homedir();
+  const win = process.platform === 'win32';
+  const exe = win ? 'claude.exe' : 'claude';
+  const local = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  // The app's userData: a direct install, then the two Store (MSIX) packages, whose AppData writes
+  // land in their own LocalCache.
+  const userData = {
+    darwin: [path.join(home, 'Library', 'Application Support', 'Claude')],
+    win32: [
+      path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Claude'),
+      ...['Claude_pzs8sxrjxfjjc', 'AnthropicPBC.Claude_fnn82j28hfe8t'].map((p) => path.join(local, 'Packages', p, 'LocalCache', 'Roaming', 'Claude')),
+    ],
+  }[process.platform] || [];
+  const desktop = userData.flatMap((d) => {
+    const root = path.join(d, 'claude-code');
+    return newestFirst(root).flatMap((v) => [
+      ...newestFirst(path.join(root, v)).flatMap((h) => [path.join(root, v, h, exe), path.join(root, v, h, 'claude.app', 'Contents', 'MacOS', 'claude')]),
+      path.join(root, v, exe),
+    ]);
+  });
+  return [path.join(home, '.local', 'bin', exe), ...(win ? [] : [path.join(home, '.claude', 'local', 'claude')]), ...desktop];
+};
 
 // 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.
@@ -46,8 +82,19 @@ export default {
     return [BIN, ...(resumeId ? ['--resume', resumeId] : []), ...(model ? ['--model', model] : []), ...(effort ? ['--effort', effort] : []), ...dirs.flatMap((d) => ['--add-dir', d])];
   },
 
-  detect() {
-    return detectVersion(BIN);
+  // How to get it, shown in Settings → Agents and the picker while it isn't found (this OS's steps).
+  setup(platform = process.platform) {
+    return {
+      tip: platform === 'linux' ? 'Install Claude Code, then run claude once to sign in' : 'Install Claude Code and run claude once to sign in. Or open the Claude app’s Code tab once: wisp uses the copy it downloads',
+      command: platform === 'win32' ? 'irm https://claude.ai/install.ps1 | iex' : 'curl -fsSL https://claude.ai/install.sh | bash',
+      url: 'https://claude.com/claude-code',
+    };
+  },
+
+  async detect() {
+    const { bin, ...found } = await detectFirst(DEFAULT_BIN, fallbackBins, !!process.env.WISP_CLAUDE_BIN);
+    BIN = bin;
+    return found;
   },
 
   // What a permission prompt is about, for the approval card and for matching "always allow".

package/server/adapters/codex.js

@@ -1,10 +1,30 @@
 // Codex CLI adapter — drives `codex exec --json` (JSONL thread/turn/item events).
 
+import os from 'node:os';
 import path from 'node:path';
-import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, flatten, rel, spawnJsonl, withProtocol } from './common.js';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectFirst, exitText, fileTracker, flatten, rel, spawnJsonl, withProtocol } from './common.js';
 import { describeCommand } from './commands.js';
 
-const BIN = process.env.WISP_CODEX_BIN || 'codex';
+const DEFAULT_BIN = process.env.WISP_CODEX_BIN || 'codex';
+let BIN = DEFAULT_BIN;
+// Where codex lives when it isn't on PATH: the standalone installer's own copy (its ~/.local/bin
+// link may not be on an app's PATH; on Windows it also keeps one in Programs\OpenAI\Codex), then
+// the CLI the ChatGPT desktop app ships: in its bundle on macOS (the older Codex.app kept it at
+// Resources/codex) and in /usr/lib/chatgpt from the Linux .deb. They share ~/.codex, so the app's
+// sign-in carries. The Windows app is a Store package whose files can't be run from outside it.
+export const fallbackBins = () => {
+  const home = os.homedir();
+  if (process.platform === 'win32') {
+    const local = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    return [path.join(home, '.codex', 'packages', 'standalone', 'current', 'bin', 'codex.exe'), path.join(local, 'Programs', 'OpenAI', 'Codex', 'bin', 'codex.exe')];
+  }
+  const apps = process.platform === 'darwin' ? ['/Applications', path.join(home, 'Applications')] : [];
+  return [
+    path.join(home, '.codex', 'packages', 'standalone', 'current', 'bin', 'codex'),
+    ...apps.flatMap((d) => [path.join(d, 'ChatGPT.app', 'Contents', 'Resources', 'codex-cli', 'bin', 'codex'), path.join(d, 'Codex.app', 'Contents', 'Resources', 'codex')]),
+    ...(process.platform === 'linux' ? ['/usr/lib/chatgpt/resources/codex'] : []),
+  ];
+};
 const IMAGE = /^image\/(png|jpe?g|gif|webp)$/;
 
 // Codex has no "accept edits only" mode; workspace-write lets it edit the project and run
@@ -29,8 +49,22 @@ export default {
     return [BIN, ...(resumeId ? ['resume', resumeId] : []), ...(model ? ['--model', model] : []), ...(effort ? ['-c', `model_reasoning_effort=${toml(effort)}`] : [])];
   },
 
-  detect() {
-    return detectVersion(BIN);
+  // How to get it, shown in Settings → Agents and the picker while it isn't found (this OS's steps).
+  setup(platform = process.platform) {
+    return {
+      tip:
+        platform === 'win32'
+          ? 'Install the Codex CLI and run codex once to sign in. On Windows the ChatGPT app’s built-in Codex can’t be run from outside the app'
+          : 'Install the Codex CLI and run codex once to sign in. Or install the ChatGPT desktop app and sign in there: wisp uses the Codex inside it',
+      command: 'npm i -g @openai/codex',
+      url: 'https://github.com/openai/codex',
+    };
+  },
+
+  async detect() {
+    const { bin, ...found } = await detectFirst(DEFAULT_BIN, fallbackBins, !!process.env.WISP_CODEX_BIN);
+    BIN = bin;
+    return found;
   },
 
   // dirs: the task's other folders, writable like cwd.

package/server/adapters/common.js

@@ -18,6 +18,19 @@ export function detectVersion(bin, args = ['--version']) {
   });
 }
 
+// Detect `bin`, or when it doesn't run, the first copy in fallbacks() that does: CLIs that live
+// off PATH (an install wisp made, a desktop app's bundled CLI). Resolves detectVersion's answer
+// plus the `bin` that answered. An explicit WISP_*_BIN override (`pinned`) is never second-guessed.
+export async function detectFirst(bin, fallbacks, pinned = false) {
+  const found = await detectVersion(bin);
+  if (found.available || pinned) return { ...found, bin };
+  for (const b of fallbacks().filter((f) => fs.existsSync(f))) {
+    const there = await detectVersion(b);
+    if (there.available) return { ...there, bin: b };
+  }
+  return { ...found, bin };
+}
+
 // Run `bin args` and resolve with stdout, or '' on any failure. Used for model discovery.
 export function quietOutput(bin, args, timeout = 15_000) {
   return new Promise((resolve) => {

package/server/adapters/cursor.js

@@ -18,6 +18,15 @@ export default {
     return [BIN, ...(resumeId ? ['--resume', resumeId] : []), ...(model ? ['--model', model] : [])];
   },
 
+  // How to get it, shown in Settings → Agents and the picker while it isn't found (this OS's steps).
+  setup(platform = process.platform) {
+    return {
+      tip: 'Install the Cursor CLI, then run cursor-agent login. The Cursor editor doesn’t include it',
+      ...(platform === 'win32' ? {} : { command: 'curl https://cursor.com/install -fsS | bash' }),
+      url: 'https://cursor.com/cli',
+    };
+  },
+
   async detect() {
     const found = await detectVersion(BIN);
     if (!found.available) return found;

package/server/adapters/grok.js

@@ -35,6 +35,11 @@ export default {
     return [BIN, ...(resumeId ? ['--resume', resumeId] : []), ...(model ? ['--model', model] : []), ...(effort ? ['--reasoning-effort', effort] : [])];
   },
 
+  // How to get it, shown in Settings → Agents and the picker while it isn't found (this OS's steps).
+  setup() {
+    return { tip: 'Install Grok Build (grok) and sign in', url: 'https://x.ai/cli' };
+  },
+
   async detect() {
     const found = await detectVersion(BIN);
     if (!found.available) return found;

package/server/adapters/index.js

@@ -13,6 +13,7 @@
 //                                                  that conversation, leaving it as it is (/btw)
 //     permission?(tool, input, cwd): { tool, action, detail, why? }   what a live approval is about
 //     detect(): Promise<{ available, version?, error?, models? }>   models overrides the static list
+//     setup?(platform): { tip, command?, url? }    how to get it on that OS, sent while it isn't found
 //     resumeCommand({ resumeId, model, effort }): string[]   argv to continue the session interactively
 //     run({ prompt, cwd, resumeId, mode, model, effort, systemPrompt, grants, onEvent }): { stop(), done: Promise }
 //                                                  grants: `rule`s from its own blocked events the
@@ -52,6 +53,7 @@ function checked(a) {
     a.askTool !== null && a.askTool !== undefined && typeof a.askTool !== 'string' && 'askTool',
     a.approveTool !== undefined && (typeof a.approveTool !== 'string' || typeof a.permission !== 'function') && 'approveTool + permission()',
     typeof a.detect !== 'function' && 'detect()',
+    a.setup !== undefined && typeof a.setup !== 'function' && 'setup()',
     typeof a.run !== 'function' && 'run()',
     a.resumeCommand !== undefined && typeof a.resumeCommand !== 'function' && 'resumeCommand()',
   ].filter(Boolean);
@@ -74,7 +76,7 @@ export async function listAgents({ fresh = false } = {}) {
       // Only a hit is cached: a CLI installed while wisp is running shows up on the next call.
       if (!found.available) detected.delete(a.id);
       // delegates: can lead a team of subagents (needs wisp's MCP server injected).
-      return { id: a.id, name: a.name, models: a.models, efforts: a.efforts || [], delegates: a.askTool !== null, ...found };
+      return { id: a.id, name: a.name, models: a.models, efforts: a.efforts || [], delegates: a.askTool !== null, ...found, ...(!found.available && a.setup && { setup: a.setup() }) };
     }),
   );
 }

package/server/adapters/opencode.js

@@ -1,10 +1,9 @@
 // opencode adapter — drives `opencode run --format json` (one JSON event per line).
 
-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';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectFirst, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
 import { describeCommand } from './commands.js';
 
 const exe = process.platform === 'win32' ? 'opencode.cmd' : 'opencode';
@@ -12,7 +11,8 @@ const exe = process.platform === 'win32' ? 'opencode.cmd' : 'opencode';
 // 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';
+const DEFAULT_BIN = process.env.WISP_OPENCODE_BIN || 'opencode';
+let BIN = DEFAULT_BIN;
 // 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.
@@ -35,17 +35,14 @@ export default {
     return [BIN, ...(resumeId ? ['--session', resumeId] : []), ...(model ? ['--model', model] : [])];
   },
 
+  // How to get it, shown in Settings → Agents and the picker while it isn't found (this OS's steps).
+  setup() {
+    return { tip: 'wisp can install it here: free models, no account needed', command: 'npm i -g opencode-ai', url: 'https://opencode.ai' };
+  },
+
   async detect() {
-    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;
-      }
-    }
+    const { bin, ...found } = await detectFirst(DEFAULT_BIN, fallbackBins, !!process.env.WISP_OPENCODE_BIN);
+    BIN = bin;
     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.

package/server/openapi.js

@@ -25,7 +25,7 @@ export function openapi({ version, port }) {
     paths: {
       '/health': { get: { summary: 'Liveness, version and pid', responses: { 200: json(ref('Health')) } } },
       '/update': {
-        get: { summary: 'Current and latest published version, and how this copy updates (global | npx | git). ?check forces a registry check', responses: { 200: json({ type: 'object' }) } },
+        get: { summary: 'Current and latest published version, and how this copy updates (global | npx | brew | git; a git clone never offers one). ?check forces a registry check', responses: { 200: json({ type: 'object' }) } },
         post: { summary: 'Install the latest version and relaunch. 409 while agents run unless { force: true }', responses: { 202: json({ type: 'object' }), 409: json({ type: 'object' }) } },
       },
       '/preferences': {
@@ -304,7 +304,7 @@ export function openapi({ version, port }) {
       schemas: {
         Error: { type: 'object', properties: { error: { type: 'string' } } },
         Health: { type: 'object', properties: { ok: { type: 'boolean' }, name: { const: 'wisp' }, version: { type: 'string' }, apiVersion: { type: 'integer' }, pid: { type: 'integer' }, url: { type: 'string' } } },
-        Agent: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, available: { type: 'boolean' }, version: { type: 'string' }, models: { type: 'array', items: { type: 'object' } }, efforts: { type: 'array', items: { type: 'string' } } } },
+        Agent: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, available: { type: 'boolean' }, version: { type: 'string' }, models: { type: 'array', items: { type: 'object' } }, efforts: { type: 'array', items: { type: 'string' } }, setup: { type: 'object', description: 'Only while not found: how to get it on that OS', properties: { tip: { type: 'string' }, command: { type: 'string' }, url: { type: 'string' } } } } },
         Project: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, path: { type: 'string' }, color: { type: 'string' } } },
         Webhook: { type: 'object', required: ['url'], properties: { url: { type: 'string', format: 'uri' }, events: { type: 'array', items: { enum: ['session.finished', 'session.waiting'] } } } },
         Launch: {

package/server/update.js

@@ -1,8 +1,9 @@
 // Update check: polls the npm registry for a newer wisp-agents and, when asked, installs it and
 // relaunches wisp. How depends on how this copy was installed:
-//   global  npm install -g wisp-agents@latest, then rerun bin/wisp.js from the same folder
+//   global  npm install -g wisp-agents@latest (also what install.sh does), then rerun bin/wisp.js
 //   npx     nothing to install: relaunch through `npx -y wisp-agents@latest`
-//   git     a clone: we only tell you to pull
+//   brew    brew upgrade m0xoo/tap/wisp-agents, then rerun it from the keg's opt/ link
+//   git     a clone of the repo, i.e. working on wisp itself: never offers an update
 // Opt out with WISP_UPDATE_CHECK=0.
 
 import { spawn } from 'node:child_process';
@@ -16,6 +17,9 @@ const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'))
 const REGISTRY = `https://registry.npmjs.org/${PKG.name}/latest`;
 const DAY = 24 * 3600_000;
 const TICK = 30 * 60_000; // timers stall while the machine sleeps, so poll the wall clock instead
+const TAP = 'm0xoo/tap/wisp-agents';
+// <prefix>/Cellar/wisp-agents/<version>/libexec/lib/node_modules/wisp-agents
+const CELLAR = /^(.*)[\\/]Cellar[\\/]wisp-agents[\\/]/;
 
 export function newer(a, b) {
   const p = (v) => String(v).replace(/^v/, '').split(/[-+]/)[0].split('.').map(Number);
@@ -25,20 +29,23 @@ export function newer(a, b) {
 }
 
 export function installMethod(root = ROOT) {
+  if (CELLAR.test(root)) return 'brew';
   if (fs.existsSync(path.join(root, '.git'))) return 'git';
   if (/[\\/]_npx[\\/]/.test(root)) return 'npx';
   return 'global';
 }
 
 export class Updater {
-  constructor({ port, onChange = () => {}, env = process.env, fetch = globalThis.fetch, now = Date.now } = {}) {
+  constructor({ port, onChange = () => {}, env = process.env, fetch = globalThis.fetch, now = Date.now, root = ROOT } = {}) {
     this.port = port;
     this.onChange = onChange;
     this.fetch = fetch;
     this.now = now;
     this.checkedAt = -Infinity;
-    this.enabled = !/^(0|false|no|off)$/i.test(env.WISP_UPDATE_CHECK || '') && !env.CI;
-    this.method = installMethod();
+    this.root = root;
+    this.method = installMethod(root);
+    this.brew = root.match(CELLAR)?.[1]; // Homebrew's prefix, e.g. /opt/homebrew
+    this.enabled = this.method !== 'git' && !/^(0|false|no|off)$/i.test(env.WISP_UPDATE_CHECK || '') && !env.CI;
     this.state = { current: PKG.version, latest: null, available: false, method: this.method, status: 'idle', error: null };
   }
 
@@ -60,9 +67,20 @@ export class Updater {
   }
 
   view() {
-    const s = this.state;
-    const command = { global: `npm install -g ${PKG.name}@latest`, npx: `npx -y ${PKG.name}@latest`, git: 'git pull' }[s.method];
-    return { ...s, command, auto: s.method !== 'git' };
+    return { ...this.state, command: this.command() };
+  }
+
+  // What installs the latest version; shown to copy if it fails. A clone has none.
+  command() {
+    if (this.method === 'brew') return `${JSON.stringify(path.join(this.brew, 'bin', 'brew'))} upgrade ${TAP}`;
+    return { global: `npm install -g ${PKG.name}@latest`, npx: `npx -y ${PKG.name}@latest` }[this.method];
+  }
+
+  // Where the updated copy lives: the same folder, except Homebrew puts each version in its own
+  // keg and keeps opt/wisp-agents pointing at the current one.
+  home() {
+    if (this.method !== 'brew') return this.root;
+    return path.join(this.brew, 'opt', 'wisp-agents', 'libexec', 'lib', 'node_modules', PKG.name);
   }
 
   async check() {
@@ -71,20 +89,28 @@ export class Updater {
       const r = await this.fetch(REGISTRY, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(10_000) });
       if (!r.ok) return this.view();
       const { version } = await r.json();
-      const available = newer(version, PKG.version);
+      const available = this.method !== 'git' && newer(version, PKG.version);
       if (version !== this.state.latest || available !== this.state.available) this.set({ latest: version, available });
     } catch {} // offline: try again next round
     return this.view();
   }
 
-  // Installs (global) then hands off to a detached helper that waits for this server's port to
-  // free up and starts the new version. The caller shuts this process down.
+  // Installs (npm or brew; npx fetches on relaunch) then hands off to a detached helper that waits
+  // for this server's port to free up and starts the new version. The caller shuts this process down.
   async install() {
-    if (this.method === 'git') throw bad('This is a git checkout: run `git pull` to update.');
+    if (this.method === 'git') throw bad('This copy of wisp is a git clone, so it does not update itself.');
     if (this.state.status === 'installing') throw bad('Already updating.', 409);
     this.set({ status: 'installing', error: null });
     try {
-      if (this.method === 'global') await run(`npm install -g ${PKG.name}@latest`);
+      if (this.method !== 'npx') {
+        // Old kegs stay until brew's own periodic cleanup: this process still runs from one.
+        await run(this.command(), this.method === 'brew' ? { HOMEBREW_NO_INSTALL_CLEANUP: '1' } : {});
+        // Relaunching a copy that didn't change would leave the UI waiting for a version that never comes.
+        const got = installedVersion(this.home());
+        if (!newer(got, PKG.version)) {
+          throw bad(this.method === 'brew' ? `Homebrew doesn't have wisp ${this.state.latest} yet. Try again later.` : `npm installed wisp somewhere else: this copy is still ${got || PKG.version}.`);
+        }
+      }
     } catch (err) {
       this.set({ status: 'idle', error: err.message });
       throw err;
@@ -97,13 +123,21 @@ export class Updater {
   relaunchCommand(electron = !!process.versions.electron) {
     const args = `${electron ? '' : ' --browser --no-open'} --port ${this.port}`; // desktop: reopen the app; browser: keep the tab
     const node = JSON.stringify(electron ? 'node' : process.execPath);
-    return this.method === 'npx' ? `npx -y ${PKG.name}@latest${args}` : `${node} ${JSON.stringify(path.join(ROOT, 'bin', 'wisp.js'))}${args}`;
+    return this.method === 'npx' ? `npx -y ${PKG.name}@latest${args}` : `${node} ${JSON.stringify(path.join(this.home(), 'bin', 'wisp.js'))}${args}`;
+  }
+}
+
+function installedVersion(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
+  } catch {
+    return null;
   }
 }
 
-function run(cmd) {
+function run(cmd, env = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn(cmd, { shell: true, stdio: ['ignore', 'ignore', 'pipe'], env: withoutElectronNode() });
+    const child = spawn(cmd, { shell: true, stdio: ['ignore', 'ignore', 'pipe'], env: { ...withoutElectronNode(), ...env } });
     let err = '';
     child.stderr.on('data', (d) => (err = (err + d).slice(-2000)));
     child.on('error', reject);

package/web/css/feed.css

@@ -34,6 +34,9 @@
 .f-group h4.toggle-done { width: fit-content; min-height: 24px; margin-left: -4px; padding: 0 8px; border-radius: 6px; transition: background 0.15s, color 0.15s; }
 .f-group h4.toggle-done:hover { background: var(--bg-2); }
 .f-list { display: flex; flex-direction: column; gap: 6px; }
+/* The end of a paged Done / Archived list: scrolling near it adds the next page, clicking does too. */
+.f-more { display: block; margin: 10px auto 0; color: var(--faint); font-weight: 400; }
+.f-more:hover { color: var(--ink-2); }
 .feed-empty { padding: 48px 0; text-align: center; color: var(--faint); font-size: 13.5px; }
 
 /* one feed item — a row that expands in place */

package/web/css/launcher.css

@@ -195,10 +195,11 @@ body:has(.launcher.docked:is(:focus-within, :has(.open))) .to-top { display: non
 .pk-side { display: flex; flex-direction: column; gap: 2px; padding: 6px; overflow-y: auto; background: var(--surface-2); border-right: 1px solid var(--line); }
 .pk-head, .pk-ghead { padding: 8px 10px 5px; font-size: 11px; font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; color: var(--faint); }
 .pk-h, .pk-m { display: flex; align-items: center; gap: 10px; width: 100%; padding: 7px 9px; border-radius: 9px; text-align: left; outline: 0; color: var(--ink-2); transition: background 0.12s; }
-.pk-h:hover:not(:disabled), .pk-m:hover, .pk-m:focus-visible { background: var(--bg-2); }
+.pk-h:hover, .pk-m:hover, .pk-m:focus-visible { background: var(--bg-2); }
 .pk-h:focus-visible { box-shadow: inset 0 0 0 1px var(--line-2); }
 .pk-h.on { background: var(--surface); box-shadow: 0 0 0 1px var(--line-2), var(--shadow-1); }
-.pk-h.off { opacity: 0.45; cursor: not-allowed; }
+.pk-h.off .pk-logo, .pk-h.off .pk-text { opacity: 0.5; }
+.pk-h.off.on .pk-logo, .pk-h.off.on .pk-text { opacity: 0.8; }
 .pk-logo { display: grid; place-items: center; flex: none; width: 28px; height: 28px; border-radius: 8px; background: var(--surface); border: 1px solid var(--line); color: var(--ink); }
 .pk-h.on .pk-logo { background: var(--bg-2); border-color: transparent; }
 .pk-logo > * { display: block; width: 15px; height: 15px; }
@@ -224,6 +225,21 @@ body:has(.launcher.docked:is(:focus-within, :has(.open))) .to-top { display: non
 .pk-seg button:focus-visible { box-shadow: inset 0 0 0 1px var(--accent); }
 .pk-seg button.on { background: var(--surface); color: var(--accent-ink); font-weight: 500; box-shadow: var(--shadow-1); }
 .pk-empty { padding: 30px 10px; text-align: center; font-size: 13px; color: var(--muted); }
+/* a harness that isn't installed: its setup steps instead of models */
+.pk-setup { display: flex; flex-direction: column; align-items: flex-start; gap: 8px; padding: 12px 8px; }
+.pk-setup b { font-weight: 600; font-size: 13.5px; color: var(--ink); }
+.pk-setup p { margin: 0; font-size: 12.5px; line-height: 1.5; color: var(--muted); }
+.pk-setup-actions { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 2px; }
+.pk-recheck.busy { cursor: progress; }
+.pk-recheck.busy .i { animation: spin 0.8s linear infinite reverse; }
+/* a copyable install command (picker and Settings → Agents) */
+.setup-cmd { display: inline-flex; align-items: center; gap: 7px; max-width: 100%; height: 28px; padding: 0 8px; border: 1px solid var(--line); border-radius: 8px; background: var(--bg-2); color: var(--ink-2); font: 12px/1 var(--mono); cursor: copy; transition: border-color 0.12s, color 0.12s; }
+.setup-cmd:hover { border-color: var(--line-2); color: var(--ink); }
+.setup-cmd .p { color: var(--faint); }
+button.setup-cmd code { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font: inherit; background: none; padding: 0; }
+.setup-cmd .i { flex: none; width: 13px; height: 13px; color: var(--muted); }
+.setup-cmd.copied .i { color: var(--good); }
+.sx-text .setup-cmd { display: flex; width: fit-content; margin-top: 6px; }
 @media (max-width: 560px) {
   .picker { grid-template-columns: 1fr; grid-template-rows: auto 1fr; }
   .pk-side { flex-direction: row; overflow-x: auto; border-right: 0; border-bottom: 1px solid var(--line); }

package/web/css/modals.css

@@ -132,6 +132,9 @@
   .sx-main { padding: 16px; }
   .sx-ctl .input { width: 180px; }
   .sx-usage { grid-template-columns: repeat(2, 1fr); }
+  /* a harness that isn't found: its setup tip gets the full width, its buttons go underneath */
+  .sx-agents .sx-row:has(.sx-state.bad) { flex-wrap: wrap; row-gap: 6px; }
+  .sx-agents .sx-row:has(.sx-state.bad) .sx-text { flex-basis: 100%; }
 }
 
 /* memory: what the background retros learned */

package/web/js/features/feed.js

@@ -66,13 +66,47 @@ function groups() {
   return { needs, working, done, archived };
 }
 
+// Done and Archived can hold hundreds of tasks: they show a page of cards and add the next
+// page as the user scrolls to the end of the list. The headings count every one.
+const PAGE = 60;
+const page = { secDone: PAGE, secArchived: PAGE };
+const moreObserver = new IntersectionObserver(
+  (entries) => {
+    for (const e of entries) {
+      if (!e.isIntersecting || e.target.hidden) continue;
+      page[e.target.closest('.f-group').id] += PAGE;
+      renderFeed();
+      // Still in view after a short page: observing again reports it again, so the next page comes.
+      moreObserver.unobserve(e.target);
+      moreObserver.observe(e.target);
+    }
+  },
+  { root: stage, rootMargin: '0px 0px 800px 0px' },
+);
+for (const id of Object.keys(page)) {
+  const more = el(`<button class="f-more link xs" hidden></button>`);
+  more.addEventListener('click', () => {
+    page[id] += PAGE;
+    renderFeed();
+  });
+  $(`#${id}`).append(more);
+  moreObserver.observe(more);
+}
+
 export function renderFeed() {
   const { needs, working, done, archived } = groups();
   const place = (sec, list, show = true) => {
     const box = $('.f-list', sec);
     sec.hidden = !list.length;
     $('h4 .n', sec).textContent = list.length || '';
-    const want = show ? list : [];
+    const cap = page[sec.id] ?? list.length;
+    const want = show ? list.slice(0, cap) : [];
+    const more = $('.f-more', sec);
+    if (more) {
+      const left = show ? list.length - want.length : 0;
+      more.hidden = left <= 0;
+      more.textContent = `Show ${Math.min(left, PAGE)} more · ${left} left`;
+    }
     want.forEach((s, i) => {
       const { card } = s.runs ? taskItem(s) : item(s);
       // Only touch the DOM when the order actually changed: moving a node
@@ -83,9 +117,9 @@ export function renderFeed() {
   };
   place($('#secNeeds'), needs);
   place($('#secWorking'), working);
-  place($('#secDone'), done.slice(0, 60), S.showDone);
+  place($('#secDone'), done, S.showDone);
   $('#secDone').classList.toggle('collapsed', !S.showDone);
-  place($('#secArchived'), archived.slice(0, 60), S.showArchived);
+  place($('#secArchived'), archived, S.showArchived);
   $('#secArchived').classList.toggle('collapsed', !S.showArchived);
 
   // Drop nodes for sessions that are gone or filtered out of the feed entirely.
@@ -399,6 +433,13 @@ export function reveal(id) {
     save('wisp.filter', S.filter);
     renderLaunchChips();
   }
+  // A card further down than the pages shown so far: show pages up to it.
+  const sec = { done: 'secDone', archived: 'secArchived' }[sectionOf(s)];
+  if (sec) {
+    const { done, archived } = groups();
+    const at = (sec === 'secDone' ? done : archived).findIndex((t) => (t.runs || [t]).some((r) => r.id === id));
+    if (at >= page[sec]) page[sec] = Math.ceil((at + 1) / PAGE) * PAGE;
+  }
   renderFeed();
   setFocus(id, { scroll: false });
   if (S.open.has(id)) S.nodes.get(id)?.card.scrollIntoView({ block: 'start', behavior: 'smooth' });

package/web/js/features/runner-picker.js

@@ -1,10 +1,14 @@
 import { esc } from '../md.js';
+import { api } from '../core/api.js';
+import * as bus from '../core/bus.js';
 import { $, $$, el, icon } from '../core/dom.js';
-import { S } from '../core/state.js';
+import { S, setAgents } from '../core/state.js';
 import { popover } from '../ui/popover.js';
+import { toast, toastError } from '../ui/toast.js';
 import { placeName } from './places.js';
 import { AUTO, AUTO_GOALS, effortLabel, effortsFor, harnessesAt, harnessLogo } from './runners.js';
 import { openSettings } from './settings.js';
+import { copySetupCommand, INSTALLABLE, installHarness, setupCommand, setupDocs, setupTip, setupTitle } from './setup.js';
 
 // One popover for all three choices: harnesses on the left, the focused harness's models on the
 // right, and its thinking levels underneath. Clicking (or arrowing to) a harness previews its
@@ -14,9 +18,10 @@ export function runnerPicker(anchor, { agent, model, effort, savedModel, savedEf
   const open = $('.picker');
   if (open) return open.close();
   const agents = places ? harnessesAt(places, { auto }) : auto ? [AUTO, ...S.agents] : S.agents;
+  const remote = places?.length > 1 || !!places?.[0];
   const sub = (a) => {
     if (a.id === 'auto') return 'Picks harness and model for you';
-    if (!a.available) return places?.length > 1 || places?.[0] ? 'Not installed there' : 'Not installed';
+    if (!a.available) return remote ? 'Not installed there' : 'Not installed';
     const models = (a.models || []).length > 1 ? `${a.models.length - 1} models` : 'Default model';
     return a.missing?.length ? `Not on ${a.missing.map(placeName).join(', ')}` : models;
   };
@@ -35,7 +40,7 @@ export function runnerPicker(anchor, { agent, model, effort, savedModel, savedEf
         <div class="pk-head">Harness</div>
         ${agents
           .map(
-            (a) => `<button class="pk-h${a.available ? '' : ' off'}" role="option" data-id="${esc(a.id)}" ${a.available ? '' : 'disabled'}>
+            (a) => `<button class="pk-h${a.available ? '' : ' off'}" role="option" data-id="${esc(a.id)}" ${a.available ? '' : `aria-disabled="true" title="${esc(setupTitle(a))}"`}>
               <span class="pk-logo">${harnessLogo(a.id)}</span>
               <span class="pk-text"><b>${esc(a.name)}</b><small${a.missing?.length ? ' class="warn"' : ''}>${esc(sub(a))}</small></span>
               ${a.id === agent ? '<span class="pk-dot" title="In use"></span>' : ''}
@@ -86,6 +91,7 @@ export function runnerPicker(anchor, { agent, model, effort, savedModel, savedEf
     const models = a?.models || [{ id: '', label: 'Default' }];
     const current = focusAgent === agent ? model : savedModel(focusAgent);
     input.placeholder = `Search ${a?.name || ''} models`;
+    if (a && !a.available) return paintSetup(a);
     if (a?.id === 'auto') {
       list.innerHTML = `<div class="pk-group"><div class="pk-ghead">Goal</div>${AUTO_GOALS.map((g) => `<button class="pk-m${g.id === current ? ' on' : ''}" role="option" aria-selected="${g.id === current}" data-id="${g.id}"><span class="pk-text"><b>${g.label}</b><small>${g.hint}</small></span>${icon('check', 'pk-check')}</button>`).join('')}</div><p class="pk-note">wisp picks the harness and model for each task from what worked before, and learns from how it went. ${'<a href="#" class="pk-auto-more">How Auto picks</a>'}</p><div class="pk-empty" hidden>No models match</div>`;
       $('.pk-search', node).hidden = true;
@@ -120,6 +126,51 @@ export function runnerPicker(anchor, { agent, model, effort, savedModel, savedEf
     filter();
     paintEffort();
   };
+  // A harness that isn't installed: how to get it, in place of its models.
+  const paintSetup = (a) => {
+    $('.pk-search', node).hidden = true;
+    seg.hidden = true;
+    const canInstall = !remote && INSTALLABLE.has(a.id);
+    list.innerHTML = `<div class="pk-setup">
+      <b>${esc(a.name)} isn’t installed${remote ? ' there' : ''}</b>
+      <p>${esc(setupTip(a))}</p>
+      ${a.setup?.command && !canInstall ? setupCommand(a.setup.command) : ''}
+      <div class="pk-setup-actions">
+        ${canInstall ? `<button class="primary sm pk-install">Install ${esc(a.name)}</button>` : ''}
+        ${setupDocs(a)}
+        <button class="ghost sm pk-recheck" title="Look for harnesses again">${icon('replay')}<span>Re-check</span></button>
+      </div>
+    </div>`;
+    const c = $('.setup-cmd', list);
+    if (c) c.onclick = () => {
+      copySetupCommand(c);
+    };
+    const inst = $('.pk-install', list);
+    if (inst) inst.onclick = () => {
+      close();
+      installHarness(a.id);
+    };
+    $('.pk-recheck', list).onclick = async (e) => {
+      const btn = e.currentTarget;
+      btn.disabled = true;
+      btn.classList.add('busy');
+      try {
+        setAgents(await api('/agents/recheck', { method: 'POST', body: {} }));
+        $('#launcher')?.placesChanged?.();
+        bus.emit('agents');
+        const found = S.agents.find((x) => x.id === a.id)?.available;
+        if (found) {
+          close();
+          toast(`<b>${esc(a.name)}</b> found`);
+        } else if (node.isConnected) toast(`Still no ${esc(a.name)}. Install it, sign in, then re-check.`);
+      } catch (err) {
+        toastError(err);
+      } finally {
+        btn.disabled = false;
+        btn.classList.remove('busy');
+      }
+    };
+  };
   const rows = () => $$('.pk-m', list).filter((b) => !b.hidden);
   const filter = () => {
     const q = input.value.trim().toLowerCase();
@@ -145,7 +196,7 @@ export function runnerPicker(anchor, { agent, model, effort, savedModel, savedEf
   // Picking a harness applies it straight away with the model and level it shows as selected.
   const useAgent = (id) => {
     preview(id);
-    if (id === agent) return;
+    if (id === agent || !agents.find((x) => x.id === id)?.available) return;
     markInUse(id);
     agent = id;
     model = savedModel(id);
@@ -171,7 +222,6 @@ export function runnerPicker(anchor, { agent, model, effort, savedModel, savedEf
   };
   const keys = (e) => {
     const inSide = sideRows.includes(document.activeElement);
-    const live = sideRows.filter((b) => !b.disabled);
     const segBtns = $$('button', seg);
     const inSeg = segBtns.includes(document.activeElement);
     // Tab hops from the model list to the thinking levels and back; anywhere else it leaves.
@@ -191,7 +241,7 @@ export function runnerPicker(anchor, { agent, model, effort, savedModel, savedEf
       e.preventDefault();
       e.stopPropagation();
       const d = e.key === 'ArrowDown' ? 1 : -1;
-      if (inSide) preview(step(live, d)?.dataset.id);
+      if (inSide) preview(step(sideRows, d)?.dataset.id); // not-installed ones too: they show how to get them
       else step(rows(), d);
     } else if (e.key === 'ArrowLeft' && document.activeElement !== input) {
       e.preventDefault();

package/web/js/features/settings.js

@@ -19,7 +19,7 @@ import { notifyOn } from './notify.js';
 import { openPhone, phoneSummary } from './phone.js';
 import { machinesSummary } from './places.js';
 import { AUTO_GOALS, harnessLogo } from './runners.js';
-import { INSTALLABLE, installHarness, isInstalling } from './setup.js';
+import { copySetupCommand, INSTALLABLE, installHarness, isInstalling, setupCommand, setupDocs, setupTip } from './setup.js';
 import { clearPicks } from './transcript.js';
 import { repaintViews } from './turns.js';
 import { openUsage } from './usage.js';
@@ -156,11 +156,13 @@ export function openSettings(opts) {
         // opencode: wisp can install it (free models, no account), so its row offers that.
         const canInstall = !a.available && INSTALLABLE.has(a.id);
         const busy = isInstalling(a.id);
+        // Not found: this OS's setup tip, with the command to copy unless wisp installs it itself.
         const desc = a.available
-          ? [a.version, n && `${n} model${n === 1 ? '' : 's'}`].filter(Boolean).join(' · ')
-          : busy ? 'Installing into ~/.wisp/tools…' : canInstall ? 'Install it here: free models, no account needed' : `Install the ${a.name} CLI and sign in, then re-check`;
+          ? esc([a.version, n && `${n} model${n === 1 ? '' : 's'}`].filter(Boolean).join(' · '))
+          : busy ? 'Installing into ~/.wisp/tools…' : `${esc(setupTip(a))}${a.setup?.command && !canInstall ? setupCommand(a.setup.command) : ''}`;
         const install = canInstall ? `<button class="ghost sm" data-install="${esc(a.id)}" ${busy ? 'disabled' : ''}>${busy ? 'Installing…' : 'Install'}</button>` : '';
-        return row(`<span class="model-logo">${harnessLogo(a.id)}</span>${esc(a.name)}`, esc(desc), `${install}<span class="sx-state ${a.available ? 'ok' : 'bad'}" ${a.error ? `title="${esc(a.error)}"` : ''}><i class="dot ${a.available ? 'ok' : 'bad'}"></i>${a.available ? 'Ready' : 'Not found'}</span>`);
+        const docs = a.available ? '' : setupDocs(a);
+        return row(`<span class="model-logo">${harnessLogo(a.id)}</span>${esc(a.name)}`, desc, `${install}${docs}<span class="sx-state ${a.available ? 'ok' : 'bad'}" ${a.error ? `title="${esc(a.error)}"` : ''}><i class="dot ${a.available ? 'ok' : 'bad'}"></i>${a.available ? 'Ready' : 'Not found'}</span>`);
       }).join('')
       : '<div class="sx-row"><div class="it-loading"><span class="orb tiny"></span>Looking for harnesses…</div></div>';
     const missing = S.agents.filter((a) => !a.available).length;
@@ -174,6 +176,8 @@ export function openSettings(opts) {
   bus.on('agents', paintAgents, { node });
   bus.on('install', paintAgents, { node });
   $('.sx-agents', node).onclick = (e) => {
+    const c = e.target.closest('[data-copy]');
+    if (c) return copySetupCommand(c);
     const b = e.target.closest('[data-install]');
     if (b) installHarness(b.dataset.install);
   };

package/web/js/features/setup.js

@@ -3,6 +3,7 @@
 // Settings → Agents uses the same install.
 
 import { esc } from '../md.js';
+import { copy } from '../blocks.js';
 import { api } from '../core/api.js';
 import * as bus from '../core/bus.js';
 import { $, icon } from '../core/dom.js';
@@ -13,6 +14,17 @@ import { harnessLogo } from './runners.js';
 // What wisp can install itself (server/services/install.js).
 export const INSTALLABLE = new Set(['opencode']);
 
+// A harness that isn't found: how to get it, from the server for that computer's OS
+// (adapter setup()). As a tooltip, as a copyable command, and as a docs link.
+export const setupTip = (a) => a.setup?.tip || `Install the ${a.name} CLI and sign in, then re-check`;
+export const setupTitle = (a) => [setupTip(a), a.setup?.command && `$ ${a.setup.command}`].filter(Boolean).join('\n');
+export const setupCommand = (cmd) => `<button type="button" class="setup-cmd" data-copy="${esc(cmd)}" title="Copy"><span class="p">$</span><code>${esc(cmd)}</code>${icon('copy')}</button>`;
+export const setupDocs = (a, cls = 'ghost sm') => (a.setup?.url ? `<a class="${cls}" href="${esc(a.setup.url)}" target="_blank" rel="noopener" title="${esc(a.name)} install guide">${icon('external')}<span>Docs</span></a>` : '');
+export function copySetupCommand(btn) {
+  copy(btn.dataset.copy, btn);
+  toast('Copied. Run it in a terminal, sign in, then Re-check');
+}
+
 let installing = null; // the running install's id
 let failed = ''; // the last install's error, shown in the strip until the next try
 
@@ -71,7 +83,7 @@ export function renderSetup() {
       setAgents(await api('/agents/recheck', { method: 'POST', body: {} }));
       $('#launcher')?.placesChanged?.();
       bus.emit('agents');
-      if (needsSetup()) toast('Still no harness found. Install opencode here, or Claude Code, Codex, Cursor… yourself.');
+      if (needsSetup()) toast('Still no harness found. Install opencode here, or Claude Code, Codex, Cursor… yourself. The ChatGPT app (Codex) or the Claude app (its Code tab) works too.');
     } catch (err) {
       toastError(err);
     } finally {

package/web/js/features/update.js

@@ -18,12 +18,11 @@ export function renderUpdate(u) {
   b.disabled = busy;
   b.classList.toggle('busy', busy);
   b.querySelector('span').textContent = u.status === 'installing' ? 'Updating…' : u.status === 'restarting' ? 'Restarting…' : `Update to ${u.latest}`;
-  b.title = u.auto ? `wisp ${u.current} → ${u.latest}: install and restart` : `wisp ${u.latest} is out. Run \`${u.command}\` to update`;
+  b.title = `wisp ${u.current} → ${u.latest}: install and restart`;
 }
 
 export async function installUpdate() {
   if (!update?.available) return;
-  if (!update.auto) return toast(`wisp <b>${esc(update.latest)}</b> is out. Run <code>${esc(update.command)}</code>`, { action: { label: 'Copy', run: () => copy(update.command) }, timeout: 8000 });
   const post = (force) => api('/update', { method: 'POST', body: { force } });
   try {
     await post(false).catch(async (err) => {