@1agh/maude 0.36.1 → 0.38.0

package/apps/studio/readiness.ts

@@ -14,8 +14,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-
+import { isNativePluginContext } from './acp/plugin-bootstrap.ts';
 import { resolveAdapterEntry, resolveClaudePath } from './acp/probe.ts';
+import { resolveBrowser } from './bin/_ensure-browser.mjs';
+import { DESIGN_PLUGIN_DIR } from './paths.ts';
 
 export type ReadinessStatus = 'present' | 'missing' | 'unknown';
 
@@ -101,7 +103,7 @@ function readJson<T = unknown>(path: string): T | null {
   }
 }
 
-interface PluginScan {
+export interface PluginScan {
   /** 'unknown' when the registry couldn't be read (Claude Code's internal contract). */
   status: 'present' | 'unknown';
   marketplace: boolean;
@@ -114,8 +116,17 @@ interface PluginScan {
  * (`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'`.
+ *
+ * A plugin counts as present if EITHER the marketplace registry
+ * (`installed_plugins.json`) lists it OR the user enabled it in `settings.json`
+ * `enabledPlugins` (`"<plugin>@<marketplace>": true`). The adapter spawns the
+ * user's `claude` with `settingSources: ["user","project","local"]`, so a
+ * settings-enabled plugin loads NATIVELY in the session — the ACP plugin
+ * auto-bootstrap (DDR-143) must treat it as already-present and skip injection,
+ * or the command set double-registers. Exported so `acp/plugin-bootstrap.ts`
+ * reuses this single registry-scan instead of duplicating it.
  */
-function scanPlugins(): PluginScan {
+export function scanPlugins(): PluginScan {
   const dir = claudeConfigDir();
   const markets = readJson<Record<string, { source?: { repo?: string } }>>(
     join(dir, 'plugins', 'known_marketplaces.json')
@@ -123,7 +134,12 @@ function scanPlugins(): PluginScan {
   const installed = readJson<{ plugins?: Record<string, unknown> }>(
     join(dir, 'plugins', 'installed_plugins.json')
   );
-  if (!markets && !installed) {
+  // `settingSources:user` — a plugin the user enabled in ~/.claude/settings.json
+  // loads natively even if it's not in installed_plugins.json (DDR-143 no-op gate).
+  const settings = readJson<{ enabledPlugins?: Record<string, unknown> }>(
+    join(dir, 'settings.json')
+  );
+  if (!markets && !installed && !settings) {
     return { status: 'unknown', marketplace: false, design: false, flow: false };
   }
   const marketplace =
@@ -132,9 +148,11 @@ function scanPlugins(): PluginScan {
       (m) => String(m?.source?.repo ?? '').toLowerCase() === '1agh/maude'
     );
   const plugins = installed?.plugins ?? {};
+  const enabled = settings?.enabledPlugins ?? {};
   const has = (key: string): boolean => {
     const v = plugins[key];
-    return Array.isArray(v) ? v.length > 0 : !!v;
+    const installedHit = Array.isArray(v) ? v.length > 0 : !!v;
+    return installedHit || enabled[key] === true;
   };
   return { status: 'present', marketplace, design: has('design@maude'), flow: has('flow@maude') };
 }
@@ -179,40 +197,71 @@ export async function probeReadiness(): Promise<ReadinessReport> {
   });
 
   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(' + ');
+  // DDR-143 — on the native/desktop path the ACP chat session AUTO-LOADS the
+  // bundled `design` plugin (acp/plugin-bootstrap.ts → session-scoped
+  // `_meta.claudeCode.options.plugins`), so a design plugin that isn't
+  // marketplace-installed is still available in the chat. Count that as
+  // satisfied: the check collapses from a red install-wall to green. `/flow` is
+  // intentionally NOT part of the chat for now (2026-07-03), so the gate tracks
+  // `design` alone — demanding a plugin the chat doesn't use would be a false red.
+  // The web `maude design serve` path ships no bundle (native=false, dir null) →
+  // the manual marketplace remediation still shows there.
+  const native = isNativePluginContext();
+  const designAutoloaded = native && DESIGN_PLUGIN_DIR !== null && !scan.design;
+  const designReady = scan.design || designAutoloaded;
+  const pluginStatus: ReadinessStatus = designReady
+    ? 'present'
+    : scan.status === 'unknown'
+      ? 'unknown'
+      : 'missing';
   items.push({
     id: 'plugins',
-    label: 'Maude plugins in Claude Code',
+    label: 'Maude design plugin in Claude Code',
     required: true,
     status: pluginStatus,
-    detail:
-      scan.status === 'unknown'
+    detail: designReady
+      ? designAutoloaded
+        ? 'Auto-loaded in the Maude chat session — nothing to install.'
+        : 'design@maude is installed.'
+      : 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`.',
+        : `Missing: design@maude${scan.marketplace ? '' : ' (and the maude marketplace)'}.`,
+    remediation: designReady
+      ? undefined
+      : 'In Claude Code: `/plugin marketplace add 1aGh/maude`, then `/plugin install design@maude`.',
   });
 
+  // agent-browser + a headless Chromium capture artboards so `/design:*` critics
+  // can SEE the work — effectively required for the full design workflow. On the
+  // native/desktop path agent-browser is BUNDLED (externalBin, DDR — bundled
+  // screenshots) and the browser engine is resolved (or provisioned as
+  // chrome-headless-shell on first use) by ensure-browser, so it's a first-class,
+  // satisfied capability — not a red "optional install" wall. On web/CLI it stays
+  // optional (the user brings agent-browser or playwright).
+  let browserReady = false;
+  if (native) {
+    try {
+      browserReady = !!(await resolveBrowser({ download: false })).path;
+    } catch {
+      /* best-effort — the browser provisions at screenshot time regardless */
+    }
+  }
   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`.',
+    label: native ? 'Screenshot engine (design critics)' : 'agent-browser (optional)',
+    required: native,
+    status: native || agentBrowser ? 'present' : 'missing',
+    detail: native
+      ? browserReady
+        ? 'Bundled — artboard screenshots for `/design:*` critics are ready.'
+        : 'Bundled — the browser engine downloads on your first screenshot (~94 MB, one-time).'
+      : agentBrowser
+        ? 'Installed — screenshot evidence during edits.'
+        : 'Optional — richer screenshot evidence during edits.',
+    remediation:
+      native || 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

package/apps/studio/scaffold-design.ts

@@ -13,6 +13,93 @@ import { basename, join } from 'node:path';
 const CONFIG_SCHEMA =
   'https://raw.githubusercontent.com/1aGh/maude/main/apps/studio/config.schema.json';
 
+// A neutral, token-free starter canvas seeded into `ui/` so a freshly-created project
+// opens to a real artboard instead of an empty studio (the "empty-studio after Start a
+// new project" onboarding gap). It depends ONLY on @maude/canvas-lib + inline styles —
+// no design-system tokens — so it renders before /design:setup-ds exists. The button
+// vocabulary mirrors the shipped GitPanel (Save version · Publish · Get latest).
+const STARTER_CANVAS_TSX = `/**
+ * @canvas   welcome · Your first canvas — seeded when a new Maude project is created.
+ * @platform desktop
+ * @stack    React 19 · TSX · Bun.build
+ *
+ * Neutral + token-free so it renders the moment the project is created — before
+ * /design:setup-ds builds a design system. Edit it, replace it, or delete it once you
+ * have your own canvases.
+ */
+import { DCArtboard, DCSection, DesignCanvas } from "@maude/canvas-lib";
+
+export default function Welcome() {
+  return (
+    <DesignCanvas>
+      <DCSection id="welcome" title="Welcome to Maude" subtitle="START HERE">
+        <DCArtboard id="welcome" label="WELCOME/01" width={680} height={440}>
+          <div
+            data-testid="welcome-artboard-content"
+            style={{
+              height: "100%",
+              boxSizing: "border-box",
+              padding: 48,
+              display: "flex",
+              flexDirection: "column",
+              gap: 24,
+              fontFamily: "system-ui, -apple-system, sans-serif",
+              color: "#16181d",
+              background: "#fbfbfc",
+            }}
+          >
+            <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+              <span style={{ fontSize: 12, letterSpacing: "0.12em", textTransform: "uppercase", color: "#8a8f98" }}>
+                Your first canvas
+              </span>
+              <h1 style={{ margin: 0, fontSize: 30, lineHeight: 1.1, fontWeight: 650 }}>
+                You're in. This is a canvas.
+              </h1>
+              <p style={{ margin: 0, fontSize: 15, lineHeight: 1.5, color: "#4a4f57", maxWidth: 460 }}>
+                Everything you design lives on canvases like this one. Edit it, or start fresh —
+                your work saves on its own, and you can version and share it without ever opening a terminal.
+              </p>
+            </div>
+            <div style={{ display: "flex", gap: 12 }}>
+              {[
+                ["Save version", "keep a checkpoint, just for you"],
+                ["Publish", "share it with your team"],
+                ["Get latest", "pull in everyone else's work"],
+              ].map(([title, desc]) => (
+                <div key={title} style={{ flex: 1, padding: 16, border: "1px solid #e6e7ea", borderRadius: 10, background: "#fff" }}>
+                  <div style={{ fontSize: 14, fontWeight: 600, marginBottom: 4 }}>{title}</div>
+                  <div style={{ fontSize: 12.5, lineHeight: 1.4, color: "#6b7078" }}>{desc}</div>
+                </div>
+              ))}
+            </div>
+            <p style={{ margin: 0, fontSize: 13, lineHeight: 1.5, color: "#8a8f98" }}>
+              Next: build a design system, or just start editing this canvas.
+            </p>
+          </div>
+        </DCArtboard>
+      </DCSection>
+    </DesignCanvas>
+  );
+}
+`;
+
+const STARTER_CANVAS_META = {
+  title: 'Welcome',
+  subtitle: 'Your first canvas — seeded on project creation',
+  brief:
+    'Neutral, token-free welcome canvas written by scaffoldDesign() so a new project opens to a real artboard instead of an empty studio. Safe to edit or delete.',
+  platform: 'desktop',
+  sections: [
+    {
+      id: 'welcome',
+      title: 'Welcome to Maude · START HERE',
+      artboards: [{ id: 'welcome', label: 'WELCOME/01', width: 680, height: 440 }],
+    },
+  ],
+  css_mode: 'inline',
+  layout: { artboards: [{ id: 'welcome', x: 0, y: 0 }] },
+};
+
 /** Whether `dir` is already a Maude project (has `.design/config.json`). */
 export function hasDesign(dir: string): boolean {
   return existsSync(join(dir, '.design', 'config.json'));
@@ -47,8 +134,14 @@ export function scaffoldDesign(dir: string, name?: string): ScaffoldResult {
       completenessProfile: 'standard',
     };
     writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-    // Keep the empty group dirs in git so a fresh clone still has the structure.
-    writeFileSync(join(designDir, 'ui', '.gitkeep'), '', 'utf8');
+    // Seed a starter canvas so the studio opens to a real artboard, not an empty list.
+    writeFileSync(join(designDir, 'ui', 'Welcome.tsx'), STARTER_CANVAS_TSX, 'utf8');
+    writeFileSync(
+      join(designDir, 'ui', 'Welcome.meta.json'),
+      `${JSON.stringify(STARTER_CANVAS_META, null, 2)}\n`,
+      'utf8'
+    );
+    // `system/` is genuinely empty until /design:setup-ds — keep it in git.
     writeFileSync(join(designDir, 'system', '.gitkeep'), '', 'utf8');
     return { ok: true };
   } catch (e) {

package/apps/studio/server.ts

@@ -31,7 +31,7 @@ import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
 import { createSyncRuntime } from './sync/index.ts';
-import { createWs, isLoopbackHost, parseCollabSlug, type WsData } from './ws.ts';
+import { createWs, isLoopbackHost, isSameOriginWs, parseCollabSlug, type WsData } from './ws.ts';
 
 // Phase 19 / DDR-044 — covers the marketplace-cache-install gap where
 // node_modules/ ships empty (git clone honors .gitignore). Auto-installs +
@@ -100,7 +100,10 @@ const gitLifecycle = createGitLifecycle(ctx, collab.registry);
 const activity = createActivity(ctx);
 // Phase 31 (DDR-123) — ACP chat bridge manager. Owns one claude-agent-acp
 // subprocess per /_ws/acp socket; main-origin + loopback only (wired below).
-const acp = createAcp(ctx);
+// Gets the ai-activity registry so agent edits raise the same "Claude is
+// editing" banner + presence as /design:edit (RC5,
+// rca/issue-canvas-hmr-optimistic-update-consistency).
+const acp = createAcp(ctx, aiActivity);
 const ws = createWs(ctx, api, inspect, collab, activity, acp);
 const http = createHttp(ctx, api, inspect, aiActivity);
 const fsWatch = createFsWatch(ctx);
@@ -170,6 +173,12 @@ function startServer(port: number): BunServer {
         if (!isLoopbackHost(req.headers.get('host'))) {
           return new Response('ACP chat is loopback-only', { status: 403 });
         }
+        // CSWSH defense: a WS handshake bypasses SOP, so loopback-Host alone would
+        // let a cross-origin drive-by open this privileged socket (spawns `claude`,
+        // drives edits). Reject any Origin that isn't this same loopback server.
+        if (!isSameOriginWs(req)) {
+          return new Response('ACP chat is same-origin only', { status: 403 });
+        }
         const ok = srv.upgrade(req, {
           data: {
             id: crypto.randomUUID(),

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

@@ -0,0 +1,154 @@
+// RCA issue-acp-subagent-activity-invisible — the ACP chat "still working"
+// indicator must survive the premature turn-end that claude-agent-acp emits
+// while background subagents are still running (adapter settles the prompt at
+// the main agent's `result`, #773). These lock the pure activity reducer +
+// label so a background subagent stays visible instead of the panel looking idle.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  activityLabel,
+  applyUpdate,
+  isSubagentTool,
+  reduceActivity,
+} from '../client/panels/acp-runtime.js';
+
+const call = (id: string, toolName?: string, over: Record<string, unknown> = {}) => ({
+  t: 'update' as const,
+  update: {
+    sessionUpdate: 'tool_call',
+    toolCallId: id,
+    title: over.title,
+    kind: over.kind,
+    ...(toolName ? { _meta: { claudeCode: { toolName } } } : {}),
+  },
+});
+const done = (id: string, status = 'completed') => ({
+  t: 'update' as const,
+  update: { sessionUpdate: 'tool_call_update', toolCallId: id, status },
+});
+
+describe('reduceActivity', () => {
+  test('a Task tool_call survives turn-end — the background subagent stays tracked', () => {
+    const m = new Map();
+    expect(
+      reduceActivity(m, call('t1', 'Task', { title: 'map the acp module', kind: 'think' }))
+    ).toBe(true);
+    expect(m.size).toBe(1);
+
+    // The regression this fix exists for: turn-end must NOT wipe the map.
+    expect(reduceActivity(m, { t: 'turn-end', stopReason: 'end_turn' })).toBe(false);
+    expect(m.size).toBe(1);
+
+    // …it drains on the subagent's OWN completed update, not on turn-end.
+    expect(reduceActivity(m, done('t1'))).toBe(true);
+    expect(m.size).toBe(0);
+  });
+
+  test('a hard error still wipes the map (teardown)', () => {
+    const m = new Map();
+    reduceActivity(m, call('t1', 'Read', { kind: 'read' }));
+    expect(reduceActivity(m, { t: 'error', message: 'boom' })).toBe(true);
+    expect(m.size).toBe(0);
+  });
+
+  test('captures the concrete tool name for subagent classification', () => {
+    const m = new Map();
+    reduceActivity(m, call('t1', 'Task', { title: 'x', kind: 'think' }));
+    reduceActivity(m, call('t2', 'Read', { title: 'foo.ts', kind: 'read' }));
+    const tools = [...m.values()];
+    expect(isSubagentTool(tools[0])).toBe(true);
+    expect(isSubagentTool(tools[1])).toBe(false);
+  });
+
+  test('failed updates remove the tool; unknown ids are a no-op', () => {
+    const m = new Map();
+    reduceActivity(m, call('t1', 'Bash', { kind: 'execute' }));
+    expect(reduceActivity(m, done('nope'))).toBe(false);
+    expect(reduceActivity(m, done('t1', 'failed'))).toBe(true);
+    expect(m.size).toBe(0);
+  });
+});
+
+describe('activityLabel', () => {
+  test('subagents get explicit, counted wording', () => {
+    expect(activityLabel([{ toolName: 'Task', title: 'a' }])).toBe('1 subagent running');
+    expect(activityLabel([{ toolName: 'Task' }, { toolName: 'Agent' }])).toBe(
+      '2 subagents running'
+    );
+  });
+
+  test('non-subagent tools fall back to title / count / Working…', () => {
+    expect(activityLabel([{ title: 'Edit foo.ts' }])).toBe('Edit foo.ts');
+    expect(activityLabel([{ title: 'a' }, { title: 'b' }])).toBe('2 tasks running');
+    expect(activityLabel([])).toBe('Working…');
+  });
+});
+
+// The F2 fix: the SAME reducer folds live-turn frames AND the post-turn-end
+// "background continuation" frames the client used to drop. If this drifts, the
+// dropped subagent results / consolidation render wrong (or not at all).
+describe('applyUpdate (shared part reducer)', () => {
+  const chunk = (text: string) => ({
+    sessionUpdate: 'agent_message_chunk',
+    content: { type: 'text', text },
+  });
+  const call = (id: string, title: string, kind: string, rawInput: unknown = {}) => ({
+    sessionUpdate: 'tool_call',
+    toolCallId: id,
+    title,
+    kind,
+    rawInput,
+  });
+  const upd = (id: string, status: string, rawOutput: unknown) => ({
+    sessionUpdate: 'tool_call_update',
+    toolCallId: id,
+    status,
+    rawOutput,
+  });
+
+  test('coalesces consecutive text chunks into one part', () => {
+    const parts: unknown[] = [];
+    const ti = new Map();
+    applyUpdate(parts, ti, chunk('Panel: '));
+    applyUpdate(parts, ti, chunk('9 blockers'));
+    expect(parts).toEqual([{ type: 'text', text: 'Panel: 9 blockers' }]);
+  });
+
+  test('tool_call adds a pending part; tool_call_update fills the result', () => {
+    const parts: Array<Record<string, unknown>> = [];
+    const ti = new Map();
+    applyUpdate(parts, ti, call('t1', 'Write critique/001.md', 'edit', { path: 'x' }));
+    expect(parts[0]).toMatchObject({ type: 'tool-call', toolName: 'Write critique/001.md' });
+    expect(parts[0].result).toBeUndefined();
+    applyUpdate(parts, ti, upd('t1', 'completed', { ok: true }));
+    expect(parts[0]).toMatchObject({ result: { ok: true }, isError: false });
+  });
+
+  test('failed update marks isError', () => {
+    const parts: Array<Record<string, unknown>> = [];
+    const ti = new Map();
+    applyUpdate(parts, ti, call('t1', 'Bash', 'execute'));
+    applyUpdate(parts, ti, upd('t1', 'failed', null));
+    expect(parts[0].isError).toBe(true);
+  });
+
+  test('thought → reasoning part; usage/plan ignored', () => {
+    const parts: unknown[] = [];
+    const ti = new Map();
+    applyUpdate(parts, ti, {
+      sessionUpdate: 'agent_thought_chunk',
+      content: { type: 'text', text: 'hmm' },
+    });
+    applyUpdate(parts, ti, { sessionUpdate: 'usage_update' });
+    applyUpdate(parts, ti, { sessionUpdate: 'plan' });
+    expect(parts).toEqual([{ type: 'reasoning', text: 'hmm' }]);
+  });
+
+  test('update for an unknown tool id is a no-op', () => {
+    const parts: unknown[] = [];
+    const ti = new Map();
+    applyUpdate(parts, ti, upd('nope', 'completed', {}));
+    expect(parts).toEqual([]);
+  });
+});

package/apps/studio/test/acp-ai-activity.test.ts

@@ -0,0 +1,182 @@
+// RC5 (rca/issue-canvas-hmr-optimistic-update-consistency) — the ACP chat agent
+// must raise the same "Claude is editing" ai-activity banner as /design:edit.
+// The tracker watches streamed tool_call / tool_call_update notifications for
+// edit-kind tools touching canvas files and drives start/heartbeat/end.
+
+import { describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+
+import type { SessionUpdate } from '@agentclientprotocol/sdk';
+
+import { createAgentActivityTracker } from '../acp/index.ts';
+import type { AiActivity, AiActivityEntry } from '../collab/ai-activity.ts';
+import { type Context, createBus } from '../context.ts';
+
+const ROOT = join('/tmp', 'acp-ai-root');
+const DESIGN = join(ROOT, '.design');
+
+function mkCtx(): Context {
+  return {
+    cfg: {} as Context['cfg'],
+    projectLabel: 'test',
+    bus: createBus(),
+    paths: {
+      repoRoot: ROOT,
+      designRel: '.design',
+      designRoot: DESIGN,
+      serverInfoFile: join(DESIGN, '_server.json'),
+      activeFile: join(DESIGN, '_active.json'),
+      commentsDir: join(DESIGN, '_comments'),
+      canvasStateDir: join(DESIGN, '_canvas-state'),
+      historyDir: join(DESIGN, '_history'),
+      tokensUrlRel: '',
+      systemDirRel: 'system',
+    },
+  };
+}
+
+function mkAi(): { ai: AiActivity; calls: string[] } {
+  const calls: string[] = [];
+  const entry = (file: string): AiActivityEntry => ({
+    file,
+    author: 'x',
+    startedAt: 0,
+    lastHeartbeat: 0,
+  });
+  const ai: AiActivity = {
+    start(file, author) {
+      calls.push(`start:${file}:${author}`);
+      return entry(file);
+    },
+    heartbeat(file) {
+      calls.push(`beat:${file}`);
+      return entry(file);
+    },
+    end(file) {
+      calls.push(`end:${file}`);
+      return true;
+    },
+    list: () => [],
+    get: () => null,
+    stop: () => {},
+  };
+  return { ai, calls };
+}
+
+const upd = (u: Record<string, unknown>): SessionUpdate => u as unknown as SessionUpdate;
+
+describe('acp / agent activity tracker', () => {
+  test('edit tool_call on a canvas starts ai-activity with the designRel key', () => {
+    const { ai, calls } = mkAi();
+    const t = createAgentActivityTracker(mkCtx(), ai);
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 't1',
+        kind: 'edit',
+        locations: [{ path: join(DESIGN, 'ui', 'Foo.tsx') }],
+      })
+    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toStartWith('start:.design/ui/Foo.tsx:');
+  });
+
+  test('follow-up update for the same file inside the beat throttle adds nothing', () => {
+    const { ai, calls } = mkAi();
+    const t = createAgentActivityTracker(mkCtx(), ai);
+    const loc = { locations: [{ path: join(DESIGN, 'ui', 'Foo.tsx') }] };
+    t.onUpdate(upd({ sessionUpdate: 'tool_call', toolCallId: 't1', kind: 'edit', ...loc }));
+    // kind omitted on the update — must be recalled from the tool_call by id.
+    t.onUpdate(upd({ sessionUpdate: 'tool_call_update', toolCallId: 't1', ...loc }));
+    expect(calls).toHaveLength(1);
+  });
+
+  test('read/search tools and non-canvas paths never banner', () => {
+    const { ai, calls } = mkAi();
+    const t = createAgentActivityTracker(mkCtx(), ai);
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 'r1',
+        kind: 'read',
+        locations: [{ path: join(DESIGN, 'ui', 'Foo.tsx') }],
+      })
+    );
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 'e2',
+        kind: 'edit',
+        locations: [{ path: join(ROOT, 'src', 'App.tsx') }], // outside designRoot
+      })
+    );
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 'e3',
+        kind: 'edit',
+        locations: [{ path: join(DESIGN, '_history', 'x', 'Foo.tsx') }], // runtime state
+      })
+    );
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 'e4',
+        kind: 'edit',
+        locations: [{ path: join(DESIGN, 'ui', 'Foo.meta.json') }], // not a canvas
+      })
+    );
+    expect(calls).toEqual([]);
+  });
+
+  test('rawInput.file_path works when locations are absent', () => {
+    const { ai, calls } = mkAi();
+    const t = createAgentActivityTracker(mkCtx(), ai);
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 'w1',
+        kind: 'edit',
+        rawInput: { file_path: join(DESIGN, 'ui', 'Bar.tsx') },
+      })
+    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toStartWith('start:.design/ui/Bar.tsx:');
+  });
+
+  test('endTurn ends every banner this turn raised', () => {
+    const { ai, calls } = mkAi();
+    const t = createAgentActivityTracker(mkCtx(), ai);
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 't1',
+        kind: 'edit',
+        locations: [{ path: join(DESIGN, 'ui', 'Foo.tsx') }],
+      })
+    );
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 't2',
+        kind: 'edit',
+        locations: [{ path: join(DESIGN, 'ui', 'Bar.tsx') }],
+      })
+    );
+    t.endTurn();
+    expect(calls.filter((c) => c.startsWith('end:'))).toEqual([
+      'end:.design/ui/Foo.tsx',
+      'end:.design/ui/Bar.tsx',
+    ]);
+    // A later turn on the same file must start (not silently beat) again.
+    t.onUpdate(
+      upd({
+        sessionUpdate: 'tool_call',
+        toolCallId: 't3',
+        kind: 'edit',
+        locations: [{ path: join(DESIGN, 'ui', 'Foo.tsx') }],
+      })
+    );
+    expect(calls.filter((c) => c.startsWith('start:'))).toHaveLength(3);
+  });
+});