@1agh/maude 0.58.1 → 0.58.3

package/apps/studio/.ai/cache/_stats.json

@@ -1,7 +1,7 @@
 {
   "hits": {},
   "misses": {
-    "security": 1
+    "security": 2
   },
   "since": 1783681711349
 }

package/apps/studio/acp/bridge.ts

@@ -147,6 +147,8 @@ export interface AcpBridgeOptions {
   onUsage?: (usage: BridgeUsage) => void;
   /** Override for `PERMISSION_TIMEOUT_MS` (tests only — production always gets the real default). */
   permissionTimeoutMs?: number;
+  /** Override for `CANCEL_ESCALATION_MS` (tests only — production always gets the real default). */
+  cancelEscalationMs?: number;
 }
 
 /**
@@ -561,6 +563,16 @@ export function newSessionParams(
 // the security control, so failing open would defeat the point.
 const PERMISSION_TIMEOUT_MS = 120_000;
 
+// SECURITY/RELIABILITY (issue-82) — how long cancel() waits for the
+// in-flight turn to actually END after asking the adapter cooperatively,
+// before forcing it to end itself. A wedged subprocess — or one that never
+// implemented `session/cancel` at all — must not be able to leave the Stop
+// button permanently inert (see `cancel()`'s doc comment). Bounded like
+// PERMISSION_TIMEOUT_MS/INITIALIZE_TIMEOUT_MS above: generous enough not to
+// misfire on a merely-slow cancel ack, short enough that Stop still feels
+// responsive.
+const CANCEL_ESCALATION_MS = 5_000;
+
 // SECURITY (ethical-hacker finding, retroactive review) — a single agent turn
 // can legitimately issue several tool calls back to back (a burst is normal
 // agent behavior, not a bug — e.g. prompt-injected content directing several
@@ -624,6 +636,32 @@ export class AcpBridge {
   // running establishSession() and stomping the single shared `replaying` flag.
   private sessionPromises = new Map<string, Promise<string>>();
   private currentSession: string | null = null; // the in-flight prompt's session
+  // issue-82 — every prompt() call currently racing a forced-cancellation
+  // (see `prompt()`), so cancel()/stop() can force ANY of them to settle
+  // when the adapter doesn't cooperate, instead of leaving one hanging
+  // forever. A Set, not a single field, on purpose (ethical-hacker finding):
+  // `handlePrompt` has no reentrancy guard, so a duplicate/replayed `prompt`
+  // frame for the same chat can start a SECOND overlapping turn on this
+  // bridge. A singleton field would be silently overwritten by the second
+  // turn's registration and then nulled by whichever turn settles first —
+  // even a normal, uncancelled completion — leaving an EARLIER, genuinely
+  // wedged turn permanently unescalatable and reopening this exact bug.
+  // Tracking every in-flight turn means cancel() always finds (and can
+  // force-end) whichever one is actually stuck, regardless of ordering.
+  private pendingTurns = new Set<{ reject: (err: Error) => void; settled: Promise<void> }>();
+  // issue-82 / ethical-hacker finding — set for good, synchronously, at the
+  // very top of `stop()`. `stop()` kills the subprocess but cannot make it
+  // die instantly (SIGTERM, not a synchronous severance of the ndjson
+  // stream), so a message the child had already started writing can still
+  // arrive and be dispatched afterward. Without this flag a
+  // `requestPermission`/`unstable_createElicitation` call landing in that
+  // window would register a fresh pending entry as if the session were
+  // still live — and a stale client `permission-response` could later
+  // resolve it as an "allow" against a session the user was told was
+  // closed. Checked at the top of both handlers below; never reset (a
+  // stopped bridge is torn out of the `bridges` map by `reap()` and never
+  // reused — see acp/index.ts).
+  private stopped = false;
   /** Sessions whose bootstrap brief already hit the transcript (audit record). */
   private briefLogged = new Set<string>();
   private starting: Promise<void> | null = null;
