@1agh/maude 0.58.0 → 0.58.2

package/apps/studio/sync/remote-docs.ts

@@ -24,6 +24,8 @@
 // file outside the design root. That is not policy filtering, it is the
 // difference between writing your project and writing your filesystem.
 
+import { type CanvasGroupLike, resolveCanvasBodyRel } from './canvas-path.ts';
+
 /** One document as the hub reports it. */
 export interface RemoteDoc {
   name: string;
@@ -147,31 +149,66 @@ export function slugFromDocName(docName: string): string | null {
 export interface PullTarget {
   slug: string;
   docName: string;
-  /** Absolute path the body will be written to, flat under the design root. */
+  /** Absolute path the body will be written to. */
   bodyAbs: string;
+  /** True when the path came from the document's own `syncMeta.path` and was
+   *  accepted — false when it was absent or refused and the fallback applied. */
+  fromPath: boolean;
+}
+
+export interface PullTargetOptions {
+  /** Design root, relative to the repo root. Rule 7 of the path check. */
+  designRel?: string;
+  /** Declared canvas groups — the fallback places the body inside one. */
+  canvasGroups?: readonly CanvasGroupLike[];
+  /** Fresh-link relaxation — see `validateCanvasPath`. */
+  allowUndeclaredGroup?: boolean;
+  /**
+   * The document's own `syncMeta.path`, if it is already known.
+   *
+   * USUALLY NULL AT THIS POINT, and that is not an oversight. The listing
+   * (`GET /api/documents`) carries names and byte counts only — the path lives
+   * INSIDE the document, so it cannot be resolved until that document has
+   * synced. The runtime therefore calls this to get a provisional target, then
+   * `resolvePulledTarget` again per document once its doc is populated (see
+   * sync/index.ts). Tests pass it directly, which is the whole reason it is a
+   * parameter rather than a fetch.
+   */
+  pathFor?: (docName: string, slug: string) => string | null | undefined;
+  /** See `resolvePulledTarget`. */
+  realpath?: (p: string) => string;
+  /** Called with (slug, reason) when a PRESENT path is refused. */
+  onRefused?: (slug: string, reason: string) => void;
 }
 
 /**
  * Where a hub-only document lands on disk.
  *
- * FLAT, directly under the design root — the same convention the hub applies in
- * the mirror direction (`workspace-files.mjs defaultBodyPath`) and for the same
- * reason: a slug is lossy, `ui-card` cannot be un-flattened into `ui/Card.tsx`
- * without guessing, and guessing wrong scatters files into directories the user
- * never made. A flat file is trivially moved; an invented tree is not. Moving it
- * later does not break sync — both paths slug to the same document.
+ * It used to be FLAT, directly under the design root, because a slug is lossy —
+ * `ui-card` cannot be un-flattened into `ui/Card.tsx` without guessing, and
+ * guessing wrong scatters files into directories the user never made. The
+ * comment here said a flat file "is trivially moved"; the hub's twin said a
+ * desktop peer "will move it on its next sync". Neither was a mechanism, and
+ * nothing moved it — and a file at the design root is inside no canvas group,
+ * so the tree never listed it and `scanCanvases` never synced it onward.
+ *
+ * So the path now travels with the document (`syncMeta.path`) and is checked
+ * rather than trusted — see `sync/canvas-path.ts` for the eight rules and for
+ * why rule 7 is the one that makes it safe. Absent or refused, the fallback
+ * still applies, but inside a canvas group.
  *
- * Returns only targets that resolve INSIDE the design root. A document name is
- * hub-controlled input, and this is the last point before a create.
+ * Returns only targets that resolve INSIDE the design root. A document name and
+ * a document's path are both hub-controlled input, and this is the last point
+ * before a create — so the containment check stays even for a validated path.
  */
 export function pullTargets(
   hubOnly: readonly RemoteDoc[],
   designRoot: string,
   join: (...parts: string[]) => string,
   resolve: (p: string) => string,
-  sep: string
+  sep: string,
+  opts: PullTargetOptions = {}
 ): PullTarget[] {
-  const rootResolved = resolve(designRoot);
   const out: PullTarget[] = [];
   // One slug, one target. `slugFromDocName` lowercases, so a hub advertising
   // `Foo`, `foo` and `ws/w/main/foo` yields three targets for ONE file — three
@@ -182,10 +219,80 @@ export function pullTargets(
     const slug = slugFromDocName(doc.name);
     if (!slug || seen.has(slug)) continue;
     seen.add(slug);
-    const bodyAbs = join(designRoot, `${slug}.tsx`);
-    const target = resolve(bodyAbs);
-    if (target !== rootResolved && !target.startsWith(rootResolved + sep)) continue;
-    out.push({ slug, docName: doc.name, bodyAbs });
+    const target = resolvePulledTarget({
+      slug,
+      path: opts.pathFor?.(doc.name, slug) ?? null,
+      designRoot,
+      designRel: opts.designRel,
+      canvasGroups: opts.canvasGroups,
+      allowUndeclaredGroup: opts.allowUndeclaredGroup,
+      join,
+      resolve,
+      sep,
+      realpath: opts.realpath,
+      onRefused: opts.onRefused ? (reason) => opts.onRefused?.(slug, reason) : undefined,
+    });
+    if (!target) continue;
+    out.push({ slug, docName: doc.name, ...target });
   }
   return out;
 }
+
+/**
+ * One document's body path — the whole receiver-side decision, in one call.
+ *
+ * Separate from `pullTargets` because the runtime needs it TWICE: once from the
+ * listing (where no path is known yet, so every target is a fallback) and again
+ * per document once that document has synced and its `syncMeta.path` is
+ * readable. Both hops go through the same function, so "where does this canvas
+ * go" cannot have two answers.
+ *
+ * Returns null when even the containment check refuses — the only case in which
+ * a canvas is dropped rather than degraded.
+ */
+export function resolvePulledTarget(args: {
+  slug: string;
+  path: unknown;
+  designRoot: string;
+  designRel?: string;
+  canvasGroups?: readonly CanvasGroupLike[];
+  allowUndeclaredGroup?: boolean;
+  join: (...parts: string[]) => string;
+  resolve: (p: string) => string;
+  sep: string;
+  /**
+   * Resolve symlinks on the deepest EXISTING ancestor of a path.
+   *
+   * `resolve()` is purely lexical — it never follows a symlink — and the
+   * receivers create parent directories with `mkdirSync(recursive: true)`, which
+   * happily traverses one that already exists. While the only reachable target
+   * was `<designRoot>/<slug>.tsx` that only mattered for a symlinked design root
+   * (operator-controlled); now the sender picks the directory, so any symlink
+   * committed anywhere under a canvas group is a write-outside primitive.
+   * Injected rather than imported because this module is dependency-free.
+   */
+  realpath?: (p: string) => string;
+  onRefused?: (reason: string) => void;
+}): { bodyAbs: string; fromPath: boolean } | null {
+  const { rel, fromPath } = resolveCanvasBodyRel({
+    path: args.path,
+    slug: args.slug,
+    designRel: args.designRel,
+    canvasGroups: args.canvasGroups,
+    allowUndeclaredGroup: args.allowUndeclaredGroup,
+    onRefused: args.onRefused,
+  });
+  const bodyAbs = args.join(args.designRoot, rel);
+  // Belt and braces at a create. The validator already refuses everything that
+  // could escape lexically; this catches whatever a platform's own `resolve`
+  // makes of a string neither of us anticipated.
+  const rootResolved = args.resolve(args.designRoot);
+  const target = args.resolve(bodyAbs);
+  if (target !== rootResolved && !target.startsWith(rootResolved + args.sep)) return null;
+  if (args.realpath) {
+    const realRoot = args.realpath(rootResolved);
+    const realTarget = args.realpath(target);
+    if (realTarget !== realRoot && !realTarget.startsWith(realRoot + args.sep)) return null;
+  }
+  return { bodyAbs, fromPath };
+}

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

@@ -28,6 +28,7 @@ import type { WsData } from '../ws.ts';
 
 const FIXTURE_SLOW = join(import.meta.dir, 'fixtures', 'mock-acp-agent-slow.mjs');
 const FIXTURE_PERM = join(import.meta.dir, 'fixtures', 'mock-acp-agent-permission.mjs');
+const FIXTURE_WEDGED = join(import.meta.dir, 'fixtures', 'mock-acp-agent-wedged.mjs');
 const TEST_ENV_KEYS = ['MAUDE_ACP_ADAPTER_ENTRY', 'MAUDE_ACP_RUNTIME', 'MAUDE_CLAUDE_BIN'];
 
 function useMockAgent(fixture: string) {
@@ -333,6 +334,111 @@ describe('bridge lifetime — the attach seq is client-supplied and must be boun
   }, 30000);
 });
 
