@1agh/maude 0.31.0 → 0.32.1

package/apps/studio/dist/styles.css

@@ -8000,6 +8000,70 @@
     margin-top: 2px;
   }
 
+  .ob-readiness {
+    max-width: 560px;
+    margin: var(--space-3) 0 0;
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-sm);
+    background: var(--bg-1);
+    text-align: left;
+  }
+
+  .ob-readiness-sum {
+    align-items: center;
+    gap: var(--space-2);
+    padding: var(--space-3);
+    cursor: pointer;
+    font-size: var(--type-sm);
+    color: var(--fg-1);
+    list-style: none;
+    display: flex;
+  }
+
+  .ob-readiness-sum::-webkit-details-marker {
+    display: none;
+  }
+
+  .ob-readiness-dot {
+    border-radius: 50%;
+    flex: none;
+    width: 8px;
+    height: 8px;
+  }
+
+  .ob-readiness-dot--ok {
+    background: var(--status-success);
+  }
+
+  .ob-readiness-dot--warn {
+    background: var(--status-warning, var(--status-info));
+  }
+
+  .ob-readiness-lede {
+    color: var(--fg-0);
+    font-weight: 600;
+  }
+
+  .ob-readiness-hint {
+    color: var(--fg-3);
+    font-size: var(--type-xs);
+    margin-left: auto;
+  }
+
+  .ob-readiness-body {
+    padding: 0 var(--space-3) var(--space-3);
+    gap: var(--space-3);
+    flex-direction: column;
+    display: flex;
+  }
+
+  .ob-readiness-note {
+    color: var(--fg-2);
+    font-size: var(--type-xs);
+    line-height: var(--lh-md);
+    margin: 0;
+  }
+
   .ob-create {
     align-items: center;
     gap: var(--space-4);
@@ -12029,6 +12093,128 @@
       animation: none;
     }
   }
+
+  .rdy {
+    gap: var(--space-3);
+    flex-direction: column;
+    display: flex;
+  }
+
+  .rdy-list {
+    gap: var(--space-2);
+    flex-direction: column;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    display: flex;
+  }
+
+  .rdy-row {
+    gap: var(--space-2);
+    padding: var(--space-2) var(--space-3);
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-sm);
+    background: var(--bg-2);
+    text-align: left;
+    align-items: flex-start;
+    display: flex;
+  }
+
+  .rdy-ic {
+    flex-shrink: 0;
+    margin-top: 1px;
+  }
+
+  .rdy-row--present .rdy-ic {
+    color: var(--status-success);
+  }
+
+  .rdy-row--missing .rdy-ic {
+    color: var(--status-error);
+  }
+
+  .rdy-row--unknown .rdy-ic {
+    color: var(--status-info);
+  }
+
+  .rdy-row--opt.rdy-row--missing .rdy-ic {
+    color: var(--fg-3);
+  }
+
+  .rdy-tx {
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
+    display: flex;
+  }
+
+  .rdy-label {
+    font-size: var(--type-sm);
+    color: var(--fg-0);
+    font-weight: 600;
+  }
+
+  .rdy-detail {
+    font-size: var(--type-xs);
+    color: var(--fg-2);
+    line-height: var(--lh-xs);
+  }
+
+  .rdy-fix {
+    margin-top: var(--space-2);
+    gap: var(--space-2);
+    font-size: var(--type-xs);
+    color: var(--fg-1);
+    line-height: var(--lh-xs);
+    align-items: flex-start;
+    display: flex;
+  }
+
+  .rdy-fix-tx {
+    min-width: 0;
+  }
+
+  .rdy code {
+    font-family: var(--font-mono);
+    font-size: var(--type-xs);
+    color: var(--fg-0);
+    background: var(--bg-3);
+    border-radius: var(--radius-xs);
+    overflow-wrap: anywhere;
+    padding: 1px 5px;
+  }
+
+  .rdy-copy {
+    cursor: pointer;
+    font-size: var(--type-xs);
+    color: var(--fg-2);
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-xs);
+    background: none;
+    flex-shrink: 0;
+    padding: 1px 6px;
+  }
+
+  .rdy-copy:hover {
+    color: var(--fg-0);
+    background: var(--bg-3);
+  }
+
+  .rdy-foot {
+    justify-content: flex-end;
+    display: flex;
+  }
+
+  .rdy-modal {
+    max-width: 520px;
+  }
+
+  .rdy-modal-note {
+    margin: 0 0 var(--space-3);
+    color: var(--fg-2);
+    font-size: var(--type-sm);
+    line-height: var(--lh-md);
+  }
 }
 
 @layer utilities;