@@ -859,8 +897,31 @@ export class AcpBridge {
     }
   }
 
-  /** Spawn + handshake exactly once; concurrent callers share the same promise. */
+  /** Spawn + handshake exactly once; concurrent callers share the same promise.
+   *
+   * issue-82 follow-up (ethical-hacker finding on the fix itself) — once a
+   * bridge has been `stop()`'d, refuse to resurrect it rather than silently
+   * respawning. `stop()` is currently ONLY reached via `reap()` (which also
+   * deletes the bridge from `index.ts`'s map, so a fresh `AcpBridge` — with
+   * `stopped` correctly false — is created for the next turn) OR via THIS
+   * file's own cancel()-escalation path (`cancel()` calling `stop()` when a
+   * turn doesn't end in time), which does NOT go through `reap()` and leaves
+   * the SAME, now-permanently-`stopped` instance live in that map. Without
+   * this guard, a merely-slow (not malicious) turn that just misses
+   * `CANCEL_ESCALATION_MS` would respawn a working-looking subprocess whose
+   * `requestPermission`/`unstable_createElicitation` handlers silently
+   * auto-deny forever (the `stopped` check in both) — a hard-to-diagnose,
+   * silent regression of the permission gate with no visible error. Throwing
+   * here instead surfaces a clear, actionable error through the SAME
+   * try/catch every caller already has (`handlePrompt` etc.), so the failure
+   * is loud, not silent — the user is prompted to start a new chat, whose
+   * `getOrCreateEntry` makes a brand-new bridge with `stopped` unset. */
   async ensureStarted(): Promise<void> {
+    if (this.stopped) {
+      throw new Error(
+        'This AI editing session was stopped and cannot be reused — start a new chat.'
+      );
+    }
     if (this.conn) return;
     if (!this.starting) {
       this.starting = this.start().finally(() => {
@@ -1139,6 +1200,12 @@ export class AcpBridge {
         void this.appendTranscript({ role: 'agent', update: u }, seq);
       },
       requestPermission: (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
+        // issue-82 / ethical-hacker finding — a message the child had already
+        // started writing before `stop()` killed it can still be dispatched
+        // in the brief window before the process actually dies. Fail closed
+        // immediately rather than register a pending entry a stale client
+        // response could later resolve as "allow" against a torn-down session.
+        if (this.stopped) return Promise.resolve({ outcome: { outcome: 'cancelled' } });
         // Milestone B (retires DDR-125 F2's blanket auto-approve) — the
         // permission POLICY is now the selected session mode (sourced from
         // Claude Code itself): `bypassPermissions`/`dontAsk` short-circuit
@@ -1195,6 +1262,11 @@ export class AcpBridge {
       unstable_createElicitation: (
         params: CreateElicitationRequest
       ): Promise<CreateElicitationResponse> => {
+        // issue-82 / ethical-hacker finding — same fail-closed guard as
+        // `requestPermission` above, and for the same reason: a message
+        // already in flight from the child when `stop()` fires must not
+        // register a pending entry a stale client response could resolve.
+        if (this.stopped) return Promise.resolve({ action: 'decline' });
         // feature-acp-ask-user-question — mirrors requestPermission's shape
         // exactly. Fires for BOTH `AskUserQuestion` and any MCP-server
         // elicitation (see the plan's Research section) — the toolCallId/
@@ -1316,10 +1388,40 @@ export class AcpBridge {
       }
     }
     await this.appendTranscript({ role: 'user', text });
-    const response = await conn.prompt({
-      sessionId,
-      prompt: [{ type: 'text', text }],
+
+    // issue-82 — race the real adapter response against a forced rejection
+    // `cancel()`/`stop()` can trigger. `turn.settled` resolves the moment the
+    // RACE ITSELF is decided (security-auditor finding: resolving it only
+    // after the transcript-append below would let a slow disk write
+    // masquerade as a still-hanging turn and trigger a needless escalation
+    // even though the real response already won) — the append is bookkeeping
+    // on an already-settled outcome, not part of what `cancel()` waits on.
+    let resolveSettled!: () => void;
+    const settled = new Promise<void>((resolve) => {
+      resolveSettled = resolve;
     });
+    const turn: { reject: (err: Error) => void; settled: Promise<void> } = {
+      reject: () => {}, // replaced synchronously below before this can matter
+      settled,
+    };
+    const forced = new Promise<never>((_, reject) => {
+      turn.reject = reject;
+    });
+    let response: PromptResponse;
+    // `add` happens INSIDE the try (not before it) so a synchronous throw
+    // from `conn.prompt()` still reaches the `finally` and removes `turn` —
+    // otherwise it would leak in the Set forever, and a later cancel()
+    // calling `turn.reject()` on it would reject a `forced` promise nothing
+    // is racing anymore (an unhandled rejection).
+    try {
+      this.pendingTurns.add(turn);
+      const promptCall = conn.prompt({ sessionId, prompt: [{ type: 'text', text }] });
+      promptCall.catch(() => {}); // a forced-reject race must not surface as an unhandled rejection
+      response = await Promise.race([promptCall, forced]);
+    } finally {
+      this.pendingTurns.delete(turn);
+      resolveSettled();
+    }
     await this.appendTranscript({ role: 'stop', stopReason: response.stopReason });
     return { stopReason: response.stopReason };
   }
@@ -1548,24 +1650,72 @@ export class AcpBridge {
     }
   }
 
-  /** Cancel the in-flight turn (no-op if nothing is running). */
-  async cancel(): Promise<void> {
+  /** Deny pending permissions/elicitations, then fire the cooperative ACP
+   *  `session/cancel` request — WITHOUT waiting for it to settle. A wedged
+   *  or non-cooperating subprocess can leave this RPC unanswered forever (or
+   *  reject it immediately if `session/cancel` isn't even implemented);
+   *  either way this must never make a caller wait on it, so both
+   *  `cancel()`'s escalation and `stop()`'s teardown stay bounded no matter
+   *  what the adapter does with the request. */
+  private requestCancel(): void {
     this.denyAllPendingPermissions();
     this.declineAllPendingElicitations();
     if (this.conn && this.currentSession) {
-      try {
-        await this.conn.cancel({ sessionId: this.currentSession });
-      } catch {
-        /* turn may already have finished */
-      }
+      this.conn.cancel({ sessionId: this.currentSession }).catch(() => {
+        /* turn may already have finished, or the adapter doesn't implement cancel */
+      });
     }
   }
 
-  /** Tear down: cancel, kill the subprocess, drop all handles + sessions. */
+  /**
+   * Cancel the in-flight turn (no-op if nothing is running).
+   *
+   * Fires the cooperative ACP `session/cancel` request, but does not simply
+   * trust it: a wedged subprocess — or one that never implemented
+   * `session/cancel` at all — can leave the pending `prompt()` call
+   * unsettled forever, which used to mean Stop silently did nothing
+   * (issue-82): the client's turn loop never exits, `busy` stays true, and
+   * the Stop button stays visible but inert. Any turn that hasn't actually
+   * ended within `CANCEL_ESCALATION_MS` of asking is forced to end — reject
+   * its pending `prompt()` — so it always settles as an error the client
+   * surfaces, instead of hanging. If ANY turn needed forcing, the whole
+   * bridge (one subprocess serving every turn) is presumed wedged and torn
+   * down.
+   */
+  async cancel(): Promise<void> {
+    this.requestCancel();
+    const turns = [...this.pendingTurns];
+    if (turns.length === 0) return; // nothing in flight to escalate
+    const escalated = await Promise.all(
+      turns.map(async (turn) => {
+        const result = await withTimeout(
+          turn.settled,
+          this.opts.cancelEscalationMs ?? CANCEL_ESCALATION_MS
+        );
+        if (result !== TIMED_OUT) return false;
+        turn.reject(new Error('Cancelled — the agent did not respond in time and was stopped.'));
+        return true;
+      })
+    );
+    if (escalated.some(Boolean)) await this.stop();
+  }
+
+  /** Tear down: cancel, kill the subprocess, drop all handles + sessions.
+   *  Never blocks on the cooperative cancel ask (see `requestCancel`) — a
+   *  wedged subprocess must not be able to make `stop()` hang too. */
   async stop(): Promise<void> {
-    await this.cancel();
-    this.denyAllPendingPermissions(); // belt-and-suspenders — cancel() already does this
-    this.declineAllPendingElicitations(); // ditto
+    // Fail-closed from this instant on — see the `stopped` field comment.
+    this.stopped = true;
+    this.requestCancel();
+    // Any turn(s) still in flight — a direct stop() with no prior cancel(),
+    // or cancel()'s own escalation calling back in here. Force them to
+    // settle before the connection dies underneath them, so the client's
+    // turn loop always exits instead of awaiting a promise that can now
+    // never resolve.
+    for (const turn of this.pendingTurns) {
+      turn.reject(new Error('Stopped — the AI editing session was closed.'));
+    }
+    this.pendingTurns.clear();
     try {
       this.proc?.kill();
     } catch {

package/apps/studio/annotations-bindings.ts

@@ -17,18 +17,69 @@ import {
   rotatePoint,
   type Stroke,
   strokeBBox,
+  strokeHitTest,
   strokeRotation,
 } from './annotations-model.ts';
 
-/** Hosts an arrow endpoint can attach to (shapes + cards, FigJam set). */
+/**
+ * The largest bbox a TEXT stroke may present as a bind target, PER AXIS.
+ *
+ * A `TextStroke` has no stored `w`/`h` — `strokeBBox` SYNTHESIZES one from the
+ * content (`max(8, longest * fontSize * 0.55)` wide). So a long single line can
+ * project a bind strip tens of thousands of px wide, and `bindCandidate` scans
+ * topmost-first with no area preference: one such stroke would silently become a
+ * board-wide magnet that steals every endpoint the user drags. Text bigger than
+ * a plausible label is therefore not offered as a host at all (DDR-216 D9).
+ */
+export const MAX_TEXT_BIND_W = 1200;
+export const MAX_TEXT_BIND_H = 480;
+
+/**
+ * Hosts an arrow endpoint can attach to (shapes + cards, FigJam set).
+ *
+ * **Widened to `text` + `section` (DDR-216 D9).** FigJam binds connectors to
+ * anything, and on the only real board measured 2/2 connectors had at least one
+ * endpoint Maude could not bind — so an imported connector degraded to a frozen
+ * line. It is also a plain native gap: you could not attach an arrow to a text
+ * label or a section, independent of import.
+ *
+ * Three deliberate exclusions, each closing a regression the naive widening
+ * would have introduced:
+ *
+ *  1. **ANCHORED text is still not bindable.** `bindCandidate`/`anchorPoint`/
+ *     `recomputeBoundArrows` call `strokeBBox(s)` WITHOUT the anchors map, and
+ *     for a text stroke with `anchorId` that returns `null`. Admitting it would
+ *     mint a bind that `anchorPoint` can never resolve — and `applyEnd` would
+ *     keep it (it only strips when the host stops being bindable), freezing the
+ *     arrow at stale coordinates forever. That is strictly worse than today's
+ *     honest "strip the bind, freeze the endpoint". Anchored text lives inside a
+ *     host shape which is itself bindable, so nothing is lost: bind to the shape.
+ *  2. **Oversized text is not offered** — see `MAX_TEXT_BIND_W`/`_H`.
+ *  3. **Groups are not bindable by construction** — Maude groups are a flat
+ *     `groupIds[]` tag array, not addressable objects. A group-targeted import
+ *     endpoint falls back to the group's geometric bbox and is reported.
+ */
 export function isBindable(s: Stroke): boolean {
-  return (
+  if (
     s.tool === 'rect' ||
     s.tool === 'ellipse' ||
     s.tool === 'polygon' ||
     s.tool === 'sticky' ||
     s.tool === 'image'
-  );
+  ) {
+    return true;
+  }
+  if (s.tool === 'section') return true;
+  if (s.tool === 'text') {
+    if (s.anchorId) return false; // (1) — no resolvable bbox without the anchors map
+    const bb = strokeBBox(s);
+    // Per-AXIS, not an area product: an area cap is satisfiable by a very wide,
+    // very short strip, which is precisely the board-wide magnet shape. 4 000
+    // chars at the fontSize floor of 8 gives w ≈ 17 600 × h ≈ 9.6 — area 168 960,
+    // comfortably under a 640×480 product (post-implementation review F8).
+    return !!bb && bb.w > 0 && bb.h > 0 && bb.w <= MAX_TEXT_BIND_W && bb.h <= MAX_TEXT_BIND_H; // (2)
+  }
+  return false;
 }
 
 /** Bind proximity threshold in world px at zoom 1 (Excalidraw's 15 px). */
@@ -78,6 +129,20 @@ export function bindCandidate(
     ) {
       continue;
     }
+    // A SECTION is a large container, and the natural gesture is to draw one
+    // AROUND existing notes — which puts it later in the array, i.e. topmost.
+    // Testing its raw bbox would make the whole interior a magnet, so every
+    // arrow drawn between two stickies inside a section would bind to the
+    // section instead. `strokeHitTest` already encodes the right rule (a section
+    // is grabbed by its BORDER or its label chip; the interior stays
+    // click-through), so defer to it rather than inventing a second geometry.
+    //
+    // Deliberately NOT "prefer the smallest containing bbox": containment here
+    // is over a bbox INFLATED by `threshold`, so smallest-area lets an 8×8 dot
+    // 14 px AWAY beat the large rect the pointer is actually inside — and it
+    // inverts the visual invariant, letting a shape hidden behind an opaque one
+    // win a bind the user cannot see happening (DDR-216 D9 fix 4).
+    if (s.tool === 'section' && !strokeHitTest(s, wx, wy, threshold)) continue;
     return {
       hostId: s.id,
       nx: snapMagnet(clamp01((wx - bb.x) / bb.w)),
@@ -155,7 +220,21 @@ export function recomputeBoundArrows(strokes: readonly Stroke[]): Stroke[] {
         }
       }
       const pt = anchorPoint(host, effective.nx, effective.ny);
-      if (!pt) return;
+      if (!pt) {
+        // The host is bindable but its bbox is unresolvable right now (e.g. a
+        // text stroke whose anchors map isn't reachable from here). Returning
+        // silently would KEEP a bind that can never be honoured — the arrow
+        // would freeze at stale coordinates permanently, across save/load,
+        // while still claiming to be attached. Strip it instead: the arrow
+        // survives unbound with its endpoint frozen, which is the same honest
+        // degradation a deleted host already gets. (DDR-216 D9 fix 2 — inert
+        // before the `isBindable` widening, load-bearing after it.)
+        const copy: ArrowStroke = { ...next };
+        delete copy[end === 'start' ? 'startBind' : 'endBind'];
+        next = copy;
+        mutated = true;
+        return;
+      }
       if (end === 'start') {
         if (next.x1 !== pt[0] || next.y1 !== pt[1]) {
           next = { ...next, x1: pt[0], y1: pt[1] };

package/apps/studio/api.ts

@@ -5260,7 +5260,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // `loadCanvasMeta` call the DDR-093 DS-map loop below already makes for
     // non-path-owned (`ui/`) canvases — no extra I/O for the common case.
     const canvasKinds: Record<string, string> = {};
-    const NOTABLE_KINDS = new Set(['reconstructed-experimental']);
+    // DDR-216 D7 adds `imported-figma`. The badge deliberately reads as
+    // THIRD-PARTY CONTENT rather than as provenance-therefore-trustworthy: a
+    // clean "imported from Figma" stamp otherwise makes the most
+    // attacker-influenced artifact in the tree look like real design work, to a
+    // human AND to `design-system-keeper` / the critic panel.
+    const NOTABLE_KINDS = new Set(['reconstructed-experimental', 'imported-figma']);
     const defaultDs = cfg.defaultDesignSystem || cfg.designSystems?.[0]?.name || 'project';
     // A file under `system/<folder>/` belongs to the DS that owns that folder —
     // path-authoritative, because specimens/ui_kits rarely carry a sidecar

package/apps/studio/bin/_fetch-asset.mjs

@@ -39,9 +39,9 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { lookup } from 'node:dns/promises';
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync } from 'node:fs';
 import { isIP } from 'node:net';
-import { join, resolve, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 // A real browser UA — some CDNs (wikimedia) 403 a bare curl/UA; the memory
@@ -202,7 +202,7 @@ export function classifyAddress(addr) {
  * FetchAssetError (code 3) on anything else — non-https scheme, embedded
  * credentials, missing host.
  */
-export function parseHttpsTarget(rawUrl) {
+export function parseHttpsTarget(rawUrl, opts = {}) {
   let u;
   try {
     u = new URL(rawUrl);
@@ -221,9 +221,71 @@ export function parseHttpsTarget(rawUrl) {
   if (!Number.isInteger(port) || port < 1 || port > 65535) {
     throw new FetchAssetError(3, `bad port ${u.port}`);
   }
+  // DDR-216 D4 — an OPTIONAL host allowlist, at the gate rather than at the
+  // caller. Absent (the default) = today's unrestricted behaviour, so the
+  // existing moodboard/research callers are untouched. The Figma lane always
+  // passes it.
+  //
+  // Matching is exact-or-DOTTED-SUFFIX, never a bare `endsWith`: `endsWith(
+  // 'figma.com')` admits `evil-figma.com`, and `endsWith('.amazonaws.com')`
+  // admits every S3 bucket on earth.
+  //
+  // This is a REACH control (which endpoint), never a CONTENT control — the
+  // Figma render bucket is a SHARED object store any account can write into,
+  // so the byte-level sniff below is what actually protects the tree. And it
+  // NARROWS the IP gate, never replaces it: an allowlisted hostname that
+  // resolves to 127.0.0.1 is still refused by `resolveSafeIp`.
+  if (opts.allowHosts?.length) {
+    const h = host.toLowerCase();
+    const ok = opts.allowHosts.some((suffix) => {
+      const s = String(suffix).toLowerCase().replace(/^\./, '');
+      return h === s || h.endsWith(`.${s}`);
+    });
+    if (!ok) throw new FetchAssetError(3, `host not in this lane's allowlist: ${safeHostLabel(h)}`);
+  }
+  // DDR-216 D4 — the Figma lane pins 443. Named as NEW logic rather than
+  // assumed: this function accepts 1–65535 by default and always has.
+  if (opts.pinPort443 && port !== 443) {
+    throw new FetchAssetError(3, `this lane requires port 443 (got ${port})`);
+  }
   return { host, port };
 }
 
+/**
+ * A hostname reduced to a charset-validated token before it can be printed.
+ *
+ * DDR-216 D10: this verb's output is read BY an agent, so an upstream-controlled
+ * string must never appear verbatim in a message. A DNS label charset is narrow
+ * enough to be safe and specific enough to diagnose.
+ */
+function safeHostLabel(host) {
+  const cleaned = String(host)
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]/g, '');
+  return cleaned.slice(0, 253) || '(unprintable)';
+}
+
+/**
+ * The `--raw-out` accept set: everything `sniffImageExt` accepts, PLUS SVG.
+ *
+ * `sniffImageExt` is deliberately NOT modified — it is the type gate the
+ * moodboard lane depends on, and a standing test asserts it still returns null
+ * for `<svg`/`<?xml`. The SVG probe below reuses the exact leading-token shape
+ * `_import-asset.mjs`'s own `svgPreParseReject` uses, so a payload accepted here
+ * is one that lane will actually attempt to parse (and then sanitize).
+ */
+export function sniffStagedKind(bytes) {
+  const raster = sniffImageExt(bytes);
+  if (raster) return raster;
+  // Text probe on the first bytes only — never decode the whole body to guess.
+  const head = Buffer.from(bytes.subarray(0, 256)).toString('utf8');
+  // Deliberately NARROWER than `svgPreParseReject`'s own leading-token set: a
+  // bare `<!--` prologue is legal SVG but it is also what lets an arbitrary text
+  // payload masquerade as one (review F2), and no Figma export starts with it.
+  // The full DDR-167 lane still validates properly downstream.
+  return /^\s*(<\?xml|<svg)/i.test(head) ? 'svg' : null;
+}
+
 // ── image sniff + naming ─────────────────────────────────────────────────────
 
 /**
@@ -408,10 +470,91 @@ export async function fetchAsset({
   designRootRel = '.design',
   maxBytes = DEFAULT_MAX_BYTES,
   maxTime = DEFAULT_MAX_TIME,
+  allowHosts,
+  pinPort443 = false,
+  rawOut = null,
+  rawRoot = null,
 }) {
-  const { host, port } = parseHttpsTarget(url);
+  const { host, port } = parseHttpsTarget(url, { allowHosts, pinPort443 });
   const pinIp = await resolveSafeIp(host);
 
+  // ── `--raw-out` (DDR-216 D11) ──────────────────────────────────────────────
+  //
+  // Download under the FULL network gate (IP classification, DNS pin, redirect
+  // ban, size/time caps, host allowlist) but write to a CALLER-SUPPLIED path
+  // instead of `assets/`, and do NOT content-address or name the file.
+  //
+  // Why this exists: D11 composes two already-reviewed gates rather than
+  // widening one. A Figma vector export is an SVG, and this helper's raster-only
+  // sniff is load-bearing for its OTHER caller (the DDR-147 moodboard lane,
+  // where URLs are research-harvested and there is no allowlist at all). So the
+  // Figma lane stages the bytes here and hands them to `_import-asset.mjs`'s
+  // DDR-167 SVG lane (allowlist DOM-sanitize → SVGO validity gate) before
+  // anything is named or lands in the versioned tree.
+  //
+  // IT STILL SNIFFS. `--raw-out` must never mean "skip the type gate" — that
+  // would turn the one reviewable downloader into an unsniffed one (HTML, JS,
+  // polyglots, archives) for the next caller who copies it. It sniffs against
+  // an EXTENDED accept set; `sniffImageExt` itself is untouched, which is what
+  // keeps the standing "sniffImageExt still rejects SVG" test literally true.
+  if (rawOut) {
+    // CONTAINMENT (post-implementation review F2). Without this, `--raw-out`
+    // was an arbitrary-file-write primitive on the ONE helper whose whole job
+    // is to be the safe downloader: `resolve()` + `renameSync()` with no root
+    // relationship, no charset assertion, and a type gate a leading `<!--`
+    // satisfies. An agent that can run `maude design fetch-asset` (ACP
+    // default-allows `Bash(maude:*)`) could have written remote bytes over
+    // `CLAUDE.md` — durable prompt injection.
+    //
+    // So the mode now REQUIRES the caller to declare the directory it owns, and
+    // the target must resolve inside it. The Figma lane passes its per-run
+    // staging dir; there is no way to express "anywhere".
+    if (!rawRoot) {
+      throw new FetchAssetError(2, '--raw-out requires --raw-root (the directory the caller owns)');
+    }
+    // BOTH sides get realpath'd, or neither. On macOS `/var` and `/tmp` are
+    // themselves OS-level symlinks (`-> /private/var`, `-> /private/tmp`), so
+    // realpath'ing only the root compares `/private/var/…` against `/var/…` and
+    // rejects EVERY legitimate staging path — which is exactly how this shipped
+    // and why the first real import skipped all 29 of its assets. Same trap
+    // DDR-172 Decision 1 documents for its own symlink check.
+    //
+    // The target does not exist yet, so realpath its PARENT (which does — the
+    // caller made the staging dir) and rebuild the leaf onto it.
+    const rootAbs = realpathSync(resolve(rawRoot));
+    const requested = resolve(rawOut);
+    const parentAbs = realpathSync(dirname(requested));
+    const outAbs = join(parentAbs, basename(requested));
+    if (outAbs !== rootAbs && !outAbs.startsWith(rootAbs + sep)) {
+      throw new FetchAssetError(6, '--raw-out must resolve inside --raw-root');
+    }
+    // Never overwrite: a staged download is always a fresh file, so an existing
+    // target means either a collision or an attempt to clobber something.
+    if (existsSync(outAbs)) {
+      throw new FetchAssetError(6, '--raw-out target already exists');
+    }
+    const tmpRaw = `${outAbs}.part`;
+    try {
+      curlDownload({ url, host, port, pinIp, tmpAbs: tmpRaw, maxBytes, maxTime });
+      let data;
+      try {
+        data = readFileSync(tmpRaw);
+      } catch {
+        throw new FetchAssetError(4, 'download produced no file');
+      }
+      if (data.length === 0) throw new FetchAssetError(4, 'downloaded empty body');
+      if (data.length > maxBytes) throw new FetchAssetError(4, `file exceeds ${maxBytes} bytes`);
+      const kind = sniffStagedKind(data);
+      if (!kind) {
+        throw new FetchAssetError(5, 'not a png/jpg/gif/webp/svg payload (HTML/script rejected)');
+      }
+      renameSync(tmpRaw, outAbs);
+      return { ref: null, path: outAbs, name: null, bytes: data.length, ext: kind };
+    } finally {
+      rmSync(tmpRaw, { force: true });
+    }
+  }
+
   const { assetsDir } = containedAssetPath(root, designRootRel, 'placeholder.png');
   mkdirSync(assetsDir, { recursive: true });
   const tmpAbs = join(
@@ -476,6 +619,21 @@ function parseArgv(argv) {
       case '--max-time':
         out.maxTime = Number(argv[++i]);
         break;
+      // DDR-216 D4/D11 — all three default to today's behaviour, so every
+      // existing caller of this helper is untouched.
+      case '--allow-host':
+        if (!out.allowHosts) out.allowHosts = [];
+        out.allowHosts.push(argv[++i]);
+        break;
+      case '--pin-port-443':
+        out.pinPort443 = true;
+        break;
+      case '--raw-out':
+        out.rawOut = argv[++i];
+        break;
+      case '--raw-root':
+        out.rawRoot = argv[++i];
+        break;
       case '--json':
         out.json = true;
         break;
@@ -540,8 +698,14 @@ async function main() {
       designRootRel: opts.designRoot,
       maxBytes: opts.maxBytes,
       maxTime: opts.maxTime,
+      ...(opts.allowHosts ? { allowHosts: opts.allowHosts } : {}),
+      ...(opts.pinPort443 ? { pinPort443: true } : {}),
+      ...(opts.rawOut ? { rawOut: opts.rawOut } : {}),
+      ...(opts.rawRoot ? { rawRoot: opts.rawRoot } : {}),
     });
-    process.stdout.write(opts.json ? `${JSON.stringify(r)}\n` : `${r.ref}\n`);
+    // `--raw-out` has no canvas ref (it deliberately writes outside `assets/`),
+    // so print the staged path instead of a null.
+    process.stdout.write(opts.json ? `${JSON.stringify(r)}\n` : `${r.ref ?? r.path}\n`);
   } catch (err) {
     process.stderr.write(`fetch-asset: ${err.message}\n`);
     process.exit(err instanceof FetchAssetError ? err.code : 1);