@venturewild/workspace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VentureWild
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# wild-workspace — Claude Code Web
+
+A Replit/Lovable-style **chat-first** browser UI that wraps the AI agent already installed on your machine (Claude Code by default; Gemini / GLM / Codex if present).
+
+> v0.1.0 — initial scaffold, implements PRD §5.5 (workspace-platform-prd.md v0.10).
+
+## Quick start
+
+```bash
+# install agent dependencies & web build
+npm install
+npm run build
+
+# launch
+node server/src/index.mjs
+# or after `npm install -g .`
+wild-workspace
+```
+
+Opens `http://localhost:5173` in your default browser.
+
+## What's in here
+
+```
+wild-workspace/
+├── server/                # Node.js Hono server + WebSocket bridge
+│   ├── bin/
+│   │   └── wild-workspace.mjs   # CLI entry (the `bin` field)
+│   └── src/
+│       ├── index.mjs            # server bootstrap
+│       ├── config.mjs           # config + role definitions
+│       ├── agent.mjs            # claude / gemini / glm / codex subprocess wrapper
+│       ├── share.mjs            # JWT share-token mint + verify
+│       ├── inbox.mjs            # .wild/inbox.md watcher
+│       ├── fs.mjs               # workspace file tree (collapsed by default)
+│       ├── activity.mjs         # AI activity event bus
+│       ├── preview.mjs          # dev-server port detection
+│       └── routes/              # REST + WS endpoints
+├── web/                   # React + Vite frontend
+│   └── src/
+│       ├── App.jsx              # role-flagged React tree (partner / viewer / client)
+│       ├── components/          # Chat, Preview, FileTree, Terminal, ShareDialog…
+│       └── state/               # session + chat stores
+└── docs/                  # design notes
+```
+
+## The three roles (AR-19)
+
+| Role | URL pattern | What they see |
+|---|---|---|
+| **partner** | `http://localhost:5173` | Chat + preview + file tree + terminal toggle + inbox + share + deploy |
+| **viewer** | `https://workspace.venturewild.llc/<wsid>?t=<token>` | Chat history (read-only) + preview + presence + activity stream |
+| **client** | `https://workspace.<client>.com` | Chat + preview + "request changes" only |
+
+Same React tree, role-gated visibility (AR-19).
+
+## AR-17: wrap don't embed
+
+We don't ship an AI agent. `server/src/agent.mjs` spawns `claude` (or `gemini` / `glm` / `codex` if installed) as a subprocess and pipes stdout/stderr through WebSocket to the chat UI. The wrapped agent's modes mirror automatically (AR-18).
+
+## Rich chat rendering
+
+The chat is the product (AR-16), so it renders like one:
+
+- **Markdown** — agent replies render as GitHub-flavored markdown (`Markdown.jsx`).
+- **Syntax-highlighted code** — fenced code blocks via prism-react-renderer, with a copy button.
+- **Tool cards** — each tool call (`Read`, `Edit`, `Bash`, …) renders as a compact card with a running/done/error status (`ToolCard.jsx`).
+- **Inline diffs** — `Edit` / `Write` / `MultiEdit` show a red/green line diff right in the chat (`DiffView.jsx`).
+- **Live streaming** — text streams token-by-token from the rebuilt `agent.mjs` stream-json parser, with a per-turn cost + token footer.
+
+## License
+
+MIT — VentureWild.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@venturewild/workspace",
+  "version": "0.1.0",
+  "description": "Claude Code Web — Replit/Lovable-style chat-first browser UI that wraps the AI agent already installed on your machine.",
+  "license": "MIT",
+  "bin": {
+    "wild-workspace": "./server/bin/wild-workspace.mjs"
+  },
+  "files": [
+    "server/bin",
+    "server/src",
+    "web/dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "concurrently -k -n server,web -c blue,magenta \"npm:dev:server\" \"npm:dev:web\"",
+    "dev:server": "node --watch server/src/index.mjs",
+    "dev:web": "vite --config web/vite.config.mjs",
+    "build": "npm run build:web",
+    "build:web": "vite build --config web/vite.config.mjs",
+    "prepublishOnly": "npm run build",
+    "start": "node server/src/index.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint . --ext .mjs,.js,.jsx || echo 'skipping (eslint not configured)'"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "chokidar": "^4.0.0",
+    "hono": "^4.6.0",
+    "jose": "^5.9.0",
+    "mime-types": "^2.1.0",
+    "nanoid": "^5.0.0",
+    "open": "^10.1.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.0",
+    "concurrently": "^9.0.0",
+    "diff": "^9.0.0",
+    "playwright": "^1.48.0",
+    "prism-react-renderer": "^2.4.1",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "supertest": "^7.0.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chunin1103/wild-workspace"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "claude-code",
+    "workspace",
+    "replit",
+    "lovable",
+    "wild",
+    "venturewild"
+  ]
+}