package/apps/studio/http.ts

@@ -24,6 +24,7 @@ import { createGitHubEndpoints } from './github/endpoints.ts';
 import type { Inspect } from './inspect.ts';
 import { canvasSlug, writeLocator } from './locator.ts';
 import { DEV_SERVER_ROOT } from './paths.ts';
+import { probeReadiness } from './readiness.ts';
 import { getRuntimeBundle, packageForSlug } from './runtime-bundle.ts';
 import { linkHub } from './sync/hub-link.ts';
 import { loadWhatsNew } from './whats-new.ts';
@@ -570,6 +571,20 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActiv
     '/_api/acp/status': () =>
       Response.json(probeAcpAvailability(), { headers: { 'Cache-Control': 'no-store' } }),
 
+    // DDR-128 — first-open AI-editing readiness. Read-only probe of the AI-editing
+    // dependency chain (claude CLI · maude CLI · maude marketplace + plugins in the
+    // paired Claude Code · optional agent-browser) with per-item remediation; it
+    // installs/mutates nothing. MAIN-ORIGIN ONLY — absent from CANVAS_SAFE_API +
+    // startCanvasServer routes, so the untrusted canvas iframe is 403'd. The probe
+    // can shell out (login-shell fallback), so a cross-origin Origin-reject also
+    // fronts it — a drive-by page can't fire the loopback endpoint to spawn-storm
+    // the dev-server (DDR-128 hardening). The onboarding readiness card + the
+    // ChatPanel not-connected explainer + the Help-menu modal read this.
+    '/_api/preflight': async (req: Request) => {
+      if (!sameOriginWrite(req)) return new Response('cross-origin rejected', { status: 403 });
+      return Response.json(await probeReadiness(), { headers: { 'Cache-Control': 'no-store' } });
+    },
+
     // Phase 31 (DDR-123) — `/design:chat` focus hook. `maude design chat-open`
     // POSTs here; we emit a bus event the shell turns into "open the Assistant
     // panel" (app.jsx, native-only). MAIN-ORIGIN ONLY (off the canvas allowlist).

package/apps/studio/readiness.ts