+describe('cancel() must not hang forever on a non-cooperating agent (issue-82)', () => {
+  // The reported bug: "I clicked STOP and nothing happened. Probably stuck."
+  // The old cancel() just `await`ed the cooperative ACP `session/cancel`
+  // request with no bound — a wedged subprocess (or one that never
+  // implemented session/cancel at all, as here) left it, and the pending
+  // prompt() call, hanging forever. `bridge.cancel()` below must always
+  // return, and it must force the stuck turn to actually end.
+  test('cancel() escalates and force-ends the turn when the agent never responds', async () => {
+    useMockAgent(FIXTURE_WEDGED);
+    const ctx = freshCtx();
+    const bridge = new AcpBridge({
+      repoRoot: ctx.paths.repoRoot,
+      cancelEscalationMs: 200, // real default is 5s; keep the test fast
+      onUpdate: () => {},
+    });
+    try {
+      const promptPromise = bridge.prompt('go', 'c1');
+      // Let the turn actually reach the wedged conn.prompt() call — the same
+      // race a real Stop click lands in — before cancelling.
+      await until(() => (bridge.sessionId ? true : undefined));
+
+      // This is the assertion that matters: without the fix, this call never
+      // resolves and the test times out.
+      await bridge.cancel();
+
+      await expect(promptPromise).rejects.toThrow(/did not respond/);
+      // The subprocess was actually killed, not just the promise resolved —
+      // otherwise a "cancelled" chat could keep silently running/burning
+      // tokens in the background.
+      expect(bridge.connected).toBe(false);
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+
+  // Ethical-hacker finding on the first cut of this fix: `handlePrompt` has
+  // no reentrancy guard, so a duplicate/replayed `prompt` frame for the same
+  // chat can start a SECOND, overlapping turn on one bridge. A single shared
+  // "pending turn" field would be overwritten by that second turn and then
+  // nulled by whichever turn settles FIRST — even an ordinary, uncancelled
+  // completion — silently leaving an earlier, genuinely wedged turn
+  // permanently unescalatable and reopening this exact bug from a different
+  // angle. Pin that a normal turn finishing does not blind cancel() to a
+  // still-stuck one that started before it.
+  test('an overlapping turn finishing normally does not blind cancel() to an earlier wedged one', async () => {
+    useMockAgent(FIXTURE_WEDGED);
+    const ctx = freshCtx();
+    const bridge = new AcpBridge({
+      repoRoot: ctx.paths.repoRoot,
+      cancelEscalationMs: 200,
+      onUpdate: () => {},
+    });
+    try {
+      // Turn A — the fixture's FIRST session/prompt call, which wedges forever.
+      const turnA = bridge.prompt('go', 'c1');
+      await until(() => (bridge.sessionId ? true : undefined));
+
+      // Turn B — a second, overlapping call for the SAME chat while A is
+      // still in flight. The fixture resolves every call after the first
+      // quickly, so this settles normally with no cancellation involved.
+      const turnB = bridge.prompt('go again', 'c1');
+      await expect(turnB).resolves.toMatchObject({ stopReason: 'end_turn' });
+
+      // Turn B's ordinary completion must not have cleared turn A's
+      // escalation registration — cancel() must still find and force-end A.
+      await bridge.cancel();
+      await expect(turnA).rejects.toThrow(/did not respond/);
+      expect(bridge.connected).toBe(false);
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+
+  // A second-round ethical-hacker finding on THIS fix: cancel()'s escalation
+  // calls this.stop() directly, which does NOT go through index.ts's reap()
+  // (the only place that deletes a bridge from the `bridges` map). Without a
+  // guard, the SAME now-`stopped` instance would stay live and silently
+  // respawn a working-looking subprocess on the next prompt — except its
+  // requestPermission/unstable_createElicitation handlers auto-deny forever
+  // (the `stopped` check never resets), a silent permission-gate regression
+  // with no visible error. `ensureStarted()` must refuse to resurrect it.
+  test('after cancel() escalates and self-stops, the bridge refuses to silently respawn', async () => {
+    useMockAgent(FIXTURE_WEDGED);
+    const ctx = freshCtx();
+    const bridge = new AcpBridge({
+      repoRoot: ctx.paths.repoRoot,
+      cancelEscalationMs: 200,
+      onUpdate: () => {},
+    });
+    try {
+      const promptPromise = bridge.prompt('go', 'c1');
+      await until(() => (bridge.sessionId ? true : undefined));
+      await bridge.cancel(); // escalates → self-stop()
+      await expect(promptPromise).rejects.toThrow(/did not respond/);
+      expect(bridge.connected).toBe(false);
+
+      // The assertion that matters: a LOUD, immediate error — never a silent
+      // respawn into a permanently permission-denying session.
+      await expect(bridge.prompt('again', 'c1')).rejects.toThrow(/stopped and cannot be reused/);
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+});
+
 describe('set-mode is attachment-scoped too (ethical-hacker A2)', () => {
   test('a socket CANNOT flip another chat into bypassPermissions', async () => {
     // A2 was the one control frame that escaped the attachment-scoping sweep,

package/apps/studio/test/artboard-hug-commit.test.ts

@@ -0,0 +1,36 @@
+// artboard-hug-commit.ts — issue #79. The Artboard Inspector's Height
+// NumberField silently dropped a typed value whenever the artboard was in
+// Hug mode (fixed=false, the default per DDR-027 Design Decision 1) — Width
+// always worked because it has no such mode. Typing a height should instead
+// promote the artboard to Fixed at that height, same as the Hug/Fixed
+// toggle's own freeze-current-height write.
+
+import { describe, expect, test } from 'bun:test';
+
+import { resolveHeightCommit } from '../artboard-hug-commit.ts';
+
+describe('artboard-hug-commit / resolveHeightCommit', () => {
+  test('fixed=true → plain resize (Width-field parity)', () => {
+    expect(resolveHeightCommit(true, 480)).toEqual({ kind: 'resize', height: 480 });
+  });
+
+  test('fixed=false (Hug, the default) → promotes to Fixed at the typed height', () => {
+    // Before the fix this typed value was dropped entirely (no action) —
+    // reproducing "when I want to set height... manually from inspector
+    // panel, nothing happened. Width works."
+    expect(resolveHeightCommit(false, 480)).toEqual({ kind: 'promote-to-fixed', height: 480 });
+  });
+
+  test('rounds a fractional typed value', () => {
+    expect(resolveHeightCommit(true, 480.6)).toEqual({ kind: 'resize', height: 481 });
+    expect(resolveHeightCommit(false, 480.6)).toEqual({ kind: 'promote-to-fixed', height: 481 });
+  });
+
+  test('non-finite or non-positive input → noop, in either mode', () => {
+    expect(resolveHeightCommit(true, Number.NaN)).toEqual({ kind: 'noop' });
+    expect(resolveHeightCommit(true, 0)).toEqual({ kind: 'noop' });
+    expect(resolveHeightCommit(true, -10)).toEqual({ kind: 'noop' });
+    expect(resolveHeightCommit(false, Number.NaN)).toEqual({ kind: 'noop' });
+    expect(resolveHeightCommit(false, 0)).toEqual({ kind: 'noop' });
+  });
+});

package/apps/studio/test/clip-ops.test.ts

@@ -31,6 +31,11 @@ import {
 
 const CANVAS = '/abs/Canvas.tsx';
 
+// Adversarial fixture (security review 2026-07-30) — a prompt embedding a
+// fake </AIPlaceholder> close tag + template-literal/env-var syntax, proving
+// the JSON.stringify escaping discipline (DDR-150 P1) holds under attack.
+const EVIL = '*/ `backtick` ${process.env.HOME} </AIPlaceholder> "q" \\';
+
 const SERIES = [
   "import { TransitionSeries } from '@remotion/transitions';",
   'const S1 = 90;',
@@ -568,8 +573,6 @@ describe('greenfield first drop (Task 20)', () => {
 });
 
 describe('AIPlaceholder insert + resolve (Tasks 21–22)', () => {
-  const EVIL = '*/ `backtick` ${process.env.HOME} </AIPlaceholder> "q" \\';
-
   test('prompt is JSON.stringified into the JSX (injection fixtures) and enumerates back', () => {
     const r = applyInsertClipAt(CANVAS, SERIES, 'a', {
       lane: 'storyline',
@@ -833,4 +836,83 @@ describe('layers model — set-text + move between layers', () => {
     expect(cc.clips.filter((c) => c.tag === 'Sequence').length).toBe(0); // overlay row gone
     expect(back.source).toContain('const TOTAL = 270;'); // exact content end again
   });
+
+  // Bug: issue #81 — an AI placeholder slate (no media src yet) was refused by
+  // both move verbs, so it could never leave the storyline it was dropped
+  // into. A placeholder has no <src> to graft, but it has a prompt + kind
+  // that can ride over unchanged.
+  test('AI placeholder beat → overlay layer keeps the prompt (no media src required)', () => {
+    const withPh = applyInsertClipAt(CANVAS, HARDCUT, 'a', {
+      lane: 'storyline',
+      index: 3,
+      durationInFrames: 60,
+      placeholder: { prompt: 'drone shot over Brno', kind: 'veo' },
+    });
+    const r = applyMoveClipToOverlay(
+      CANVAS,
+      withPh.source,
+      'a',
+      withPh.stableId as string,
+      undefined
+    );
+    const cc = enumerateClips(CANVAS, r.source, 'a');
+    const overlays = cc.clips.filter((c) => c.tag === 'Sequence');
+    expect(overlays.length).toBe(1);
+    expect(overlays[0]?.placeholder?.prompt).toBe('drone shot over Brno');
+    expect(overlays[0]?.mediaSrc).toBe(null);
+    const beats = cc.clips.filter((c) => c.kind === 'sequence' && c.tag !== 'Sequence');
+    expect(beats.length).toBe(3); // the placeholder beat left the storyline
+  });
+
+  test('AI placeholder overlay → storyline round-trips the prompt back into a beat', () => {
+    const withPh = applyInsertClipAt(CANVAS, HARDCUT, 'a', {
+      lane: 'overlay',
+      from: 0,
+      durationInFrames: 45,
+      placeholder: { prompt: 'sunset time-lapse', kind: 'image' },
+    });
+    const back = applyMoveClipToStoryline(
+      CANVAS,
+      withPh.source,
+      'a',
+      withPh.stableId as string,
+      undefined
+    );
+    const cc = enumerateClips(CANVAS, back.source, 'a');
+    const beats = cc.clips.filter((c) => c.kind === 'sequence' && c.tag !== 'Sequence');
+    expect(beats.some((c) => c.placeholder?.prompt === 'sunset time-lapse')).toBe(true);
+    expect(cc.clips.filter((c) => c.tag === 'Sequence').length).toBe(0); // overlay row gone
+  });
+
+  // Adversarial (security review 2026-08-07): the move path must go through
+  // the same JSON.stringify escaping as a fresh insert (DDR-150 P1) — prove
+  // it with the same EVIL fixture the insert/resolve suite uses above, not
+  // just infer it from code-path sharing.
+  test('AI placeholder move preserves EVIL-prompt escaping (F-A3 companion)', () => {
+    const withPh = applyInsertClipAt(CANVAS, HARDCUT, 'a', {
+      lane: 'storyline',
+      index: 3,
+      durationInFrames: 60,
+      placeholder: { prompt: EVIL, kind: 'veo' },
+    });
+    const moved = applyMoveClipToOverlay(
+      CANVAS,
+      withPh.source,
+      'a',
+      withPh.stableId as string,
+      undefined
+    );
+    expect(moved.source).toContain(`<span>{${JSON.stringify(EVIL)}}</span>`);
+    const back = applyMoveClipToStoryline(
+      CANVAS,
+      moved.source,
+      'a',
+      moved.stableId as string,
+      undefined
+    );
+    expect(back.source).toContain(`<span>{${JSON.stringify(EVIL)}}</span>`);
+    const cc = enumerateClips(CANVAS, back.source, 'a');
+    const beats = cc.clips.filter((c) => c.kind === 'sequence' && c.tag !== 'Sequence');
+    expect(beats.some((c) => c.placeholder?.prompt === EVIL)).toBe(true);
+  });
 });

package/apps/studio/test/comment-relay-origin-gate.test.ts

@@ -0,0 +1,117 @@
+// The shell's inbound-postMessage comment relays must stay scoped to the
+// ACTIVE canvas.
+//
+// Threat: the origin check at the top of app.jsx's `onMessage` compares against
+// the single shared `canvasOrigin`, so EVERY open canvas iframe passes it —
+// including ones in background tabs. `comment-submit` / `comment-patch` /
+// `comment-delete` relay straight onto the privileged WS, so without a
+// per-message `e.source === activeWin` gate a background canvas can write
+// comments onto a file it names itself, with no user gesture. That mattered
+// little while comments were an inert store; the ACP panel's one-click
+// "Implement N comments" action turns open comments into a feed the agent acts
+// on, which is what promoted the seam to worth-closing.
+//
+// This is a SOURCE-STRUCTURE test, not a behavioural one: `App()` is a
+// 14k-line component that cannot be mounted in isolation, and the twenty other
+// `e.source === activeWin` gates in the same handler have no coverage at all.
+// Asserting on the source keeps the guard cheap and honest about its reach —
+// it catches a gate being deleted, a `file:` pin regressing to the
+// caller-supplied value, and (the last test) a gate that is written but cannot
+// execute. It claims nothing beyond that: it does not prove the relay behaves
+// correctly, only that the control is present and reachable.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = readFileSync(join(import.meta.dir, '..', 'client', 'app.jsx'), 'utf8');
+
+/** The body of one `else if (m.dgn === '<name>' …)` branch, up to the next one. */
+function branch(name: string): string {
+  const start = SRC.indexOf(`m.dgn === '${name}'`);
+  expect(start, `branch for ${name} not found in app.jsx`).toBeGreaterThan(-1);
+  const rest = SRC.slice(start + name.length);
+  const end = rest.indexOf('} else if (m.dgn ===');
+  return rest.slice(0, end === -1 ? 2000 : end);
+}
+
+describe('canvas → shell comment relays are scoped to the active canvas', () => {
+  // The comment relays, plus the three shell-control branches that were
+  // ungated alongside them: `shell-shortcut` (reload / panel toggles /
+  // Export + Handoff dialogs), and `open-export` / `open-timeline-request`,
+  // which reach the same dialogs from the in-canvas toolbar and context menu.
+  // All five are actions a user takes INSIDE the canvas in view; none has a
+  // reason to be honoured from a background frame.
+  for (const name of [
+    'comment-submit',
+    'comment-patch',
+    'comment-delete',
+    'shell-shortcut',
+    'open-export',
+    'open-timeline-request',
+  ]) {
+    test(`${name} is gated on e.source === activeWin`, () => {
+      expect(branch(name)).toContain('e.source === activeWin');
+    });
+  }
+
+  test('comment-submit pins the target file to activePath, never the payload', () => {
+    const body = branch('comment-submit');
+    // The file the comment lands on is the one the user is looking at.
+    expect(body).toContain('file: activePath');
+    // A canvas-supplied target would let a background iframe pick the victim.
+    expect(body).not.toContain('file: p.file');
+  });
+
+  test('comment-patch / comment-delete only accept ids owned by the active canvas', () => {
+    // A bare id would otherwise reach any comment in the project — and these
+    // two verbs change or remove somebody else's note (ws.ts refuses both for a
+    // viewer session for exactly that reason).
+    expect(branch('comment-patch')).toContain('ownsActiveComment(m.id)');
+    expect(branch('comment-delete')).toContain('ownsActiveComment(m.id)');
+  });
+
+  // The above only prove the gate is WRITTEN. This proves it can RUN.
+  //
+  // House style declares `const activeWin` block-locally inside each `else if`
+  // branch, so a branch that compares against `activeWin` without declaring it
+  // reads exactly like a working gate while throwing `ReferenceError` at
+  // runtime — fail-closed, but it takes the legitimate path down with it and
+  // silently reopens the moment anything introduces an outer binding. That is
+  // not hypothetical: the first cut of this fix shipped it, and every
+  // string-matching assertion above stayed green.
+  test('every activeWin comparison has a declaration, derived from activePath', () => {
+    // Line comments are blanked first — the prose in this handler quotes the
+    // gate expression, and a comment is not a use.
+    const CODE = SRC.split('\n')
+      .map((l) => l.replace(/^\s*\/\/.*$/, ''))
+      .join('\n');
+    const BRANCH_START = /\b(?:else )?if \(m\.dgn ===/g;
+    const starts = [...CODE.matchAll(BRANCH_START)].map((m) => m.index ?? 0);
+    const undeclared: string[] = [];
+
+    // Both idioms count: the `===` gate used by the comment relays and the
+    // `!== … return` early-exit form five other branches use. Checking only
+    // one lets a branch convert to the other and slip the check.
+    for (const use of [...CODE.matchAll(/e\.source [!=]== activeWin/g)].map((m) => m.index ?? 0)) {
+      // Nearest branch boundary at or before this usage.
+      const open = starts.filter((s) => s < use).pop() ?? 0;
+      // `= activePath` is the load-bearing half: a declaration that derives the
+      // window from the MESSAGE (`iframesRef.current.get(m.file)`) instead of
+      // from app state satisfies a bare `const activeWin` check while handing
+      // the attacker the very comparison the gate exists to make.
+      if (!/const activeWin =\s*\n?\s*activePath/.test(CODE.slice(open, use))) {
+        undeclared.push(
+          CODE.slice(open, open + 60)
+            .split('\n')[0]!
+            .trim()
+        );
+      }
+    }
+
+    expect(
+      undeclared,
+      `activeWin used without a block-local declaration in: ${undeclared.join(' | ')}`
+    ).toEqual([]);
+  });
+});