@1agh/maude 0.22.0 → 0.23.0

package/plugins/design/dev-server/input-router.tsx

@@ -268,6 +268,16 @@ export interface UseInputRouterOptions {
   callbacks: RouterCallbacks;
   /** When false, listeners are not attached. Defaults to true. */
   enabled?: boolean;
+  /**
+   * Allowlist of action kinds this router is permitted to CLAIM (preventDefault
+   * + stopImmediatePropagation + dispatch). Any classified action outside the
+   * set is downgraded to `no-op` so it propagates untouched to other listeners.
+   * Omit to claim everything (the default — used by the full DesignCanvas
+   * router). The shell-owned comment mount layer passes a narrow set so it can
+   * coexist as an ANCESTOR capture-listener over a UI canvas's own router
+   * without swallowing select / context-menu / undo gestures it doesn't own.
+   */
+  claimableActions?: ReadonlySet<RouterAction['kind']>;
 }
 
 export function isEditableTarget(t: EventTarget | null): boolean {
@@ -295,13 +305,21 @@ export function isOverlayTarget(t: EventTarget | null): boolean {
 }
 
 export function useInputRouter(opts: UseInputRouterOptions): void {
-  const { hostRef, getActiveTool, isSpaceHeld, callbacks, enabled = true } = opts;
+  const { hostRef, getActiveTool, isSpaceHeld, callbacks, enabled = true, claimableActions } = opts;
 
   useEffect(() => {
     if (!enabled) return;
     const host = hostRef.current;
     if (!host) return;
 
+    // Downgrade any action this router isn't permitted to claim to no-op so it
+    // propagates untouched (no preventDefault / no dispatch). Identity pass-
+    // through when no allowlist is configured.
+    const claim = (action: RouterAction): RouterAction =>
+      claimableActions && action.kind !== 'no-op' && !claimableActions.has(action.kind)
+        ? { kind: 'no-op' }
+        : action;
+
     const dispatch = (action: RouterAction): void => {
       switch (action.kind) {
         case 'hover':
@@ -334,18 +352,20 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
     };
 
     const onPointerMove = (e: PointerEvent): void => {
-      const action = classify({
-        type: 'pointermove',
-        button: e.button,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        clientX: e.clientX,
-        clientY: e.clientY,
-        spaceHeld: isSpaceHeld?.() ?? false,
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'pointermove',
+          button: e.button,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          clientX: e.clientX,
+          clientY: e.clientY,
+          spaceHeld: isSpaceHeld?.() ?? false,
+          activeTool: getActiveTool(),
+        })
+      );
       dispatch(action);
     };
 
@@ -354,18 +374,20 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
       // their own clicks. The router is in capture phase, so we have to
       // bail HERE before classify can claim the event.
       if (isOverlayTarget(e.target)) return;
-      const action = classify({
-        type: 'pointerdown',
-        button: e.button,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        clientX: e.clientX,
-        clientY: e.clientY,
-        spaceHeld: isSpaceHeld?.() ?? false,
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'pointerdown',
+          button: e.button,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          clientX: e.clientX,
+          clientY: e.clientY,
+          spaceHeld: isSpaceHeld?.() ?? false,
+          activeTool: getActiveTool(),
+        })
+      );
       if (action.kind !== 'no-op') {
         // Suppress native behavior on every event the router claims —
         // button presses don't fire, inputs don't focus, the canvas
@@ -386,18 +408,20 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
      */
     const onMouseDown = (e: MouseEvent): void => {
       if (isOverlayTarget(e.target)) return;
-      const action = classify({
-        type: 'pointerdown',
-        button: e.button,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        clientX: e.clientX,
-        clientY: e.clientY,
-        spaceHeld: isSpaceHeld?.() ?? false,
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'pointerdown',
+          button: e.button,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          clientX: e.clientX,
+          clientY: e.clientY,
+          spaceHeld: isSpaceHeld?.() ?? false,
+          activeTool: getActiveTool(),
+        })
+      );
       if (action.kind !== 'no-op') {
         e.preventDefault();
         e.stopImmediatePropagation();
@@ -414,41 +438,55 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
       if (isOverlayTarget(e.target)) return;
       const tool = getActiveTool();
       const mod = e.metaKey || e.ctrlKey;
-      const wouldRoute =
-        tool === 'comment' || (tool === 'move' && mod && e.button === 0) || e.button === 2;
-      if (wouldRoute) {
+      // Map the click to the action kind the matching pointerdown would have
+      // produced, then honor the claim allowlist so a scoped router (the
+      // comment mount layer) doesn't suppress clicks it never claimed.
+      const wouldRouteKind: RouterAction['kind'] | null =
+        tool === 'comment'
+          ? 'drop-comment'
+          : tool === 'move' && mod && e.button === 0
+            ? 'select'
+            : e.button === 2
+              ? 'context-menu'
+              : null;
+      if (wouldRouteKind && (!claimableActions || claimableActions.has(wouldRouteKind))) {
         e.preventDefault();
         e.stopImmediatePropagation();
       }
     };
 
     const onContextMenu = (e: MouseEvent): void => {
+      const action = claim(
+        classify({
+          type: 'contextmenu',
+          clientX: e.clientX,
+          clientY: e.clientY,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          activeTool: getActiveTool(),
+        })
+      );
+      if (action.kind === 'no-op') return; // not ours to claim — let it bubble
       e.preventDefault();
       e.stopImmediatePropagation();
-      const action = classify({
-        type: 'contextmenu',
-        clientX: e.clientX,
-        clientY: e.clientY,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        activeTool: getActiveTool(),
-      });
       dispatch(action);
     };
 
     const onKeyDown = (e: KeyboardEvent): void => {
-      const action = classify({
-        type: 'keydown',
-        key: e.key,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        isEditable: isEditableTarget(e.target),
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'keydown',
+          key: e.key,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          isEditable: isEditableTarget(e.target),
+          activeTool: getActiveTool(),
+        })
+      );
       if (
         action.kind === 'tool' ||
         action.kind === 'escape' ||
@@ -486,7 +524,7 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
       } as EventListenerOptions);
       doc.removeEventListener('keydown', onKeyDown, true);
     };
-  }, [enabled, hostRef, getActiveTool, isSpaceHeld, callbacks]);
+  }, [enabled, hostRef, getActiveTool, isSpaceHeld, callbacks, claimableActions]);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/plugins/design/dev-server/server.ts