@@ -0,0 +1,238 @@
+// First-open AI-editing readiness probe (DDR-128). Backs `GET /_api/preflight`.
+//
+// Read-only: it reports which pieces of the AI-editing chain are present — the
+// `claude` CLI, the `maude` CLI, the maude marketplace + plugins registered in the
+// paired Claude Code, and the optional `agent-browser` — with per-item remediation.
+// It NEVER installs, links, or mutates anything (DDR-128 detect-and-guide posture).
+//
+// PATH accuracy: in the packaged `.app` the sidecar's PATH is corrected at the Rust
+// boundary (apps/desktop/.../sidecar.rs, DDR-128), so `Bun.which` is accurate here;
+// `resolveOnPath` keeps a login-shell fallback as defense-in-depth for an unusual
+// shell config the Rust resolution missed. Under `maude design serve` the terminal
+// PATH is already correct.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { resolveAdapterEntry, resolveClaudePath } from './acp/probe.ts';
+
+export type ReadinessStatus = 'present' | 'missing' | 'unknown';
+
+export interface ReadinessItem {
+  id: 'claude' | 'maude' | 'plugins' | 'agent-browser' | 'adapter';
+  /** Short human label for the row. */
+  label: string;
+  /** Required items gate `ready`; optional ones never block it. */
+  required: boolean;
+  status: ReadinessStatus;
+  /** One-line current-state description. */
+  detail: string;
+  /** Copy-paste-able fix, present only when the item is not satisfied. */
+  remediation?: string;
+}
+
+export interface ReadinessReport {
+  /** True when every REQUIRED item is `present`. */
+  ready: boolean;
+  items: ReadinessItem[];
+}
+
+/**
+ * Resolve a binary on PATH. `Bun.which` first (accurate once the sidecar PATH is
+ * Rust-corrected, and always correct under a terminal launch); a login-shell
+ * fallback recovers a binary the app env can't see when the Rust resolution missed.
+ * Unix-only fallback (Windows GUI apps inherit the user PATH). Returns an absolute
+ * path or null. `bin` is always a hardcoded literal — never user input.
+ *
+ * Async + `Bun.spawn` (not `spawnSync`): the fallback shells out for up to 5 s, so a
+ * synchronous spawn would block the single-threaded dev-server event loop for the
+ * whole probe — a real freeze on a fresh machine where the binary is missing
+ * (DDR-128 hardening, ethical-hacker F1). Awaiting yields the loop; the 5 s kill
+ * bounds a misconfigured rc.
+ */
+export async function resolveOnPath(bin: string): Promise<string | null> {
+  const direct = Bun.which(bin);
+  if (direct) return direct;
+  if (process.platform === 'win32') return null;
+  try {
+    const shell = process.env.SHELL || '/bin/sh';
+    const proc = Bun.spawn([shell, '-ilc', `command -v ${bin} 2>/dev/null`], {
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    const killer = setTimeout(() => {
+      try {
+        proc.kill(9);
+      } catch {
+        /* already gone */
+      }
+    }, 5000);
+    let out: string;
+    try {
+      out = await new Response(proc.stdout).text();
+    } finally {
+      clearTimeout(killer);
+    }
+    // Instant-prompt frameworks (powerlevel10k) can print to stdout on interactive
+    // start, so take the last line that is an absolute path to a real file.
+    const hit = out
+      .split('\n')
+      .map((l) => l.trim())
+      .reverse()
+      .find((l) => l.startsWith('/') && existsSync(l));
+    return hit ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Claude Code's config dir — relocatable via `CLAUDE_CONFIG_DIR` (its own contract). */
+function claudeConfigDir(): string {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}
+
+function readJson<T = unknown>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+}
+
+interface PluginScan {
+  /** 'unknown' when the registry couldn't be read (Claude Code's internal contract). */
+  status: 'present' | 'unknown';
+  marketplace: boolean;
+  design: boolean;
+  flow: boolean;
+}
+
+/**
+ * Read-only scan of Claude Code's plugin registry for the maude marketplace
+ * (`repo: 1aGh/maude`) and the `design@maude` / `flow@maude` plugins. `readFileSync`
+ * follows symlinks (a dev's `~/.claude` is symlinked into Dotfiles). Never writes,
+ * never throws — an unrecognized layout yields `status: 'unknown'`.
+ */
+function scanPlugins(): PluginScan {
+  const dir = claudeConfigDir();
+  const markets = readJson<Record<string, { source?: { repo?: string } }>>(
+    join(dir, 'plugins', 'known_marketplaces.json')
+  );
+  const installed = readJson<{ plugins?: Record<string, unknown> }>(
+    join(dir, 'plugins', 'installed_plugins.json')
+  );
+  if (!markets && !installed) {
+    return { status: 'unknown', marketplace: false, design: false, flow: false };
+  }
+  const marketplace =
+    !!markets &&
+    Object.values(markets).some(
+      (m) => String(m?.source?.repo ?? '').toLowerCase() === '1agh/maude'
+    );
+  const plugins = installed?.plugins ?? {};
+  const has = (key: string): boolean => {
+    const v = plugins[key];
+    return Array.isArray(v) ? v.length > 0 : !!v;
+  };
+  return { status: 'present', marketplace, design: has('design@maude'), flow: has('flow@maude') };
+}
+
+/**
+ * Side-effect-free readiness report. The three binary probes run concurrently so a
+ * fresh machine (where the login-shell fallback fires) resolves in ~one shell round
+ * trip, not three sequential ones. The backing route gates cross-origin callers
+ * (DDR-128 hardening) so this can't be turned into a spawn-storm from a drive-by page.
+ */
+export async function probeReadiness(): Promise<ReadinessReport> {
+  const [claude, maude, agentBrowser] = await Promise.all([
+    (async () => resolveClaudePath() ?? (await resolveOnPath('claude')))(),
+    resolveOnPath('maude'),
+    resolveOnPath('agent-browser'),
+  ]);
+
+  const items: ReadinessItem[] = [];
+
+  items.push({
+    id: 'claude',
+    label: 'Claude Code (the `claude` CLI)',
+    required: true,
+    status: claude ? 'present' : 'missing',
+    detail: claude
+      ? 'Installed — AI editing drives it on your own Pro/Max subscription.'
+      : 'Not found on PATH.',
+    remediation: claude
+      ? undefined
+      : 'Install Claude Code, then run `claude` and `/login` once. AI editing runs on your own Pro/Max subscription — never API billing.',
+  });
+
+  items.push({
+    id: 'maude',
+    label: 'maude CLI',
+    required: true,
+    status: maude ? 'present' : 'missing',
+    detail: maude ? 'On PATH — `/design:edit` can reach its helpers.' : 'Not found on PATH.',
+    remediation: maude
+      ? undefined
+      : 'Install it: `npm i -g @1agh/maude`. `/design:edit` shells out to `maude design …`, so it must be on PATH.',
+  });
+
+  const scan = scanPlugins();
+  const pluginsPresent = scan.design && scan.flow;
+  const pluginStatus: ReadinessStatus =
+    scan.status === 'unknown' ? 'unknown' : pluginsPresent ? 'present' : 'missing';
+  const missing = [!scan.design && 'design@maude', !scan.flow && 'flow@maude']
+    .filter(Boolean)
+    .join(' + ');
+  items.push({
+    id: 'plugins',
+    label: 'Maude plugins in Claude Code',
+    required: true,
+    status: pluginStatus,
+    detail:
+      scan.status === 'unknown'
+        ? "Couldn't read Claude Code's plugin registry — check it manually."
+        : pluginsPresent
+          ? 'design@maude + flow@maude are installed.'
+          : `Missing: ${missing}${scan.marketplace ? '' : ' (and the maude marketplace)'}.`,
+    remediation:
+      pluginStatus === 'present'
+        ? undefined
+        : 'In Claude Code: `/plugin marketplace add 1aGh/maude`, then `/plugin install design@maude` and `/plugin install flow@maude`.',
+  });
+
+  items.push({
+    id: 'agent-browser',
+    label: 'agent-browser (optional)',
+    required: false,
+    status: agentBrowser ? 'present' : 'missing',
+    detail: agentBrowser
+      ? 'Installed — screenshot evidence during edits.'
+      : 'Optional — richer screenshot evidence during edits.',
+    remediation: agentBrowser
+      ? undefined
+      : 'Optional. Install `agent-browser` for screenshot evidence during `/design:edit`.',
+  });
+
+  // The chat bridge itself: the adapter must be resolvable on disk. This is what
+  // actually gates the chat panel (probeAcpAvailability → resolveAdapterEntry),
+  // distinct from the user-environment checks above. Shown so a build that ships
+  // without the staged adapter closure surfaces here instead of leaving every
+  // other row green while chat reports "bridge is not installed" (the v0.31–0.32
+  // desktop bug; see apps/desktop/scripts/stage-resources.mjs).
+  const adapter = resolveAdapterEntry();
+  items.push({
+    id: 'adapter',
+    label: 'Claude agent bridge',
+    required: true,
+    status: adapter ? 'present' : 'missing',
+    detail: adapter ? 'Bundled — the chat panel can spawn it.' : 'Not bundled in this build.',
+    remediation: adapter
+      ? undefined
+      : 'The Claude agent bridge is missing from this build — reinstall or update Maude. If you built it yourself, ensure the desktop staging step bundled `@agentclientprotocol/claude-agent-acp`.',
+  });
+
+  const ready = items.filter((i) => i.required).every((i) => i.status === 'present');
+  return { ready, items };
+}

package/apps/studio/test/acp-bridge.test.ts

@@ -41,6 +41,10 @@ describe('AcpBridge — round-trip + subscription guardrail', () => {
       const streamed = JSON.stringify(updates);
       expect(streamed).toContain('apiKey=<unset>');
       expect(streamed).not.toContain('sk-must-be-scrubbed');
+      // DDR-123 guardrail #2 — the bridge pins the adapter to the user's own
+      // `claude` (here MAUDE_CLAUDE_BIN = this bun) via CLAUDE_CODE_EXECUTABLE, so
+      // it never falls back to the unshipped ~210 MB native binary.
+      expect(streamed).toContain(`claudeExe=${process.execPath}`);
     } finally {
       await bridge.stop();
     }

package/apps/studio/test/acp-origin-gate.test.ts

@@ -61,6 +61,23 @@ describe('ACP bridge origin gate', () => {
       expect((await focusPost.json()).ok).toBe(true);
       expect(await status(main, '/_api/acp/focus')).toBe(405); // GET not allowed
       expect(await status(canvas, '/_api/acp/focus')).toBe(403); // off the canvas origin
+
+      // (5) DDR-128 — /_api/preflight readiness probe: main-origin 200 with the
+      // {ready, items[]} shape; 403 on the untrusted canvas origin (dual-allowlist).
+      const pre = await fetch(`${main}/_api/preflight`, { signal: AbortSignal.timeout(2000) });
+      expect(pre.status).toBe(200);
+      const preJson = await pre.json();
+      expect(typeof preJson.ready).toBe('boolean');
+      expect(Array.isArray(preJson.items)).toBe(true);
+      expect(await status(canvas, '/_api/preflight')).toBe(403);
+      // A cross-origin drive-by GET is Origin-rejected before the probe can shell
+      // out — DDR-128 DoS hardening (ethical-hacker F1). Same-origin/loopback (no
+      // Origin header, asserted above) stays 200.
+      const crossOrigin = await fetch(`${main}/_api/preflight`, {
+        headers: { Origin: 'https://evil.example' },
+        signal: AbortSignal.timeout(2000),
+      });
+      expect(crossOrigin.status).toBe(403);
     } finally {
       await killProc(proc);
     }

package/apps/studio/test/fixtures/mock-acp-agent.mjs

@@ -36,7 +36,8 @@ acp
           text:
             `apiKey=${process.env.ANTHROPIC_API_KEY ?? '<unset>'} ` +
             `model=${process.env.ANTHROPIC_MODEL ?? '<unset>'} ` +
-            `thinking=${process.env.MAX_THINKING_TOKENS ?? '<unset>'}`,
+            `thinking=${process.env.MAX_THINKING_TOKENS ?? '<unset>'} ` +
+            `claudeExe=${process.env.CLAUDE_CODE_EXECUTABLE ?? '<unset>'}`,
         },
       },
     });

package/apps/studio/test/readiness.test.ts

@@ -0,0 +1,154 @@
+// Readiness probe (DDR-128) — plugin-registry scan + PATH resolution. The
+// login-shell fallback's full correctness is proven on the packaged `.app`
+// (native-verification ceiling); here we cover the registry-scan branches, the
+// no-throw contracts, and the report shape. The probe is async (the fallback shells
+// out off the event loop — DDR-128 hardening), so everything awaits.
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { probeReadiness, resolveOnPath } from '../readiness.ts';
+
+const MARKET_OK = {
+  maude: { source: { source: 'github', repo: '1aGh/maude' }, installLocation: '/x' },
+};
+const INSTALLED_BOTH = {
+  version: 2,
+  plugins: {
+    'design@maude': [{ scope: 'user', version: '0.29.0' }],
+    'flow@maude': [{ scope: 'user', version: '0.29.0' }],
+  },
+};
+const INSTALLED_DESIGN_ONLY = { version: 2, plugins: { 'design@maude': [{ scope: 'user' }] } };
+
+function fixtureClaudeDir(opts: { markets?: unknown; installed?: unknown }): string {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-readiness-'));
+  const pluginsDir = join(dir, 'plugins');
+  mkdirSync(pluginsDir, { recursive: true });
+  if (opts.markets !== undefined)
+    writeFileSync(join(pluginsDir, 'known_marketplaces.json'), JSON.stringify(opts.markets));
+  if (opts.installed !== undefined)
+    writeFileSync(join(pluginsDir, 'installed_plugins.json'), JSON.stringify(opts.installed));
+  return dir;
+}
+
+async function withClaudeDir<T>(dir: string, fn: () => Promise<T> | T): Promise<T> {
+  const saved = process.env.CLAUDE_CONFIG_DIR;
+  process.env.CLAUDE_CONFIG_DIR = dir;
+  try {
+    return await fn();
+  } finally {
+    if (saved === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+    else process.env.CLAUDE_CONFIG_DIR = saved;
+  }
+}
+
+const pluginsItem = async (dir: string) =>
+  (await withClaudeDir(dir, () => probeReadiness())).items.find((i) => i.id === 'plugins')!;
+
+describe('readiness — plugin registry scan', () => {
+  test('both plugins + marketplace present → plugins item is present, no remediation', async () => {
+    const item = await pluginsItem(
+      fixtureClaudeDir({ markets: MARKET_OK, installed: INSTALLED_BOTH })
+    );
+    expect(item.status).toBe('present');
+    expect(item.remediation).toBeUndefined();
+  });
+
+  test('only design@maude installed → missing, names the absent flow@maude + offers the fix', async () => {
+    const item = await pluginsItem(
+      fixtureClaudeDir({ markets: MARKET_OK, installed: INSTALLED_DESIGN_ONLY })
+    );
+    expect(item.status).toBe('missing');
+    expect(item.detail).toContain('flow@maude');
+    expect(item.remediation).toContain('/plugin install');
+  });
+
+  test('registry absent → unknown (Claude Code internal contract; never throws)', async () => {
+    const item = await pluginsItem(fixtureClaudeDir({}));
+    expect(item.status).toBe('unknown');
+  });
+
+  test('plugin presence is the gate — a foreign-repo marketplace does not change a both-installed verdict', async () => {
+    const item = await pluginsItem(
+      fixtureClaudeDir({
+        markets: { other: { source: { repo: 'someone/else' } } },
+        installed: INSTALLED_BOTH,
+      })
+    );
+    expect(item.status).toBe('present');
+  });
+});
+
+describe('readiness — resolveOnPath', () => {
+  test('finds a binary that is on PATH', async () => {
+    const hit = await resolveOnPath('sh');
+    expect(hit).not.toBeNull();
+    expect(existsSync(hit!)).toBe(true);
+  });
+
+  test('returns null for a bogus binary without throwing', async () => {
+    expect(await resolveOnPath('maude-definitely-not-real-xyz')).toBeNull();
+  });
+
+  test('login-shell fallback recovers a binary hidden from the app PATH', async () => {
+    const saved = process.env.PATH;
+    try {
+      // Simulate the truncated/empty GUI env so Bun.which misses and the fallback fires.
+      process.env.PATH = '';
+      const hit = await resolveOnPath('sh');
+      // When a login shell is usable it must recover an absolute, real path. In a
+      // sandbox with no usable login shell the fallback returns null — we don't fail
+      // on that, but a non-null result must be a real absolute path.
+      if (hit !== null) {
+        expect(hit.startsWith('/')).toBe(true);
+        expect(existsSync(hit)).toBe(true);
+      }
+    } finally {
+      if (saved === undefined) delete process.env.PATH;
+      else process.env.PATH = saved;
+    }
+  });
+});
+
+describe('readiness — report shape', () => {
+  test('always returns the five items with stable ids and a boolean ready', async () => {
+    const report = await probeReadiness();
+    expect(report.items.map((i) => i.id)).toEqual([
+      'claude',
+      'maude',
+      'plugins',
+      'agent-browser',
+      'adapter',
+    ]);
+    expect(typeof report.ready).toBe('boolean');
+  });
+
+  test('agent-browser is optional and never gates ready', async () => {
+    const ab = (await probeReadiness()).items.find((i) => i.id === 'agent-browser')!;
+    expect(ab.required).toBe(false);
+  });
+
+  test('adapter row tracks the real chat gate (resolveAdapterEntry) and is required', async () => {
+    const saved = process.env.MAUDE_ACP_ADAPTER_ENTRY;
+    try {
+      // Point the override at a real file → the bridge is "bundled".
+      process.env.MAUDE_ACP_ADAPTER_ENTRY = import.meta.path;
+      const present = (await probeReadiness()).items.find((i) => i.id === 'adapter')!;
+      expect(present.required).toBe(true);
+      expect(present.status).toBe('present');
+
+      // Point it at a missing path → the row goes missing with remediation, the
+      // honest signal the v0.31–0.32 builds lacked (all other rows green, chat dead).
+      process.env.MAUDE_ACP_ADAPTER_ENTRY = join(tmpdir(), 'no-such-acp-adapter-xyz');
+      const missing = (await probeReadiness()).items.find((i) => i.id === 'adapter')!;
+      expect(missing.status).toBe('missing');
+      expect(missing.remediation).toBeDefined();
+    } finally {
+      if (saved === undefined) delete process.env.MAUDE_ACP_ADAPTER_ENTRY;
+      else process.env.MAUDE_ACP_ADAPTER_ENTRY = saved;
+    }
+  });
+});

package/apps/studio/whats-new.json

@@ -1,6 +1,24 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "desktop-ai-chat-fix",
+      "version": "0.32.1",
+      "date": "2026-06-24",
+      "kind": "fix",
+      "title": "AI chat now opens in the desktop app",
+      "summary": "If the Assistant panel said AI editing wasn't ready even when Claude Code and the plugins were all installed, that's fixed. The desktop app now includes everything the chat needs and runs on your own installed Claude — open the Assistant (the ✦ in the menubar, or ⌘⇧A) and it just works.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "ai-editing-readiness-check",
+      "version": "0.32.0",
+      "date": "2026-06-24",
+      "kind": "feature",
+      "title": "See what AI editing needs",
+      "summary": "The welcome screen and the Assistant panel now show whether AI editing is ready — and if Claude Code, the maude CLI, or the Maude plugins are missing, they hand you the exact step to fix it. Check it any time under Help → Check AI editing readiness.",
+      "surface": "design-ui"
+    },
     {
       "id": "native-desktop-app",
       "version": "0.31.0",