package/server/bin/wild-workspace.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// `wild-workspace` CLI entry — the bin field in package.json.
+// Forwards to server/src/index.mjs.
+
+import path from 'node:path';
+import url from 'node:url';
+import { createServer } from '../src/index.mjs';
+import { APP_VERSION } from '../src/config.mjs';
+
+const __filename = url.fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function printUsage() {
+  console.log(`wild-workspace v${APP_VERSION}
+
+Usage:
+  wild-workspace                  start the workspace server in the current directory
+  wild-workspace --port 5173      override port (default 5173)
+  wild-workspace --no-open        don't auto-open browser
+  wild-workspace --host 0.0.0.0   bind to all interfaces (for share-by-URL hosting)
+  wild-workspace install          register the bmo-sync daemon as a background service [v1.x]
+  wild-workspace share            (interactive helper) issue a viewer URL  [v1.x — use UI for now]
+  wild-workspace --help           this message
+  wild-workspace --version        print version
+
+Environment:
+  WILD_WORKSPACE_PORT, WILD_WORKSPACE_HOST,
+  WILD_WORKSPACE_DIR, WILD_WORKSPACE_DATA_DIR,
+  WILD_WORKSPACE_PARTNER_TOKEN, WILD_WORKSPACE_SHARE_SECRET,
+  WILD_WORKSPACE_NO_OPEN=1
+`);
+}
+
+function parseArgs(argv) {
+  const opts = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--version' || arg === '-v') opts.version = true;
+    else if (arg === '--no-open') opts.openBrowser = false;
+    else if (arg === '--port') { opts.port = Number(argv[++i]); }
+    else if (arg === '--host') { opts.host = argv[++i]; }
+    else if (arg === '--workspace') { opts.workspaceDir = argv[++i]; }
+    else if (arg.startsWith('--')) {
+      // ignore unknown flags
+    } else {
+      positional.push(arg);
+    }
+  }
+  opts.positional = positional;
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) return printUsage();
+  if (opts.version) { console.log(APP_VERSION); return; }
+
+  if (opts.positional[0] === 'install') {
+    console.log('`wild-workspace install` is a v1.x feature (bmo-sync daemon).');
+    console.log('For now: run `wild-workspace` directly; sync is via OneDrive/bmo-sync separately.');
+    return;
+  }
+  if (opts.positional[0] === 'share') {
+    console.log('Use the in-app Share button to issue viewer URLs. CLI share command is v1.x.');
+    return;
+  }
+
+  const server = await createServer(opts);
+  const { config } = server;
+  console.log(`\n  wild-workspace v${APP_VERSION}`);
+  console.log(`  workspace : ${config.workspaceDir}`);
+  console.log(`  url       : http://${config.host}:${config.port}`);
+  console.log(`  agent     : ${server.getActiveAgent()?.label || '(none detected — install Claude Code: npm i -g @anthropic-ai/claude-code)'}\n`);
+
+  if (config.openBrowser) {
+    try {
+      const open = (await import('open')).default;
+      open(`http://${config.host}:${config.port}`);
+    } catch {}
+  }
+
+  process.on('SIGINT', async () => {
+    console.log('\nshutting down…');
+    await server.stop();
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => { await server.stop(); process.exit(0); });
+}
+
+main().catch((err) => {
+  console.error('wild-workspace failed:', err);
+  process.exit(1);
+});

package/server/src/activity.mjs

