@1agh/maude 0.29.0 → 0.31.0

package/README.md

@@ -3,10 +3,10 @@
 A personal marketplace of Claude Code plugins. Two plugins today, plus a `maude` CLI for scaffolding and running the bundled dev tooling.
 
 <!-- Demo video lives at https://github.com/1aGh/maude/releases/download/v0.16.0/demo.mp4 once uploaded.
-     Until then the inline tag below stays a soft 404; landing page at https://maude.iagh.cz autoplays the same file. -->
-<video src="https://github.com/1aGh/maude/releases/download/v0.16.0/demo.mp4" controls muted playsinline poster="https://maude.iagh.cz/demo-poster.jpg" width="800"></video>
+     Until then the inline tag below stays a soft 404; landing page at https://maude.sh autoplays the same file. -->
+<video src="https://github.com/1aGh/maude/releases/download/v0.16.0/demo.mp4" controls muted playsinline poster="https://maude.sh/demo-poster.jpg" width="800"></video>
 
-> **📚 Full docs: https://maude.iagh.cz** (or browse the source under [`site/content/docs/`](./site/content/docs/) until the public URL lands).
+> **📚 Full docs: https://maude.sh** (or browse the source under [`site/content/docs/`](./site/content/docs/) until the public URL lands).
 > Contributing? See [CONTRIBUTING.md](./CONTRIBUTING.md). Security? See [SECURITY.md](./SECURITY.md).
 
 | Plugin | What it does |
@@ -106,17 +106,17 @@ Plugin slash-commands reach all executable logic through the on-PATH `maude` bin
 Two clean paths, no middle ground ([DDR-047](.ai/decisions/DDR-047-collab-scope-cut-no-lan-mode-hub-admin-ui.md)):
 
 - **v1.0 — git handoff OR loopback multi-tab.** Push / pull is the cross-machine story. On a single machine, two browser tabs (or two Claude Code instances editing the same repo) sync cursors, comments, and annotations live over loopback WebSocket. The dev server refuses any non-loopback `host` header on the collab WS endpoint.
-- **v1.1 — deploy a hub** (Phase 9, in-flight). Cross-machine live collab needs a hub binary you deploy yourself. No tunnel mode; no shared cloud.
+- **v1.1 — deploy a hub** (Phase 9, in-flight). Cross-machine live collab needs a hub binary you deploy yourself. No tunnel mode; no shared cloud. **Boot order can't eat your work** ([DDR-102](.ai/decisions/DDR-102-cold-start-divergence-resolution.md)): a per-machine journal tells clean catch-ups apart from genuine divergence; diverged canvases snapshot **both** versions to `_history/` before the newer one wins, so the loser is one `/design:rollback` away — and `maude design status` reports per-canvas sync state honestly (synced / pending / auth-rejected).
 
 ## Security
 
