@1agh/maude 1.4.4 → 1.4.6

package/apps/studio/hmr-broadcast.ts

@@ -24,9 +24,11 @@
 // loaded via the importmap + Bun.build-produced ESM — there's no React Fast
 // Refresh runtime to register with. Full-reload is the reliable path.
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 
+import { recallCanvasBuild } from './canvas-source-memo.ts';
+import { type TextPatch, textOnlyPatches } from './canvas-text-patch.ts';
 import type { Context } from './context.ts';
 
 const DEBOUNCE_MS = 50;
@@ -54,6 +56,12 @@ export interface HmrMessage {
    * lost race re-applied onto theirs).
    */
   remote?: boolean;
+  /**
+   * F4 — `module` only: the change is nothing but the text of this element
+   * (versus the source of the canvas's last build). The iframe may show them at once; the remount it still
+   * performs confirms them. Absent whenever anything else changed.
+   */
+  patches?: TextPatch[];
 }
 
 /** How long after a sync write its file's change still counts as remote. */
@@ -93,6 +101,30 @@ export function createHmrBroadcaster(
     hard: 3,
   };
 
+  // Diff the canvas as it is now against the source the iframe renders (its
+  // last build). Read at flush, not per event, so a burst diffs end to end.
+  // String scanning plus the build's locator — never a parse (see
+  // canvas-text-patch.ts: in a cell this is the credential-holding process).
+  function withTextPatches(msg: HmrMessage): HmrMessage {
+    const root = ctx.paths?.designRoot;
+    if (msg.mode !== 'module' || !msg.file?.endsWith('.tsx') || !root) return msg;
+    const abs = path.join(root, msg.file);
+    let now: string;
+    try {
+      now = readFileSync(abs, 'utf8');
+    } catch {
+      return msg;
+    }
+    const built = recallCanvasBuild(abs);
+    if (built === undefined) return msg;
+    try {
+      const patches = textOnlyPatches(built.source, now, built.locator);
+      return patches?.length ? { ...msg, patches } : msg;
+    } catch {
+      return msg; // the remount still renders it
+    }
+  }
+
   function flush() {
     // A pending `hard` supersedes the per-file queue — every open canvas does a
     // full reload anyway, so the softer messages would be redundant churn.
@@ -100,7 +132,7 @@ export function createHmrBroadcaster(
     if (hard?.mode === 'hard') {
       broadcast(hard);
     } else {
-      for (const msg of pendingByKey.values()) broadcast(msg);
+      for (const msg of pendingByKey.values()) broadcast(withTextPatches(msg));
     }
     pendingByKey.clear();
     pending = null;
@@ -116,6 +148,11 @@ export function createHmrBroadcaster(
 
   // Files sync just wrote (see HmrMessage.remote), with the time of the write.
   const projectedAt = new Map<string, number>();
+  // A real watcher and the cell fallback can report the same completed write
+  // more than 50 ms apart. A second import invalidates the first even when its
+  // bytes are already arriving. Deduplicate disk VERSIONS, never merely paths
+  // or a time window: another edit to this file must still reach the canvas.
+  const remoteVersions = new Map<string, string>();
   const isRemote = (rel: string | undefined): boolean => {
     if (!rel) return false;
     const at = projectedAt.get(rel);
@@ -146,7 +183,25 @@ export function createHmrBroadcaster(
   const offAny = ctx.bus.on('fs:any', (rel: string) => {
     const msg = classify(rel);
     if (!msg) return;
-    if (isRemote(rel.replace(/\\/g, '/')) || isRemote(msg.file)) msg.remote = true;
+    const normalized = rel.replace(/\\/g, '/');
+    if (isRemote(normalized) || isRemote(msg.file)) msg.remote = true;
+    if (msg.remote && (msg.mode === 'module' || msg.mode === 'css') && ctx.paths.designRoot) {
+      try {
+        const s = statSync(path.join(ctx.paths.designRoot, normalized), { bigint: true });
+        // Nanosecond ctime also detects a same-size rewrite with restored mtime;
+        // inode detects atomic replacement. No source or large media is read.
+        const version = `${msg.mode}:${msg.file}:${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`;
+        if (remoteVersions.get(normalized) === version) return;
+        remoteVersions.delete(normalized);
+        remoteVersions.set(normalized, version);
+        if (remoteVersions.size > 256) {
+          const oldest = remoteVersions.keys().next().value;
+          if (oldest !== undefined) remoteVersions.delete(oldest);
+        }
+      } catch {
+        remoteVersions.delete(normalized); // missing/unreadable: fail open
+      }
+    } else remoteVersions.delete(normalized);
     enqueue(msg);
   });
 
@@ -157,6 +212,7 @@ export function createHmrBroadcaster(
       if (pending) clearTimeout(pending);
       pending = null;
       pendingByKey.clear();
+      remoteVersions.clear();
     },
   };
 }

package/apps/studio/http.ts

@@ -34,6 +34,7 @@ import { buildCanvasModule } from './canvas-build.ts';
 import { buildCanvasSandboxed, buildStats } from './canvas-build-sandbox.ts';
 import { canvasLibPath } from './canvas-lib-resolver.ts';
 import { TranspileError } from './canvas-pipeline.ts';
+import { rememberCanvasBuild } from './canvas-source-memo.ts';
 import { createCloudEndpoints } from './cloud/endpoints.ts';
 import type { AiActivity } from './collab/ai-activity.ts';
 import type { Context } from './context.ts';
@@ -687,6 +688,7 @@ export async function serveCanvasTsx(
         deps,
       };
       canvasCache.set(absPath, cached);
+      rememberCanvasBuild(absPath, { source, locator: result.locator });
       await writeLocator(locatorAbsPath, canvasSlug(absPath, ctx.paths.designRoot), result.locator);
       return respondWithCanvasModule(req, cached);
     }
@@ -725,6 +727,7 @@ export async function serveCanvasTsx(
       deps,
     };
     canvasCache.set(absPath, cached);
+    rememberCanvasBuild(absPath, { source, locator: result.locator });
     // Persist the locator map. Awaited so the inspector / Phase-12 layers
     // panel sees a consistent (cdId -> source) view by the time the canvas
     // mounts. Per-path mutex inside writeLocator() makes concurrent transpiles

package/apps/studio/sync/accepted-cold-start.ts

@@ -18,16 +18,31 @@
 // A canvas the project does not know yet is proposed as `doc.create` with all
 // of its lanes, so it arrives on every peer as ONE action.
 //
-// Comments and annotations are never re-proposed from disk here: every change
-// the studio made to them went through the durable outbox (drained before any
-// cold start), so a difference on disk is an older accepted state the room had
-// not re-projected — the accepted value wins, and the local file is kept in a
+// Annotations are never re-proposed from disk here: every change the studio
+// made to them went through the durable outbox (drained before any cold start),
+// so a difference on disk is an older accepted state the room had not
+// re-projected — the accepted value wins, and the local file is kept in a
 // recovery slot in case a raw edit made while the studio was down lived there.
+//
+// Comments had the same rule, and the premise did not hold for them (issue
+// #133, reproduced end-to-end): a comment added while the sync runtime was not
+// up yet (`proposeLane` unavailable, server.ts) went to the local room and disk
+// only, never into the outbox — so the web never saw it, and the file then
+// froze behind it. Comments carry stable ids, so the difference is decidable:
+// an id on disk that the accepted state lacks and that the comment ledger says
+// was never synced from here is a local comment still owed to the project; it
+// is proposed, as the accepted list plus those comments (a three-way id merge
+// on the hub). Ids the ledger knows were synced are deletions made while this
+// machine was away and are not proposed back. With no ledger record for the
+// canvas (first launch after upgrading) nothing is decidable: the old rule —
+// accepted wins, local kept in recovery — stands.
 
 import { existsSync, readFileSync } from 'node:fs';
 import type * as Y from 'yjs';
 
 import { cssFromDoc, htmlFromDoc, laneValueFromFile, readLaneFromDoc } from './codec.ts';
+import { commentKey } from './comment-identity.ts';
+import type { CommentLedger } from './comment-ledger.ts';
 import { hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import type { DocProjection, ProjectionPaths, ProposalLane } from './projection.ts';
@@ -53,6 +68,38 @@ function readText(p: string | undefined): string | null {
   }
 }
 
+function parseList(v: string): unknown[] {
+  if (!v) return [];
+  try {
+    const parsed = JSON.parse(v) as unknown;
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The comments list to propose at cold start — the accepted list plus the local
+ * comments never synced from here — or null when there is nothing owed (or no
+ * ledger record to decide by). See the header.
+ */
+export function commentsOwedToProject(
+  local: string,
+  accepted: string,
+  slug: string,
+  ledger: CommentLedger | undefined
+): string | null {
+  if (!ledger?.known(slug)) return null;
+  const acceptedList = parseList(accepted);
+  const inProject = new Set(acceptedList.map(commentKey));
+  const synced = ledger.get(slug);
+  const owed = parseList(local).filter((c) => {
+    const k = commentKey(c);
+    return !inProject.has(k) && !synced.has(k);
+  });
+  return owed.length > 0 ? JSON.stringify([...acceptedList, ...owed]) : null;
+}
+
 /**
  * Pure decision for the source lanes. `knownBase` is the last value disk and
  * the accepted replica agreed on (recovery slot), `baseHash` the journal's
@@ -92,6 +139,21 @@ export interface AcceptedColdStartInput {
   projection: DocProjection;
   historyDir?: string;
   journal?: SyncJournal;
+  /** Issue #133 — comment ids synced from here before (see the header). */
+  commentLedger?: CommentLedger;
+  /**
+   * This disk's own html proposal a previous run left unanswered, which the
+   * outbox drain has just had accepted. The disk was saved on top of it, so it
+   * is the base — the recovery slot still holds the value before it.
+   */
+  ownAccepted?: string | null;
+  /**
+   * Did the project ever accept exactly this value? A disk with no record of
+   * its base that holds a value the store accepted at some revision holds an
+   * OLDER accepted state (a checkout restored from a backup — every cloud
+   * cell wake), not an edit: it is materialized, never held.
+   */
+  wasAccepted?: (content: string) => Promise<boolean | null>;
   createDoc: (lanes: Partial<Record<ProposalLane, string>>) => Promise<{
     status: 'accepted' | 'rejected';
     code?: string;
@@ -145,14 +207,27 @@ export async function acceptedColdStart(
     // An invalid local body cannot be proposed; the projection keeps its bytes
     // in recovery and reports it when it materializes the accepted source.
     verdicts.push({ lane: 'html', decision: 'materialize', local: localHtml });
+  } else if (i.ownAccepted != null && localHtml === i.ownAccepted) {
+    // Disk IS the drained, accepted save; its publication may still be on the
+    // way. Nothing to propose, and nothing older to write over it.
+    verdicts.push({ lane: 'html', decision: 'agreed', local: localHtml });
+    i.projection.adoptOwnAccepted(i.ownAccepted);
   } else {
     const d = decideSourceLane({
       local: localHtml,
       accepted: acceptedHtml,
-      knownBase: i.historyDir ? readRecoveryBody(i.historyDir, i.paths.html, 'base') : null,
+      knownBase:
+        i.ownAccepted ??
+        (i.historyDir ? readRecoveryBody(i.historyDir, i.paths.html, 'base') : null),
       baseHash: i.journal?.get(i.slug)?.bodyHash ?? null,
     });
-    verdicts.push({ lane: 'html', ...d, ...(localHtml !== null ? { local: localHtml } : {}) });
+    const older =
+      d.decision === 'hold' && localHtml !== null && (await i.wasAccepted?.(localHtml)) === true;
+    verdicts.push({
+      lane: 'html',
+      ...(older ? { decision: 'materialize' as const } : d),
+      ...(localHtml !== null ? { local: localHtml } : {}),
+    });
   }
 
   // ---- css — opaque text, journal-checkpointed
@@ -164,7 +239,13 @@ export async function acceptedColdStart(
       knownBase: i.historyDir ? readRecoveryBody(i.historyDir, i.paths.css, 'base') : null,
       baseHash: i.journal?.get(i.slug)?.cssHash ?? null,
     });
-    verdicts.push({ lane: 'css', ...d, ...(localCss !== null ? { local: localCss } : {}) });
+    const older =
+      d.decision === 'hold' && localCss !== null && (await i.wasAccepted?.(localCss)) === true;
+    verdicts.push({
+      lane: 'css',
+      ...(older ? { decision: 'materialize' as const } : d),
+      ...(localCss !== null ? { local: localCss } : {}),
+    });
   }
 
   // ---- meta — the shared layout keys (viewport never travels)
@@ -193,6 +274,13 @@ export async function acceptedColdStart(
       verdicts.push({ lane, decision: local === null ? 'materialize' : 'agreed' });
       continue;
     }
+    if (lane === 'comments') {
+      const owed = commentsOwedToProject(local, accepted, i.slug, i.commentLedger);
+      if (owed) {
+        verdicts.push({ lane, decision: 'propose', base: accepted, local: owed });
+        continue;
+      }
+    }
     if (i.historyDir && text) {
       try {
         saveRecoveryBody(i.historyDir, p, 'local', text);

package/apps/studio/sync/accepted-link.ts

@@ -12,6 +12,9 @@
 // Nothing here writes a Y.Doc. The documents change when the hub publishes the
 // accepted revision, through the same providers that deliver a peer's edit.
 
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
 import { createActionStage, type StageSummary } from './action-stage.ts';
 import type { AcceptedLaneLink, LaneProposal, ProposalOutcome } from './projection.ts';
 import {
@@ -71,13 +74,61 @@ export function createAcceptedLink(opts: AcceptedLinkOptions) {
       retryMs: opts.retryMs,
     });
 
-  let mode: AcceptedMode = 'unknown';
+  // Every proposal this link sends goes out AFTER the creates queued before it
+  // (a lane edit of a canvas being added must never overtake its doc.create on
+  // the serialized queue); see `queueCreate` below.
+  const propose: TransactionClient['propose'] = (action) => {
+    flushCreates();
+    // A proposal about a canvas whose batched create is still unanswered waits
+    // until that create is settled or re-queued on its own: a refused batch
+    // falls back to one create each, and those must stay AHEAD of it.
+    const waits = [
+      ...new Set(
+        action.operations
+          .map((op) => (typeof op.doc === 'string' ? createsInFlight.get(op.doc) : undefined))
+          .filter((w): w is Promise<void> => !!w)
+      ),
+    ];
+    if (!waits.length) return client.propose(action);
+    return Promise.all(waits).then(() => client.propose(action));
+  };
+
+  // THE LAST VERDICT SURVIVES A RESTART (F3/S06). Held only in memory, a
+  // desktop that restarted without the network came back 'unknown', treated
+  // its offline edits as legacy shared-document writes, and the hub fenced
+  // those raw updates: the work never reached the project while the status
+  // read "synced". The hub still has the last word — the next bootstrap
+  // replaces this — but until it answers, the answer it last gave stands.
+  // Keyed by hub, so a relinked copy starts from 'unknown' again.
+  const modeFile = path.join(opts.designRoot, '_state', 'accepted-mode.json');
+  const loadMode = (): AcceptedMode => {
+    try {
+      const v = JSON.parse(readFileSync(modeFile, 'utf8'));
+      if (v?.v === 1 && v.hub === opts.hubUrl && (v.mode === 'transactions' || v.mode === 'legacy'))
+        return v.mode;
+    } catch {
+      /* absent or unreadable — ask the hub */
+    }
+    return 'unknown';
+  };
+  const saveMode = (next: AcceptedMode): void => {
+    if (next === 'unknown') return;
+    try {
+      mkdirSync(path.dirname(modeFile), { recursive: true });
+      const tmp = `${modeFile}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ v: 1, hub: opts.hubUrl, mode: next, at: Date.now() }));
+      renameSync(tmp, modeFile);
+    } catch {
+      /* the in-memory verdict still holds for this run */
+    }
+  };
+  let mode: AcceptedMode = loadMode();
   let manifest: Bootstrap | null = null;
 
   // T16 — AI and multi-file action boundaries (see action-stage.ts).
   const stage = createActionStage({
     designRoot: opts.designRoot,
-    propose: (action) => client.propose(action),
+    propose: (action) => propose(action),
     newTransactionId: client.newTransactionId,
     onChange: opts.onStage,
     log,
@@ -96,12 +147,16 @@ export function createAcceptedLink(opts: AcceptedLinkOptions) {
       if (next !== mode && mode !== 'unknown') {
         log.log(`[sync/tx] project save mode changed: ${mode} → ${next}`);
       }
+      if (next !== mode) saveMode(next);
       mode = next;
       manifest = b;
       opts.onBootstrap?.(b);
       return b;
     } catch (err) {
-      if (err instanceof TransactionError && err.code === 'absent') mode = 'legacy';
+      if (err instanceof TransactionError && err.code === 'absent') {
+        if (mode !== 'legacy') saveMode('legacy');
+        mode = 'legacy';
+      }
       return null;
     }
   }
@@ -114,7 +169,10 @@ export function createAcceptedLink(opts: AcceptedLinkOptions) {
    * confirmed by the next `refresh()`.
    */
   function noteMode(next: 'transactions' | 'legacy'): void {
-    if (next !== mode) log.log(`[sync/tx] the project switched its save mode: ${mode} → ${next}`);
+    if (next !== mode) {
+      log.log(`[sync/tx] the project switched its save mode: ${mode} → ${next}`);
+      saveMode(next);
+    }
     mode = next;
   }
 
@@ -133,24 +191,22 @@ export function createAcceptedLink(opts: AcceptedLinkOptions) {
         const doc = opts.docNameFor(slug);
         if (stage.captures(slug, p.stageable === true)) return stage.capture(slug, doc, p);
         const send = (dependsOn: string[] | undefined) =>
-          client
-            .propose({
-              kind: 'edit',
-              label: LANE_LABEL[p.lane],
-              transactionId: p.transactionId,
-              dependsOn,
-              operations: [
-                {
-                  op: 'lane.replace',
-                  doc,
-                  lane: p.lane,
-                  content: p.content,
-                  baseContent: p.baseContent,
-                  ...(p.writeId ? { writeId: p.writeId } : {}),
-                },
-              ],
-            })
-            .then(outcome);
+          propose({
+            kind: 'edit',
+            label: LANE_LABEL[p.lane],
+            transactionId: p.transactionId,
+            dependsOn,
+            operations: [
+              {
+                op: 'lane.replace',
+                doc,
+                lane: p.lane,
+                content: p.content,
+                baseContent: p.baseContent,
+                ...(p.writeId ? { writeId: p.writeId } : {}),
+              },
+            ],
+          }).then(outcome);
         if (stage.holdsDependency(p.dependsOn)) {
           // Authored on top of an agent's unpublished bytes: it waits behind
           // the stage, and goes out right after the group (or is discarded
@@ -175,13 +231,86 @@ export function createAcceptedLink(opts: AcceptedLinkOptions) {
    * it). The caller proceeds with its local change either way — the designer
    * never waits on the network to move a canvas.
    */
+  // ONE PROPOSAL FOR A BURST OF NEW CANVASES. A fresh link adds every local
+  // canvas the project does not have, each from its own cold start, all at
+  // once; sent one by one they are that many round trips on the one
+  // serialized transaction queue, and the first edit waits behind all of them
+  // (F3 S14 on the cloud cell: 77 creates, 44 s). Creates that arrive within a
+  // short window travel together; a refused batch falls back to one proposal
+  // each, so one canvas the project will not take cannot hold back the rest.
+  const CREATE_WINDOW_MS = 25;
+  const CREATE_BATCH_MAX = 100;
+  const CREATE_BATCH_BYTES = 4 * 1024 * 1024;
+  type PendingCreate = { op: Operation; bytes: number; resolve: (o: ProposalOutcome) => void };
+  let createBatch: PendingCreate[] = [];
+  let createBatchBytes = 0;
+  let createTimer: ReturnType<typeof setTimeout> | null = null;
+  /** doc → the gate a batched create of it holds until settled or re-queued. */
+  const createsInFlight = new Map<string, Promise<void>>();
+  const proposeCreates = (ops: Operation[]) =>
+    client
+      .propose({
+        kind: 'canvas.create',
+        label: ops.length === 1 ? 'Create canvas' : `Add ${ops.length} canvases`,
+        operations: ops,
+      })
+      .then(outcome);
+  function flushCreates(): void {
+    if (createTimer) clearTimeout(createTimer);
+    createTimer = null;
+    const batch = createBatch;
+    createBatch = [];
+    createBatchBytes = 0;
+    if (!batch.length) return;
+    const docs = batch.map((c) => c.op.doc).filter((d): d is string => typeof d === 'string');
+    let settled: () => void = () => {};
+    const gate = new Promise<void>((r) => {
+      settled = r;
+    });
+    for (const d of docs) createsInFlight.set(d, gate);
+    const release = () => {
+      for (const d of docs) if (createsInFlight.get(d) === gate) createsInFlight.delete(d);
+      settled();
+    };
+    const fail = (err: unknown) => {
+      release();
+      for (const c of batch)
+        c.resolve({ status: 'rejected', code: (err as TransactionError)?.code ?? 'failed' });
+    };
+    void proposeCreates(batch.map((c) => c.op)).then((o) => {
+      if (o.status === 'accepted' || batch.length === 1) {
+        release();
+        for (const c of batch) c.resolve(o);
+        return;
+      }
+      // Each create is queued (and so ahead of anything waiting on the gate)
+      // before the gate opens.
+      const each = batch.map((c) => proposeCreates([c.op]));
+      release();
+      each.forEach((answer, i) => void answer.then(batch[i].resolve, () => batch[i].resolve(o)));
+    }, fail);
+  }
+  function queueCreate(op: Operation): Promise<ProposalOutcome> {
+    const bytes = Buffer.byteLength(JSON.stringify(op), 'utf8');
+    if (
+      createBatch.length &&
+      (createBatch.length >= CREATE_BATCH_MAX || createBatchBytes + bytes > CREATE_BATCH_BYTES)
+    )
+      flushCreates();
+    return new Promise((resolve) => {
+      createBatch.push({ op, bytes, resolve });
+      createBatchBytes += bytes;
+      createTimer ??= setTimeout(flushCreates, CREATE_WINDOW_MS);
+    });
+  }
+
   function structural(
     label: string,
     kind: string,
     operations: Operation[],
     waitMs: number
   ): Promise<StructuralOutcome> {
-    const answer = client.propose({ kind, label, operations }).then(outcome);
+    const answer = propose({ kind, label, operations }).then(outcome);
     if (!Number.isFinite(waitMs)) return answer;
     return Promise.race([
       answer,
@@ -214,12 +343,19 @@ export function createAcceptedLink(opts: AcceptedLinkOptions) {
     ): Promise<StructuralOutcome> {
       const clean: Record<string, string> = {};
       for (const [lane, v] of Object.entries(lanes)) if (v) clean[lane] = v;
-      return structural(
-        'Create canvas',
-        'canvas.create',
-        [{ op: 'doc.create', doc: opts.docNameFor(slug), path: rel, lanes: clean }],
-        waitMs
-      );
+      const answer = queueCreate({
+        op: 'doc.create',
+        doc: opts.docNameFor(slug),
+        path: rel,
+        lanes: clean,
+      });
+      if (!Number.isFinite(waitMs)) return answer;
+      return Promise.race([
+        answer,
+        new Promise<StructuralOutcome>((resolve) =>
+          setTimeout(() => resolve({ status: 'accepted', queued: true }), waitMs)
+        ),
+      ]);
     },
     deleteDoc(slug: string, waitMs = 8_000): Promise<StructuralOutcome> {
       return structural(

package/apps/studio/sync/agent.ts

@@ -67,7 +67,8 @@ import {
   unionCommentsById,
 } from './cold-start.ts';
 import { applyColdStart, type ColdStartSnapshotReason } from './cold-start-apply.ts';
-import { dedupeCommentsById, hasDuplicateComments } from './comment-identity.ts';
+import { commentKey, dedupeCommentsById, hasDuplicateComments } from './comment-identity.ts';
+import { type CommentLedger, withoutRemotelyDeleted } from './comment-ledger.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { rememberSeed, repairSeedDuplication } from './seed-repair.ts';
@@ -119,6 +120,20 @@ export interface CanvasSyncAgentOptions {
    * without it simply degrade to the conservative conflict path.
    */
   journal?: SyncJournal;
+  /**
+   * Issue #133 — comment ids synced from this machine before
+   * (sync/comment-ledger.ts). The cold-start union drops a local comment the
+   * ledger knows and the hub's doc no longer holds: that is a delete made
+   * while this machine was away, not a local-only comment. Optional — absent,
+   * the union keeps everything, as before.
+   */
+  commentLedger?: CommentLedger;
+  /**
+   * Does the hub hold this doc's current state (nothing unacknowledged)? The
+   * ledger records comment ids as synced only then — see
+   * `commentsConfirmedOnHub` in sync/index.ts. Absent → never records.
+   */
+  commentsConfirmed?: () => boolean;
   /**
    * Snapshot writer (DDR-102 conflict protocol) — persists a body version to
    * `_history/<slug>/` and resolves with the snapshot's ISO ts (null on
@@ -339,6 +354,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     echoGuard.record(paths.comments, hash);
     writer(paths.comments, serialized);
     lastComments = serialized;
+    if (opts.commentsConfirmed?.()) opts.commentLedger?.record(slug, next.map(commentKey));
   }
 
   function writeAnnotationsIfChanged(): void {
@@ -411,6 +427,8 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       if (parsed === null) return false;
       const changed = applyCommentsToDoc(doc, parsed, origin);
       if (changed) lastComments = str;
+      if (opts.commentsConfirmed?.())
+        opts.commentLedger?.record(slug, commentsFromDoc(doc).map(commentKey));
       return changed;
     }
     if (evt.path === paths.annotations) {
@@ -562,7 +580,13 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     const bodyWinner = applied.bodyWinner;
 
     // ---- comments: id-union merge (DDR-102 — union loses nothing) ----------
-    const localParsedComments = localComments !== null ? tryParseJsonArray(localComments) : null;
+    const localParsed = localComments !== null ? tryParseJsonArray(localComments) : null;
+    // Issue #133 — a local comment that was synced from here before and that
+    // the hub's doc no longer holds was deleted while this machine was away.
+    // Unioning it back resurrected it for everyone.
+    const localParsedComments = localParsed
+      ? withoutRemotelyDeleted(localParsed, docComments, opts.commentLedger?.get(slug))
+      : null;
     if (localParsedComments !== null && localParsedComments.length > 0) {
       const merged = unionCommentsById(docComments, localParsedComments);
       const mergedStr = merged.length > 0 ? `${JSON.stringify(merged, null, 2)}\n` : '';
@@ -573,6 +597,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         writer(paths.comments, mergedStr);
       }
       lastComments = mergedStr;
+      if (opts.commentsConfirmed?.()) opts.commentLedger?.record(slug, merged.map(commentKey));
     } else {
       // No (parseable) local comments — hub state materializes as before.
       lastComments = docCommentsStr;
@@ -581,6 +606,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         echoGuard.record(paths.comments, hash);
         writer(paths.comments, docCommentsStr);
       }
+      if (opts.commentsConfirmed?.()) opts.commentLedger?.record(slug, docComments.map(commentKey));
     }
 
     // ---- annotations: PER-LANE newest-wins (the 2026-08-14 eraser fix) -----