@@ -0,0 +1,71 @@
+// Activity event bus — live AI activity stream + presence (real-time).
+// All paired clients see the same activity. Implemented as in-process pub/sub for v1.
+// v1.1 wires the same channel to bmo-sync's SSE event stream.
+
+import { EventEmitter } from 'node:events';
+import { nanoid } from 'nanoid';
+
+export class ActivityBus extends EventEmitter {
+  constructor() {
+    super();
+    this.setMaxListeners(0);
+    this.recent = [];
+    this.maxRecent = 200;
+    this.presence = new Map(); // sessionId -> { sessionId, role, label, focus, lastSeen }
+    this.usage = { tokensIn: 0, tokensOut: 0, costUsd: 0 };
+  }
+
+  publish(event) {
+    const enriched = {
+      id: nanoid(10),
+      ts: Date.now(),
+      ...event,
+    };
+    this.recent.push(enriched);
+    if (this.recent.length > this.maxRecent) this.recent.shift();
+    if (event.type === 'usage' && event.usage) {
+      this.usage.tokensIn += event.usage.input_tokens || 0;
+      this.usage.tokensOut += event.usage.output_tokens || 0;
+      if (typeof event.usage.cost_usd === 'number') {
+        this.usage.costUsd += event.usage.cost_usd;
+      }
+    }
+    this.emit('event', enriched);
+  }
+
+  joinPresence({ sessionId, role, label }) {
+    const entry = {
+      sessionId: sessionId || nanoid(8),
+      role: role || 'partner',
+      label: label || role || 'partner',
+      focus: null,
+      lastSeen: Date.now(),
+    };
+    this.presence.set(entry.sessionId, entry);
+    this.publish({ type: 'presence-join', sessionId: entry.sessionId, role: entry.role });
+    return entry;
+  }
+
+  leavePresence(sessionId) {
+    if (this.presence.has(sessionId)) {
+      this.presence.delete(sessionId);
+      this.publish({ type: 'presence-leave', sessionId });
+    }
+  }
+
+  updateFocus(sessionId, focus) {
+    const entry = this.presence.get(sessionId);
+    if (!entry) return;
+    entry.focus = focus;
+    entry.lastSeen = Date.now();
+    this.publish({ type: 'presence-focus', sessionId, focus });
+  }
+
+  snapshot() {
+    return {
+      recent: this.recent.slice(-50),
+      presence: [...this.presence.values()],
+      usage: { ...this.usage },
+    };
+  }
+}

package/server/src/agent.mjs