-Solo mode (the default) is fully local — no accounts, no telemetry, no network trust surface, and the canvas sandbox is on by default. Linked (hub) mode is opt-in and carries a documented trust model with disclosed, bounded residuals (hub-pushed content is treated as untrusted input). The full account — what runs where, what the canvas sandbox does and doesn't close, `.tsx` sync's double opt-in, untrusted-context handling — is at [`/docs/security`](https://maude.iagh.cz/docs/security) (source: [`site/content/docs/security.mdx`](./site/content/docs/security.mdx)). To **report** a vulnerability, see [SECURITY.md](./SECURITY.md).
+Solo mode (the default) is fully local — no accounts, no telemetry, no network trust surface, and the canvas sandbox is on by default. Linked (hub) mode is opt-in and carries a documented trust model with disclosed, bounded residuals (hub-pushed content is treated as untrusted input). The full account — what runs where, what the canvas sandbox does and doesn't close, `.tsx` sync's double opt-in, untrusted-context handling — is at [`/docs/security`](https://maude.sh/docs/security) (source: [`site/content/docs/security.mdx`](./site/content/docs/security.mdx)). To **report** a vulnerability, see [SECURITY.md](./SECURITY.md).
 
 ## What's where
 
 User-facing docs live in two places — the README points you the right way:
 
-- **Reference** (every command, every config key, recipes for Next.js / Expo / monorepo) → [`site/content/docs/`](./site/content/docs/) (served at https://maude.iagh.cz once Vercel is wired — see [DDR-005](.ai/decisions/DDR-005-docs-site-stack-and-hosting.md)).
+- **Reference** (every command, every config key, recipes for Next.js / Expo / monorepo) → [`site/content/docs/`](./site/content/docs/) (served at https://maude.sh once Vercel is wired — see [DDR-005](.ai/decisions/DDR-005-docs-site-stack-and-hosting.md)).
 - **Quickstart** + **contributor info** → this README.
 
 The docs site auto-generates per-command pages from `plugins/{flow,design}/commands/*.md` frontmatter and a typed schema reference from `plugins/flow/.claude-plugin/config.schema.json`. Adding a new command → docs update on next build.

package/apps/studio/acp/bridge.ts

@@ -0,0 +1,285 @@
+// Per-connection ACP bridge: spawns the user's Claude Code through the
+// `claude-agent-acp` adapter and drives it as an ACP *client* (DDR-123).
+//
+//   browser ─/_ws/acp─► dev-server (this) ─stdio ndJSON─► claude-agent-acp ─► claude -p
+//
+// We never see or store an Anthropic credential — the spawned `claude` owns its
+// own auth + billing. The single load-bearing guarantee is `scrubAgentEnv`
+// (env.ts): the child inherits the environment MINUS `ANTHROPIC_API_KEY`, so
+// auth precedence falls through to the user's Pro/Max subscription.
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import {
+  type Client,
+  ClientSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type PromptResponse,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type SessionNotification,
+  type SessionUpdate,
+} from '@agentclientprotocol/sdk';
+
+import { scrubAgentEnv } from './env.ts';
+import { resolveAdapterEntry, resolveAgentRuntime, resolveClaudePath } from './probe.ts';
+
+export interface AcpBridgeOptions {
+  /** Absolute repo root the ACP session runs in (where `.design/` + the CLI operate). */
+  repoRoot: string;
+  /** Streamed `session/update` notifications relayed to the browser. */
+  onUpdate: (update: SessionUpdate) => void;
+  /** Informational: a tool permission was auto-approved (transparency for the UI). */
+  onPermission?: (req: RequestPermissionRequest) => void;
+}
+
+type Spawned = ReturnType<typeof Bun.spawn>;
+
+/**
+ * Effort → extended-thinking budget, fed to the adapter as `MAX_THINKING_TOKENS`
+ * (it maps 0 → thinking disabled, a positive int → an enabled budget). `balanced`
+ * leaves it unset so the agent uses Claude Code's own default.
+ */
+const EFFORT_THINKING_TOKENS: Record<string, number | null> = {
+  fast: 0,
+  balanced: null,
+  thorough: 31999,
+};
+
+export type AcpEffort = keyof typeof EFFORT_THINKING_TOKENS;
+
+/** Pick the most-permissive allow option, or null if the agent offered none. */
+function pickAllowOption(params: RequestPermissionRequest) {
+  const options = params.options ?? [];
+  return (
+    options.find((o) => o.kind === 'allow_always') ??
+    options.find((o) => o.kind === 'allow_once') ??
+    options.find((o) => typeof o.kind === 'string' && o.kind.startsWith('allow')) ??
+    null
+  );
+}
+
+export class AcpBridge {
+  private proc: Spawned | null = null;
+  private conn: ClientSideConnection | null = null;
+  // One ACP session per chat id (repo-level), so each chat keeps its own claude
+  // context. The adapter (one subprocess) holds them all; switching chats reuses
+  // the session, so claude remembers that chat while the app is open.
+  private sessions = new Map<string, string>(); // chatId → sessionId
+  private currentSession: string | null = null; // the in-flight prompt's session
+  private starting: Promise<void> | null = null;
+  /** Per-chat transcript file (`_chat/<id>.jsonl`); set per prompt. */
+  private transcriptPath: string | null = null;
+  // Model + effort are env-at-spawn (ANTHROPIC_MODEL / MAX_THINKING_TOKENS), so a
+  // change re-spawns the adapter. `desired*` is what the UI asked for; `active*`
+  // is what the running session was spawned with.
+  private desiredModel: string | null = null;
+  private desiredEffort: AcpEffort = 'balanced';
+  private activeModel: string | null = null;
+  private activeEffort: AcpEffort = 'balanced';
+
+  constructor(private readonly opts: AcpBridgeOptions) {}
+
+  /** The session id of the most recent prompt (for the `connected` frame). */
+  get sessionId(): string | null {
+    return this.currentSession;
+  }
+
+  get connected(): boolean {
+    return this.conn !== null && this.proc !== null;
+  }
+
+  setTranscriptPath(path: string | null): void {
+    this.transcriptPath = path;
+  }
+
+  /** Desired model (alias/id, or null for the user's default) + effort. Applied
+   *  on the next prompt — re-spawning the adapter only if it actually changed. */
+  setConfig(model: string | null, effort: AcpEffort): void {
+    this.desiredModel = model;
+    this.desiredEffort = effort in EFFORT_THINKING_TOKENS ? effort : 'balanced';
+  }
+
+  private configChanged(): boolean {
+    return this.desiredModel !== this.activeModel || this.desiredEffort !== this.activeEffort;
+  }
+
+  /** Spawn + handshake exactly once; concurrent callers share the same promise. */
+  async ensureStarted(): Promise<void> {
+    if (this.conn) return;
+    if (!this.starting) {
+      this.starting = this.start().finally(() => {
+        this.starting = null;
+      });
+    }
+    return this.starting;
+  }
+
+  /** Get-or-create the ACP session for a chat id (one claude context per chat). */
+  private async sessionFor(chatId: string): Promise<string> {
+    const existing = this.sessions.get(chatId);
+    if (existing) return existing;
+    if (!this.conn) throw new Error('ACP adapter not started');
+    const created = await this.conn.newSession({ cwd: this.opts.repoRoot, mcpServers: [] });
+    this.sessions.set(chatId, created.sessionId);
+    return created.sessionId;
+  }
+
+  private async start(): Promise<void> {
+    const adapterEntry = resolveAdapterEntry();
+    if (!adapterEntry) {
+      throw new Error('The Claude agent bridge is not installed in this build.');
+    }
+    if (!resolveClaudePath()) {
+      throw new Error("Claude Code isn't connected — run `claude` in a terminal and `/login`.");
+    }
+
+    // DDR-123 guardrail #1 — strip ANTHROPIC_API_KEY so the child stays on the
+    // user's subscription. This is the whole compliance story; do not weaken it.
+    const env = scrubAgentEnv(process.env);
+    // Model + effort selection — config, NOT credentials, so they're added back.
+    this.activeModel = this.desiredModel;
+    this.activeEffort = this.desiredEffort;
+    if (this.activeModel) env.ANTHROPIC_MODEL = this.activeModel;
+    const thinking = EFFORT_THINKING_TOKENS[this.activeEffort];
+    if (thinking !== null && thinking !== undefined) env.MAX_THINKING_TOKENS = String(thinking);
+
+    const proc = Bun.spawn([resolveAgentRuntime(), adapterEntry], {
+      cwd: this.opts.repoRoot,
+      env,
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    this.proc = proc;
+    void this.drainStderr(proc.stderr);
+
+    // Bun's `proc.stdin` is a FileSink, not a WritableStream — wrap it so
+    // ndJsonStream can pipe encoded ACP frames into the child's stdin.
+    const toChild = new WritableStream<Uint8Array>({
+      write: (chunk) => {
+        proc.stdin.write(chunk);
+        proc.stdin.flush();
+      },
+      close: () => {
+        try {
+          proc.stdin.end();
+        } catch {
+          /* already gone */
+        }
+      },
+      abort: () => {
+        try {
+          proc.stdin.end();
+        } catch {
+          /* already gone */
+        }
+      },
+    });
+    const stream = ndJsonStream(toChild, proc.stdout as ReadableStream<Uint8Array>);
+
+    const client: Client = {
+      sessionUpdate: (params: SessionNotification) => {
+        this.opts.onUpdate(params.update);
+        void this.appendTranscript({ role: 'agent', update: params.update });
+      },
+      requestPermission: (params: RequestPermissionRequest): RequestPermissionResponse => {
+        // Auto-approve: the agent is the user's OWN local Claude editing their
+        // OWN project over loopback — granting it is the feature, mirroring
+        // Claude Code's trusted-session default. A manual approve/deny UI is a
+        // Task-3 follow-up; we surface the request so the panel can show it.
+        this.opts.onPermission?.(params);
+        const option = pickAllowOption(params);
+        if (!option) return { outcome: { outcome: 'cancelled' } };
+        return { outcome: { outcome: 'selected', optionId: option.optionId } };
+      },
+    };
+
+    const conn = new ClientSideConnection(() => client, stream);
+    this.conn = conn;
+
+    await conn.initialize({
+      protocolVersion: PROTOCOL_VERSION,
+      // We don't expose the project filesystem to the agent over ACP — the
+      // spawned `claude` already has direct disk access to `cwd`, so advertising
+      // fs capabilities here would only duplicate (and widen) that surface.
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+    });
+    // Sessions are created lazily per chat (sessionFor) — not here.
+  }
+
+  /** Send a user turn for `chatId` and resolve when it completes. */
+  async prompt(
+    text: string,
+    chatId: string
+  ): Promise<{ stopReason: PromptResponse['stopReason'] }> {
+    // Model/effort are env-at-spawn — if the user changed them, tear the adapter
+    // down so ensureStarted re-spawns with the new env (sessions re-create lazily).
+    if (this.conn && this.configChanged()) {
+      await this.stop();
+    }
+    await this.ensureStarted();
+    const conn = this.conn;
+    if (!conn) throw new Error('ACP adapter not ready');
+    const sessionId = await this.sessionFor(chatId);
+    this.currentSession = sessionId;
+
+    await this.appendTranscript({ role: 'user', text });
+    const response = await conn.prompt({
+      sessionId,
+      prompt: [{ type: 'text', text }],
+    });
+    await this.appendTranscript({ role: 'stop', stopReason: response.stopReason });
+    return { stopReason: response.stopReason };
+  }
+
+  /** Cancel the in-flight turn (no-op if nothing is running). */
+  async cancel(): Promise<void> {
+    if (this.conn && this.currentSession) {
+      try {
+        await this.conn.cancel({ sessionId: this.currentSession });
+      } catch {
+        /* turn may already have finished */
+      }
+    }
+  }
+
+  /** Tear down: cancel, kill the subprocess, drop all handles + sessions. */
+  async stop(): Promise<void> {
+    await this.cancel();
+    try {
+      this.proc?.kill();
+    } catch {
+      /* already dead */
+    }
+    this.proc = null;
+    this.conn = null;
+    this.sessions.clear();
+    this.currentSession = null;
+  }
+
+  private async drainStderr(stderr: ReadableStream<Uint8Array>): Promise<void> {
+    try {
+      const decoder = new TextDecoder();
+      for await (const chunk of stderr) {
+        const line = decoder.decode(chunk).trimEnd();
+        if (line) console.error('[acp-adapter]', line);
+      }
+    } catch {
+      /* stream closed on teardown */
+    }
+  }
+
+  private async appendTranscript(entry: Record<string, unknown>): Promise<void> {
+    const path = this.transcriptPath;
+    if (!path) return;
+    try {
+      await mkdir(dirname(path), { recursive: true });
+      await appendFile(path, `${JSON.stringify({ ts: Date.now(), ...entry })}\n`);
+    } catch {
+      /* transcript is best-effort; never block the chat on disk errors */
+    }
+  }
+}

package/apps/studio/acp/env.ts

@@ -0,0 +1,48 @@
+// DDR-123 guardrail #1 — keep the spawned Claude Code adapter on the user's
+// Pro/Max SUBSCRIPTION, never metered API billing.
+//
+// Anthropic's auth precedence puts `ANTHROPIC_API_KEY` (#3, API billing) ABOVE
+// the subscription OAuth from `/login` (#6, the Pro/Max default). A stray global
+// key in the inherited environment would therefore silently switch the user to
+// API billing the moment the adapter spawns `claude -p`. We delete it (and the
+// equivalent auth-token override) from the child env before spawning. This is
+// the single load-bearing detail that makes the whole panel subscription-correct
+// — the guarantee lives here, at the bottom of the stack, independent of the UI.
+
+/**
+ * Env var names that flip Claude Code off the subscription and onto metered API
+ * billing (or a non-subscription auth token). The two precedence-relevant keys.
+ */
+export const SUBSCRIPTION_SCRUBBED_ENV_KEYS = [
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+] as const;
+
+/**
+ * Scrub the WHOLE provider/billing namespace, not just the two known keys —
+ * any `ANTHROPIC_*` (API key, auth token, custom `ANTHROPIC_BASE_URL`, Bedrock/
+ * Vertex base URLs, future billing vars) plus the cloud-provider toggles. This
+ * closes the denylist gap (security review F1): a stray base-URL or a NEW billing
+ * env var can't silently redirect the spawned `claude` off the user's
+ * subscription or exfiltrate prompts to an attacker endpoint. `ANTHROPIC_MODEL`
+ * is in this set too — the bridge re-adds it AFTER the scrub, from a validated
+ * allowlist value, so the parent's value never leaks through.
+ */
+const PROVIDER_REDIRECT_RE = /^(ANTHROPIC_|CLAUDE_CODE_USE_|AWS_BEARER_TOKEN_BEDROCK)/i;
+
+/**
+ * Return a copy of `source` with the billing/provider-redirect keys removed and
+ * any `undefined` values dropped (Bun.spawn's `env` wants Record<string,string>).
+ * Pure — never mutates the input, so `process.env` stays intact for the parent.
+ */
+export function scrubAgentEnv(
+  source: Record<string, string | undefined> = process.env
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    if (PROVIDER_REDIRECT_RE.test(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}

package/apps/studio/acp/index.ts

@@ -0,0 +1,132 @@
+// ACP manager: owns one AcpBridge per `/_ws/acp` socket and translates the
+// browser's JSON chat protocol to/from the ACP client. Wired into ws.ts (the
+// `acp` socket kind) and server.ts (the main-origin, loopback-guarded upgrade).
+// NEVER exposed on the canvas origin (DDR-054/DDR-123) — the untrusted iframe
+// must not reach the agent bridge.
+
+import { join } from 'node:path';
+
+import type { ServerWebSocket } from 'bun';
+
+import type { Context } from '../context.ts';
+import type { WsData } from '../ws.ts';
+import { AcpBridge, type AcpEffort } from './bridge.ts';
+import { probeAcpAvailability } from './probe.ts';
+
+const VALID_EFFORT = new Set(['fast', 'balanced', 'thorough']);
+// Model is set as ANTHROPIC_MODEL on the spawned child — allowlist it server-side
+// (security review F1) so the loopback WS frame can't pin an arbitrary value.
+const VALID_MODELS = new Set(['opus', 'sonnet', 'haiku']);
+
+/**
+ * Browser → server frames: `{ t: 'prompt', text, canvas? }`, `{ t: 'cancel' }`.
+ * Server → browser frames: `ready` (availability on open), `connected` (session
+ * live), `update` (each streamed session/update), `turn-end`, `permission`,
+ * `error`.
+ */
+export interface Acp {
+  onOpen(ws: ServerWebSocket<WsData>): void;
+  onMessage(ws: ServerWebSocket<WsData>, raw: string | Uint8Array): void;
+  onClose(ws: ServerWebSocket<WsData>): void;
+  /** Live bridge count — for diagnostics / teardown assertions. */
+  size(): number;
+}
+
+export function createAcp(ctx: Context): Acp {
+  const bridges = new Map<string, AcpBridge>();
+
+  function send(ws: ServerWebSocket<WsData>, payload: unknown): void {
+    try {
+      ws.send(JSON.stringify(payload));
+    } catch {
+      /* dead socket — close handler cleans up */
+    }
+  }
+
+  // Chats are repo-level (NOT per-canvas) — `_chat/<chatId>.jsonl`. The id is
+  // client-generated; sanitize it to a safe filename.
+  function sanitizeChatId(id: string): string {
+    const safe = id.replace(/[^a-z0-9_-]/gi, '').slice(0, 64);
+    return safe || 'default';
+  }
+  function transcriptPathFor(chatId: string): string {
+    return join(ctx.paths.designRoot, '_chat', `${sanitizeChatId(chatId)}.jsonl`);
+  }
+
+  async function handlePrompt(
+    ws: ServerWebSocket<WsData>,
+    text: string,
+    chatId: string,
+    model: string | null,
+    effort: AcpEffort
+  ): Promise<void> {
+    let bridge = bridges.get(ws.data.id);
+    if (!bridge) {
+      bridge = new AcpBridge({
+        repoRoot: ctx.paths.repoRoot,
+        onUpdate: (update) => send(ws, { t: 'update', update }),
+        onPermission: (req) => send(ws, { t: 'permission', toolCall: req.toolCall }),
+      });
+      bridges.set(ws.data.id, bridge);
+    }
+    bridge.setTranscriptPath(transcriptPathFor(chatId));
+    bridge.setConfig(model, effort);
+    try {
+      await bridge.ensureStarted();
+      const { stopReason } = await bridge.prompt(text, sanitizeChatId(chatId));
+      send(ws, { t: 'connected', sessionId: bridge.sessionId });
+      send(ws, { t: 'turn-end', stopReason });
+    } catch (err) {
+      send(ws, { t: 'error', message: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  return {
+    onOpen(ws) {
+      const probe = probeAcpAvailability();
+      send(ws, { t: 'ready', available: probe.available, reason: probe.reason });
+    },
+
+    onMessage(ws, raw) {
+      let msg: unknown;
+      try {
+        msg = JSON.parse(typeof raw === 'string' ? raw : new TextDecoder().decode(raw));
+      } catch {
+        return;
+      }
+      if (!msg || typeof msg !== 'object') return;
+      const frame = msg as {
+        t?: unknown;
+        text?: unknown;
+        chat?: unknown;
+        model?: unknown;
+        effort?: unknown;
+      };
+
+      if (frame.t === 'prompt' && typeof frame.text === 'string') {
+        const chatId = typeof frame.chat === 'string' && frame.chat ? frame.chat : 'default';
+        const model =
+          typeof frame.model === 'string' && VALID_MODELS.has(frame.model) ? frame.model : null;
+        const effort: AcpEffort =
+          typeof frame.effort === 'string' && VALID_EFFORT.has(frame.effort)
+            ? (frame.effort as AcpEffort)
+            : 'balanced';
+        void handlePrompt(ws, frame.text, chatId, model, effort);
+      } else if (frame.t === 'cancel') {
+        void bridges.get(ws.data.id)?.cancel();
+      }
+    },
+
+    onClose(ws) {
+      const bridge = bridges.get(ws.data.id);
+      if (bridge) {
+        bridges.delete(ws.data.id);
+        void bridge.stop();
+      }
+    },
+
+    size() {
+      return bridges.size;
+    },
+  };
+}

package/apps/studio/acp/probe.ts

@@ -0,0 +1,112 @@
+// Detection layer for the ACP chat bridge: where is the spawnable
+// `claude-agent-acp` adapter, is the user's `claude` CLI installed, and which JS
+// runtime should run the adapter. All disk paths resolve through DEV_SERVER_ROOT
+// (DDR-045) — never `dirname(import.meta.url)`, which is the virtual `/$bunfs`
+// path inside a compiled binary. Per DDR-123 the panel is native-app only; the
+// native shell ships the apps/studio source tree (with node_modules), so the
+// adapter resolves on disk there.
+
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { DEV_SERVER_ROOT } from '../paths.ts';
+
+/** Adapter npm package — the renamed continuation of `@zed-industries/claude-code-acp`. */
+const ADAPTER_PKG = '@agentclientprotocol/claude-agent-acp';
+const ADAPTER_BIN_NAME = 'claude-agent-acp';
+
+export interface AcpAvailability {
+  /** True when both the adapter entry and a `claude` CLI are resolvable. */
+  available: boolean;
+  /** Human-readable reason when `available` is false (drives the not-connected UI). */
+  reason?: string;
+  /** Absolute path to the adapter entry JS, or null. */
+  adapterEntry: string | null;
+  /** Absolute path to the `claude` CLI, or null. */
+  claudePath: string | null;
+}
+
+/**
+ * Resolve the adapter's spawnable entry script (its `bin`), trying:
+ *   1. `MAUDE_ACP_ADAPTER_ENTRY` override (tests + escape hatch).
+ *   2. The package's own `package.json` `bin` field, joined to its dir.
+ *   3. The pnpm `.bin/<name>` symlink, dereferenced to the real file.
+ * Returns an absolute path or null.
+ */
+export function resolveAdapterEntry(): string | null {
+  const override = process.env.MAUDE_ACP_ADAPTER_ENTRY;
+  if (override) return existsSync(override) ? override : null;
+
+  // (2) Locate the installed package via its package.json, read the bin map.
+  try {
+    const pkgJsonPath = Bun.resolveSync(`${ADAPTER_PKG}/package.json`, DEV_SERVER_ROOT);
+    const pkgDir = dirname(pkgJsonPath);
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) as {
+      bin?: string | Record<string, string>;
+    };
+    const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[ADAPTER_BIN_NAME];
+    if (binRel) {
+      const entry = join(pkgDir, binRel);
+      if (existsSync(entry)) return entry;
+    }
+  } catch {
+    /* fall through to the symlink strategy */
+  }
+
+  // (3) The pnpm-linked bin symlink in the dev-server's own node_modules.
+  try {
+    const sym = join(DEV_SERVER_ROOT, 'node_modules', '.bin', ADAPTER_BIN_NAME);
+    if (existsSync(sym)) return realpathSync(sym);
+  } catch {
+    /* not present */
+  }
+
+  return null;
+}
+
+/**
+ * Absolute path to the user's installed `claude` CLI, or null. Honors a
+ * `MAUDE_CLAUDE_BIN` override; otherwise looks it up on PATH.
+ */
+export function resolveClaudePath(): string | null {
+  const override = process.env.MAUDE_CLAUDE_BIN;
+  if (override) return existsSync(override) ? override : null;
+  return Bun.which('claude');
+}
+
+/**
+ * The JS runtime used to launch the adapter. The dev-server already runs under
+ * Bun, so `process.execPath` is always available; prefer a real `node` when
+ * present (the adapter + `@anthropic-ai/claude-agent-sdk` are authored for Node)
+ * and fall back to our own Bun. Overridable via `MAUDE_ACP_RUNTIME`.
+ */
+export function resolveAgentRuntime(): string {
+  return process.env.MAUDE_ACP_RUNTIME || Bun.which('node') || process.execPath;
+}
+
+/**
+ * Cheap, side-effect-free readiness probe (no subprocess spawned) backing
+ * `GET /_api/acp/status` and the WS `ready` frame. The actual ACP session spins
+ * up lazily on the first prompt.
+ */
+export function probeAcpAvailability(): AcpAvailability {
+  const adapterEntry = resolveAdapterEntry();
+  const claudePath = resolveClaudePath();
+  if (!adapterEntry) {
+    return {
+      available: false,
+      reason: 'The Claude agent bridge is not installed in this build.',
+      adapterEntry: null,
+      claudePath,
+    };
+  }
+  if (!claudePath) {
+    return {
+      available: false,
+      reason: "Claude Code isn't connected — run `claude` in a terminal and `/login`.",
+      adapterEntry,
+      claudePath: null,
+    };
+  }
+  return { available: true, adapterEntry, claudePath };
+}