@@ -26,6 +26,7 @@ import { createFsWatch } from './fs-watch.ts';
 import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
+import { createSyncRuntime } from './sync/index.ts';
 import { type WsData, createWs, isLoopbackHost, parseCollabSlug } from './ws.ts';
 
 // Phase 19 / DDR-044 — covers the marketplace-cache-install gap where
@@ -199,6 +200,18 @@ await Bun.write(
 fsWatch.start();
 startHeapWatch();
 
+// Phase 9 Task 4 — bidirectional sync agent. No-op when the project isn't
+// linked to a hub (`.design/config.json` has no `linkedHub` field). Kicked
+// off after fsWatch so the agent's bus subscription receives every fs event.
+const syncRuntime = createSyncRuntime(ctx, collab ? { registry: collab.registry } : {});
+if (syncRuntime) {
+  try {
+    await syncRuntime.start();
+  } catch (err) {
+    console.error('[sync] startup failed — continuing in solo mode:', err);
+  }
+}
+
 const url = `http://localhost:${server.port}`;
 console.log(`\n  ${ctx.projectLabel} — local browser`);
 console.log('  ─────────────────────────────');
@@ -219,6 +232,11 @@ if (!process.env.NO_OPEN) {
 async function shutdown() {
   console.log('\n  Stopping…');
   fsWatch.stop();
+  try {
+    if (syncRuntime) await syncRuntime.stop();
+  } catch {
+    /* best-effort — provider sockets will be closed by process exit anyway */
+  }
   try {
     if (collab) await collab.registry.destroyAll();
   } catch {

package/plugins/design/dev-server/sync/agent.ts

@@ -0,0 +1,323 @@
+// Per-canvas bidirectional sync agent — Phase 9 Task 4.
+//
+// Wires together the Y.Doc the HocuspocusProvider keeps in sync with the hub
+// and the local on-disk files Claude Code reads + writes:
+//
+//   `.design/<slug>.html`           ←→ Y.Text  (Y_SYNC_TYPES.html)
+//   `.design/_comments/<slug>.json` ←→ Y.Array (Y_TYPES.comments)
+//   `.design/<slug>.annotations.svg`←→ Y.Map.svg (Y_TYPES.annotations)
+//
+// Provider is INJECTED — the agent doesn't import @hocuspocus/provider. This
+// keeps the orchestration testable with an in-memory pair of Y.Docs (no hub
+// process required) and makes the wiring layer (sync/index.ts) responsible
+// for the HocuspocusProvider lifecycle.
+//
+// Flow A — local edit (Claude `Write`, designer ⌘S) → hub:
+//   1. fs.watch fires → fs-mirror debounces 250ms → onRead({bytes, hash})
+//   2. echoGuard.consume(path, hash) returns false (genuine edit)
+//   3. applyHtmlToDoc(doc, str, agentOrigin) — emits Y op
+//   4. HocuspocusProvider broadcasts the op to hub → other peers
+//
+// Flow B — hub broadcasts other peer's edit → us:
+//   1. Provider applies update to doc with NON-agent origin
+//   2. doc.on('update') schedules a 800ms-debounced flush
+//   3. On flush: htmlFromDoc(doc) → echoGuard.record(path, hash) → atomicWrite
+//   4. fs.watch fires → fs-mirror reads → onRead matches the recorded echo
+//      → echoGuard.consume returns true → event dropped (no infinite loop)
+//
+// 800ms quiescence matches the existing Phase 8 collab room flush (DDR-051).
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import type * as Y from 'yjs';
+
+import { atomicWrite } from './atomic-write.ts';
+import {
+  Y_SYNC_TYPES,
+  annotationsFromDoc,
+  applyAnnotationsToDoc,
+  applyCommentsToDoc,
+  applyHtmlToDoc,
+  commentsFromDoc,
+  htmlFromDoc,
+} from './codec.ts';
+import { type EchoGuard, hashBytes } from './echo-guard.ts';
+
+export const DOC_FLUSH_MS = 800;
+
+export interface CanvasSyncPaths {
+  /** Absolute path to <designRoot>/<canvas>.html. */
+  html: string;
+  /** Absolute path to <designRoot>/_comments/<slug>.json. */
+  comments: string;
+  /** Absolute path to <designRoot>/<slug>.annotations.svg. */
+  annotations: string;
+}
+
+export interface CanvasSyncAgentOptions {
+  slug: string;
+  doc: Y.Doc;
+  paths: CanvasSyncPaths;
+  echoGuard: EchoGuard;
+  /** When true, the first reconcile() pushes local disk state up to the doc
+   *  instead of overwriting disk with the doc state. Cleared after first run. */
+  adopt?: boolean;
+  /** Override the 800ms flush. Tests use 0 to flush synchronously. */
+  flushMs?: number;
+  /** Injected for tests — defaults to atomicWrite. */
+  writer?: (path: string, bytes: string | Uint8Array) => void;
+}
+
+export interface CanvasSyncAgent {
+  readonly slug: string;
+  /** Set up the doc.on('update') listener. Idempotent. */
+  start(): void;
+  /**
+   * Reconcile disk ↔ doc once. In adopt mode, disk wins; otherwise doc
+   * (= hub) wins. Call this AFTER the provider's `synced` event.
+   */
+  reconcile(): Promise<void>;
+  /** Apply an fs event (from fs-mirror) to the doc, honoring echo guard. */
+  applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean;
+  /** Force the pending flush timer immediately. */
+  flush(): Promise<void>;
+  /** Stop all timers + listeners. */
+  stop(): void;
+  /** Test/inspection: the origin tag used on agent-applied transactions. */
+  readonly origin: object;
+}
+
+export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncAgent {
+  const { slug, doc, paths, echoGuard } = opts;
+  const flushMs = opts.flushMs ?? DOC_FLUSH_MS;
+  const writer = opts.writer ?? atomicWrite;
+  let adopt = !!opts.adopt;
+
+  const origin = Object.freeze({ agent: 'sync', slug });
+
+  let started = false;
+  let stopped = false;
+  let dirty = false;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Tracks the last-written contents for each path so we don't issue redundant
+  // disk writes when a flush fires but the projection hasn't changed.
+  let lastHtml: string | null = null;
+  let lastComments: string | null = null;
+  let lastAnnotations: string | null = null;
+
+  function onDocUpdate(_update: Uint8Array, updateOrigin: unknown): void {
+    if (stopped) return;
+    // Self-applied (we just synced from disk) — disk is already current.
+    if (updateOrigin === origin) return;
+    scheduleFlush();
+  }
+
+  function scheduleFlush(): void {
+    dirty = true;
+    if (flushMs === 0) {
+      // Synchronous mode for tests — fire on next microtask so the doc
+      // observer has fully run.
+      queueMicrotask(() => {
+        void flush();
+      });
+      return;
+    }
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush();
+    }, flushMs);
+  }
+
+  async function flush(): Promise<void> {
+    if (!dirty || stopped) return;
+    dirty = false;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    try {
+      writeHtmlIfChanged();
+      writeCommentsIfChanged();
+      writeAnnotationsIfChanged();
+    } catch (err) {
+      dirty = true;
+      console.error(`[sync/${slug}] flush failed:`, err);
+    }
+  }
+
+  function writeHtmlIfChanged(): void {
+    const next = htmlFromDoc(doc);
+    if (next === lastHtml) return;
+    const hash = hashBytes(next);
+    echoGuard.record(paths.html, hash);
+    writer(paths.html, next);
+    lastHtml = next;
+  }
+
+  function writeCommentsIfChanged(): void {
+    const next = commentsFromDoc(doc);
+    const serialized = next.length > 0 ? `${JSON.stringify(next, null, 2)}\n` : '';
+    if (serialized === lastComments) return;
+    if (serialized === '') {
+      // Empty comments — don't create an empty file; just remember the state.
+      lastComments = serialized;
+      return;
+    }
+    const hash = hashBytes(serialized);
+    echoGuard.record(paths.comments, hash);
+    writer(paths.comments, serialized);
+    lastComments = serialized;
+  }
+
+  function writeAnnotationsIfChanged(): void {
+    const next = annotationsFromDoc(doc);
+    const value = next ?? '';
+    if (value === lastAnnotations) return;
+    if (value === '') {
+      // Empty annotations — same handling as comments.
+      lastAnnotations = value;
+      return;
+    }
+    const hash = hashBytes(value);
+    echoGuard.record(paths.annotations, hash);
+    writer(paths.annotations, value);
+    lastAnnotations = value;
+  }
+
+  function applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean {
+    if (stopped) return false;
+    // Echo of our own atomicWrite — drop.
+    if (echoGuard.consume(evt.path, evt.hash)) return false;
+
+    const str = bytesToString(evt.bytes);
+    if (evt.path === paths.html) {
+      const changed = applyHtmlToDoc(doc, str, origin);
+      if (changed) lastHtml = htmlFromDoc(doc);
+      return changed;
+    }
+    if (evt.path === paths.comments) {
+      const parsed = tryParseJsonArray(str);
+      if (parsed === null) return false;
+      const changed = applyCommentsToDoc(doc, parsed, origin);
+      if (changed) lastComments = str;
+      return changed;
+    }
+    if (evt.path === paths.annotations) {
+      const changed = applyAnnotationsToDoc(doc, str, origin);
+      if (changed) lastAnnotations = str;
+      return changed;
+    }
+    return false;
+  }
+
+  async function reconcile(): Promise<void> {
+    if (stopped) return;
+    const localHtml = readLocal(paths.html);
+    const localComments = readLocal(paths.comments);
+    const localAnnotations = readLocal(paths.annotations);
+
+    const docHtml = htmlFromDoc(doc);
+    const docComments = commentsFromDoc(doc);
+    const docCommentsStr =
+      docComments.length > 0 ? `${JSON.stringify(docComments, null, 2)}\n` : '';
+    const docAnnotations = annotationsFromDoc(doc) ?? '';
+
+    if (adopt) {
+      // Push local up: doc takes its values from disk. Hub becomes our
+      // canonical view of this canvas. One-shot.
+      if (localHtml !== null) applyHtmlToDoc(doc, localHtml, origin);
+      if (localComments !== null) {
+        const parsed = tryParseJsonArray(localComments);
+        if (parsed !== null) applyCommentsToDoc(doc, parsed, origin);
+      }
+      if (localAnnotations !== null) applyAnnotationsToDoc(doc, localAnnotations, origin);
+      lastHtml = localHtml ?? '';
+      lastComments = localComments ?? '';
+      lastAnnotations = localAnnotations ?? '';
+      adopt = false;
+      return;
+    }
+
+    // Hub-wins (default): overwrite disk from doc when they differ.
+    lastHtml = docHtml;
+    lastComments = docCommentsStr;
+    lastAnnotations = docAnnotations;
+    if (localHtml !== docHtml) {
+      const hash = hashBytes(docHtml);
+      echoGuard.record(paths.html, hash);
+      writer(paths.html, docHtml);
+    }
+    if (docCommentsStr !== '' && localComments !== docCommentsStr) {
+      const hash = hashBytes(docCommentsStr);
+      echoGuard.record(paths.comments, hash);
+      writer(paths.comments, docCommentsStr);
+    }
+    if (docAnnotations !== '' && localAnnotations !== docAnnotations) {
+      const hash = hashBytes(docAnnotations);
+      echoGuard.record(paths.annotations, hash);
+      writer(paths.annotations, docAnnotations);
+    }
+  }
+
+  return {
+    slug,
+    origin,
+    start() {
+      if (started) return;
+      doc.on('update', onDocUpdate);
+      started = true;
+    },
+    reconcile,
+    applyFromFs,
+    flush,
+    stop() {
+      stopped = true;
+      doc.off('update', onDocUpdate);
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+    },
+  };
+}
+
+/* ---------------------------------------------------------------- helpers */
+
+function readLocal(p: string): string | null {
+  if (!existsSync(p)) return null;
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function bytesToString(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}
+
+// Reviver strips dangerous keys at parse time so a malicious hub-pushed
+// payload (or a planted commit) can't seed `__proto__` / `constructor` /
+// `prototype` own-properties into the comment objects yjs subsequently
+// serializes to other peers. Modern V8/Bun block direct Object.prototype
+// pollution at parse, but the reviver also closes the cross-machine
+// propagation surface where an unsafe `for…in` on a peer would re-pollute.
+// DDR-054 §2g (defender M2).
+function tryParseJsonArray(s: string): unknown[] | null {
+  try {
+    const parsed = JSON.parse(s, (key, value) => {
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+        return undefined;
+      }
+      return value;
+    });
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Re-export for the wiring layer to know which shared type holds HTML.
+export { Y_SYNC_TYPES };

package/plugins/design/dev-server/sync/atomic-write.ts

@@ -0,0 +1,103 @@
+// Atomic file writes for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// fs.watch on macOS/Linux fires on rename, so a non-atomic write (open →
+// truncate → write chunks → close) emits multiple watch events with partial
+// content. The agent's echo guard hashes the final content, so a partial-write
+// event would miss the hash match and incorrectly bubble the (truncated) state
+// up to Y.Doc — corrupting the live state.
+//
+// Pattern: open `<path>.tmp.<random-128-bit>` with O_CREAT|O_EXCL ('wx' in
+// Node), write bytes, close, `renameSync` to the final path. POSIX rename is
+// atomic when source + destination are on the same filesystem; the watch sees
+// the final-content-already-present rename event rather than a stream of
+// in-flight chunks. O_EXCL + 128-bit suffix defeats pre-created symlinks on
+// shared-tenant hosts (DDR-054 §2c — closes attacker Chain C + defender L1).
+//
+// File mode 0o600 on the staging file so other tenants on shared hosts can't
+// read in-flight content before the rename.
+//
+// Windows note: rename of a file the watcher has open returns EBUSY. The
+// plan's Task 4 step 4 acknowledges this as a known minor risk for v1.1;
+// the agent treats EBUSY as a transient error and retries once after a 25ms
+// jitter.
+
+import { randomBytes } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const RETRY_DELAY_MS = 25;
+// 'wx' = O_CREAT | O_EXCL — fails if the target already exists, including as
+// a dangling/live symlink. Plus O_TRUNC is implied; mode 0o600 sets owner-only.
+const TMP_OPEN_FLAGS = 'wx' as const;
+const TMP_OPEN_MODE = 0o600;
+
+/**
+ * Write `bytes` to `path` atomically. Returns the absolute path written
+ * (same as input — convenience for chaining).
+ *
+ * Bytes are written via Node's synchronous `openSync` with `O_CREAT|O_EXCL`
+ * (fails on pre-existing tmp / symlink), then `renameSync` moves it into
+ * place. 128-bit random suffix; mode 0o600. On POSIX the rename is atomic;
+ * on Windows there is a small window where the watcher may see a brief gap,
+ * retried once on EBUSY.
+ *
+ * `bytes` accepts string (UTF-8 encoded) or Uint8Array (written verbatim).
+ */
+export function atomicWrite(path: string, bytes: string | Uint8Array): string {
+  // Ensure the parent directory exists. Cheap (mkdirSync recursive is a no-op
+  // when present) and removes the per-canvas burden of creating _comments/
+  // before the agent's first flush.
+  mkdirSync(dirname(path), { recursive: true });
+  // 16 bytes = 32 hex chars = 128 bits. Unforgeable in practice against a
+  // local racer (vs. the prior 32-bit value which was brute-forceable in ms).
+  const suffix = randomBytes(16).toString('hex');
+  const tmp = `${path}.tmp.${suffix}`;
+  let fd: number | null = null;
+  try {
+    fd = openSync(tmp, TMP_OPEN_FLAGS, TMP_OPEN_MODE);
+    const buf = typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : Buffer.from(bytes);
+    writeSync(fd, buf, 0, buf.byteLength, 0);
+    closeSync(fd);
+    fd = null;
+    try {
+      renameSync(tmp, path);
+    } catch (err) {
+      if (isWindowsBusy(err)) {
+        // Brief retry — Windows watcher may hold a handle while reading the
+        // pre-rename target. 25ms is short enough to be invisible to the user
+        // and long enough to clear the typical fs.watch poll interval.
+        const start = Date.now();
+        while (Date.now() - start < RETRY_DELAY_MS) {
+          // Tight loop is OK for 25ms — keeps the call synchronous so callers
+          // can record the echo-guard hash before any fs event fires.
+        }
+        renameSync(tmp, path);
+      } else {
+        throw err;
+      }
+    }
+  } catch (err) {
+    // Best-effort cleanup of the .tmp + fd on failure — don't mask the
+    // original exception with a cleanup error.
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+  return path;
+}
+
+function isWindowsBusy(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const code = (err as { code?: string }).code;
+  return code === 'EBUSY' || code === 'EPERM' || code === 'EACCES';
+}