@@ -0,0 +1,335 @@
+// AI agent subprocess wrapper.
+// AR-17: wrap, don't embed. We spawn `claude` and stream its output — we never
+// embed an SDK or run our own agent loop.
+//
+// The stream-json parser is the heart of this file. `claude -p --output-format
+// stream-json --include-partial-messages` emits NDJSON where each line is one of:
+//   - {type:"system",...}            session init / status — ignored
+//   - {type:"rate_limit_event",...}  ignored
+//   - {type:"stream_event",event:{}} the Anthropic streaming protocol, wrapped.
+//                                    This is our PRIMARY source: real-time text
+//                                    deltas, tool-call name + streamed input.
+//   - {type:"assistant",message:{}}  the completed message — REDUNDANT with the
+//                                    stream events, used only as a fallback when
+//                                    --include-partial-messages is off.
+//   - {type:"user",message:{}}       carries tool_result blocks.
+//   - {type:"result",...}            final cost + usage + status.
+
+import { spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { execFile as execFileCb } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { DEFAULT_AGENTS } from './config.mjs';
+
+const execFile = promisify(execFileCb);
+
+const PATH_LOOKUP_TIMEOUT_MS = 1500;
+
+async function isOnPath(binary) {
+  const probe = process.platform === 'win32' ? 'where.exe' : 'which';
+  try {
+    const { stdout } = await execFile(probe, [binary], { timeout: PATH_LOOKUP_TIMEOUT_MS });
+    const lines = stdout.split(/\r?\n/).filter(Boolean);
+    return lines.length > 0 ? lines[0].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function detectAgents(candidates = DEFAULT_AGENTS) {
+  const results = await Promise.all(
+    candidates.map(async (agent) => {
+      const resolved = await isOnPath(agent.binary);
+      return { ...agent, available: Boolean(resolved), resolvedPath: resolved };
+    }),
+  );
+  return results;
+}
+
+/** Flatten a tool_result `content` field (string | array of blocks) to text. */
+function flattenContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((c) => (typeof c === 'string' ? c : c?.text || ''))
+      .join('');
+  }
+  return '';
+}
+
+/**
+ * AgentSession streams one chat turn through a wrapped subprocess.
+ *
+ * Lifecycle per AR-17:
+ *   - one process per user turn (`claude -p` prints + exits)
+ *   - emits 'chunk' — a normalized event the UI understands (see below)
+ *   - emits 'stderr' on stderr output
+ *   - emits 'end' on process exit with code
+ *   - emits 'error' on spawn / runtime error
+ *
+ * Chunk protocol (the only contract the browser depends on):
+ *   { type:'text',        text }                       streamed assistant text
+ *   { type:'thinking',    text }                       streamed extended-thinking
+ *   { type:'tool-use',    id, name, input }            a completed tool call
+ *   { type:'tool-result', id, content, isError }       that tool's result
+ *   { type:'usage',       usage:{...,cost_usd}, ... }   final cost + token usage
+ *   { type:'error',       message }                    a run-level failure
+ */
+export class AgentSession extends EventEmitter {
+  constructor(agent, opts = {}) {
+    super();
+    this.agent = agent;
+    this.opts = opts;
+    this.proc = null;
+    this.closed = false;
+    // stream-json parse state — fresh per session (one session per turn)
+    this._buffer = '';
+    this._sawStreamEvent = false;
+    this._blocks = new Map(); // content-block index -> { kind, id, name, jsonBuf }
+  }
+
+  send(prompt, ctx = {}) {
+    if (this.closed) throw new Error('session closed');
+    const args = [...this.agent.args];
+    if (this.agent.id === 'claude') {
+      if (ctx.cwd) args.push('--add-dir', ctx.cwd);
+      // Mode -> permission posture.
+      //   plan  : read-only planning, the agent proposes but doesn't act.
+      //   build : the agent must be able to create/edit files and run commands,
+      //           or "chat to build something" (PRD G1) is a dead demo. The
+      //           workspace is the user's own machine, own agent, own API bill
+      //           — the same posture as the PRD's C3 "agent runs with the
+      //           user's permissions" note. This is the Replit/Lovable model.
+      args.push('--permission-mode', ctx.mode === 'plan' ? 'plan' : 'bypassPermissions');
+    }
+    // Prefer the resolved absolute path from detection; fall back to the bare
+    // name. claude ships a native binary, so shell:false spawns cleanly.
+    const command = this.agent.resolvedPath || this.agent.binary;
+    this.proc = spawn(command, args, {
+      cwd: ctx.cwd || this.opts.cwd || process.cwd(),
+      env: { ...process.env, ...(ctx.env || {}) },
+      shell: false,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    this.proc.stdout.setEncoding('utf8');
+    this.proc.stderr.setEncoding('utf8');
+
+    const streamFormat = this.agent.streamFormat || 'text';
+
+    this.proc.stdout.on('data', (chunk) => this._handleStdout(chunk, streamFormat));
+    this.proc.stderr.on('data', (chunk) => this.emit('stderr', chunk));
+    this.proc.on('error', (err) => this.emit('error', err));
+    this.proc.on('close', (code) => {
+      this.emit('end', { code });
+      this.proc = null;
+    });
+
+    try {
+      this.proc.stdin.write(prompt);
+      this.proc.stdin.end();
+    } catch (e) {
+      this.emit('error', e);
+    }
+  }
+
+  _handleStdout(chunk, streamFormat) {
+    if (streamFormat !== 'claude-stream-json') {
+      // Plain-text agents (and the test echo agent) stream straight through.
+      this.emit('chunk', { type: 'text', text: chunk });
+      return;
+    }
+    this._buffer += chunk;
+    const lines = this._buffer.split('\n');
+    this._buffer = lines.pop() || '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let evt;
+      try {
+        evt = JSON.parse(trimmed);
+      } catch {
+        // Non-JSON noise on stdout (rare). Drop it — don't pollute the chat.
+        continue;
+      }
+      this._handleClaudeEvent(evt);
+    }
+  }
+
+  _handleClaudeEvent(evt) {
+    if (!evt || typeof evt !== 'object') return;
+    switch (evt.type) {
+      case 'stream_event':
+        this._sawStreamEvent = true;
+        this._handleStreamEvent(evt.event);
+        return;
+      case 'assistant':
+        // Redundant with stream_event when --include-partial-messages is on
+        // (it always is). Only the fallback path when partials are disabled.
+        if (!this._sawStreamEvent) this._handleAssistantFallback(evt.message);
+        return;
+      case 'user':
+        this._handleToolResults(evt.message);
+        return;
+      case 'result':
+        this._handleResult(evt);
+        return;
+      case 'error':
+        this.emit('chunk', {
+          type: 'error',
+          message: evt.message || evt.error?.message || 'agent error',
+        });
+        return;
+      default:
+        // system, rate_limit_event, anything new — ignored.
+        return;
+    }
+  }
+
+  /** The wrapped Anthropic streaming protocol — our real-time source. */
+  _handleStreamEvent(ev) {
+    if (!ev || typeof ev !== 'object') return;
+    switch (ev.type) {
+      case 'content_block_start': {
+        const cb = ev.content_block || {};
+        if (cb.type === 'tool_use') {
+          // Tool input arrives as input_json_delta fragments — buffer them
+          // until content_block_stop, then emit one complete tool-use chunk.
+          this._blocks.set(ev.index, {
+            kind: 'tool',
+            id: cb.id,
+            name: cb.name,
+            jsonBuf: '',
+          });
+        } else {
+          this._blocks.set(ev.index, { kind: cb.type || 'text' });
+        }
+        return;
+      }
+      case 'content_block_delta': {
+        const d = ev.delta || {};
+        if (d.type === 'text_delta' && d.text) {
+          this.emit('chunk', { type: 'text', text: d.text });
+        } else if (d.type === 'thinking_delta' && d.thinking) {
+          this.emit('chunk', { type: 'thinking', text: d.thinking });
+        } else if (d.type === 'input_json_delta') {
+          const blk = this._blocks.get(ev.index);
+          if (blk && blk.kind === 'tool') blk.jsonBuf += d.partial_json || '';
+        }
+        return;
+      }
+      case 'content_block_stop': {
+        const blk = this._blocks.get(ev.index);
+        if (blk && blk.kind === 'tool') {
+          let input = {};
+          try {
+            input = blk.jsonBuf ? JSON.parse(blk.jsonBuf) : {};
+          } catch {
+            input = { _raw: blk.jsonBuf };
+          }
+          this.emit('chunk', {
+            type: 'tool-use',
+            id: blk.id,
+            name: blk.name,
+            input,
+          });
+        }
+        this._blocks.delete(ev.index);
+        return;
+      }
+      default:
+        // message_start / message_delta / message_stop — no UI effect.
+        return;
+    }
+  }
+
+  /** Fallback for `--include-partial-messages` off: parse the whole message. */
+  _handleAssistantFallback(message) {
+    const content = message?.content;
+    if (typeof content === 'string') {
+      if (content) this.emit('chunk', { type: 'text', text: content });
+      return;
+    }
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type === 'text' && block.text) {
+        this.emit('chunk', { type: 'text', text: block.text });
+      } else if (block.type === 'thinking' && block.thinking) {
+        this.emit('chunk', { type: 'thinking', text: block.thinking });
+      } else if (block.type === 'tool_use') {
+        this.emit('chunk', {
+          type: 'tool-use',
+          id: block.id,
+          name: block.name,
+          input: block.input || {},
+        });
+      }
+    }
+  }
+
+  /** `user` events carry tool_result blocks — match them back to a tool card. */
+  _handleToolResults(message) {
+    const content = message?.content;
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type === 'tool_result') {
+        this.emit('chunk', {
+          type: 'tool-result',
+          id: block.tool_use_id,
+          content: flattenContent(block.content),
+          isError: block.is_error === true,
+        });
+      }
+    }
+  }
+
+  /** The final `result` event — authoritative cost + usage for the turn. */
+  _handleResult(evt) {
+    const u = evt.usage || {};
+    this.emit('chunk', {
+      type: 'usage',
+      usage: {
+        input_tokens: u.input_tokens || 0,
+        output_tokens: u.output_tokens || 0,
+        cache_read_input_tokens: u.cache_read_input_tokens || 0,
+        // cost_usd lives here so the ActivityBus can accumulate it directly.
+        cost_usd: typeof evt.total_cost_usd === 'number' ? evt.total_cost_usd : 0,
+      },
+      durationMs: evt.duration_ms,
+      numTurns: evt.num_turns,
+    });
+    if (evt.is_error || (evt.subtype && evt.subtype !== 'success')) {
+      this.emit('chunk', {
+        type: 'error',
+        message:
+          (typeof evt.result === 'string' && evt.result) ||
+          evt.subtype ||
+          'agent run failed',
+      });
+    }
+  }
+
+  cancel() {
+    if (this.proc && !this.proc.killed) {
+      try {
+        this.proc.kill();
+      } catch {}
+    }
+  }
+
+  close() {
+    this.closed = true;
+    this.cancel();
+  }
+}
+
+export function pickDefaultAgent(detected) {
+  // Prefer claude; fall back to first available; fall back to claude (assume
+  // it'll be installed — the UI shows an install hint when it isn't).
+  const claude = detected.find((a) => a.id === 'claude' && a.available);
+  if (claude) return claude;
+  const anyAvailable = detected.find((a) => a.available);
+  if (anyAvailable) return anyAvailable;
+  return detected[0] || DEFAULT_AGENTS[0];
+}