@1agh/maude 0.60.6 → 1.0.2

package/apps/studio/runtime-bundle.ts

@@ -383,5 +383,10 @@ function subPathExternals(_pkg: RuntimePackage): string[] {
  * own cold-start is already the longest tail.
  */
 export async function prewarmRuntimeBundles(): Promise<void> {
-  await Promise.all(RUNTIME_PACKAGES.map(getRuntimeBundle));
+  // Arrow, not a bare reference: `.map` passes (value, index, array), so
+  // `.map(getRuntimeBundle)` handed the ARRAY INDEX to the function's optional
+  // `opts` parameter — every pre-warm after the first ran with a nonsense
+  // options object. Silent, because a pre-warm that misbehaves just means the
+  // real build happens on first GET.
+  await Promise.all(RUNTIME_PACKAGES.map((pkg) => getRuntimeBundle(pkg)));
 }

package/apps/studio/server.ts

@@ -34,6 +34,7 @@ import { createHttp } from './http.ts';
 import { createInspectRegistry } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
 import { normalizeSessionKey, runInSession, SESSION_HEADER } from './session-scope.ts';
+import { sharedDocEnabled } from './sync/cell-pairing.ts';
 import { createSyncSupervisor } from './sync/supervisor.ts';
 import {
   assertContainment,
@@ -56,13 +57,15 @@ await bootSelfHeal();
 
 const ctx = createContext();
 
-// Phase 9.2 (DDR-064) — `MAUDE_SHARED_DOC` feature flag. OPT-IN (default OFF),
-// the inverse of MAUDE_CANVAS_ORIGIN_SPLIT's opt-out parsing: only an explicit
-// truthy value enables the single-shared-doc path. OFF = the proven two-doc +
-// disk-reconcile path = byte-for-byte current behavior. The flag is threaded
-// onto ctx here (before createCollab / createSyncRuntime read it) so every
-// downstream consumer sees one source of truth.
-ctx.sharedDoc = /^(1|true|on|yes)$/i.test(process.env.MAUDE_SHARED_DOC ?? '');
+// DDR-064 cutover (Sync v2 Increment 7) — `MAUDE_SHARED_DOC` now defaults ON:
+// the collab room's Y.Doc is THE doc per canvas, everywhere. The two-doc +
+// disk-reconcile path still exists in full and `MAUDE_SHARED_DOC=0` flips a
+// machine back onto it — that config flip is this release's rollback, which is
+// why NOTHING is deleted here (the relay's deletion is the next increment,
+// one soak later). The flag is threaded onto ctx here (before createCollab /
+// createSyncRuntime read it) so every downstream consumer sees one source of
+// truth, parsed by the same function the cell-pairing interlock uses.
+ctx.sharedDoc = sharedDocEnabled(process.env);
 
 // Forward-declared so the api.commentsAdd/patch/delete/addReply callback can
 // reach into the collab registry (Phase 8 Task 3 bridge). collab is initialized
@@ -97,6 +100,19 @@ const api = createApi(ctx, {
   // + `_active.json` retarget, bridged the same forward-declared way as the
   // comments/annotations hooks above.
   isRoomPinned: (slug) => collab?.registry.isPinned(slug) ?? false,
+  // The move protocol (codec stampMovedTo): the sync runtime stamps the old
+  // document retired + detaches, which unpins the room — after which the
+  // forceDrop below actually drops it and the rename is safe. Forward-declared
+  // like the other hooks; `ctx.syncControl` is set once the supervisor exists.
+  retireCanvasForMove: async (fromSlug, toRel) => {
+    try {
+      const runtime = ctx.syncControl?.current?.();
+      return (await runtime?.retireForMove?.(fromSlug, toRel)) ?? false;
+    } catch (err) {
+      console.warn(`[move] retire failed for ${fromSlug}:`, err);
+      return false;
+    }
+  },
   flushAndDropRoom: async (slug) => {
     if (collab) await collab.registry.forceDrop(slug);
   },
@@ -580,7 +596,26 @@ const publicShellOrigin = (() => {
     return '';
   }
 })();
-ctx.mainOrigin = `http://localhost:${server.port} http://127.0.0.1:${server.port}${publicShellOrigin}`;
+// Additional legit embedders, space-separated (validated per-origin). A cell
+// can genuinely have MORE than one shell name — the local rig serves its shell
+// on `http://studio.cell.localhost:<port>` (same-site with the canvas origin,
+// so the SameSite=Strict capability cookie flows exactly as it does in
+// production) while `127.0.0.1:<port>` stays alive for tooling — and listing
+// only one of them turns the other into a silent sad-page iframe refusal.
+const extraShellOrigins = (process.env.MAUDE_EXTRA_SHELL_ORIGINS ?? '')
+  .split(/[\s,]+/)
+  .filter(Boolean)
+  .map((u) => {
+    try {
+      return new URL(u).origin;
+    } catch {
+      return '';
+    }
+  })
+  .filter(Boolean)
+  .map((o) => ` ${o}`)
+  .join('');
+ctx.mainOrigin = `http://localhost:${server.port} http://127.0.0.1:${server.port}${publicShellOrigin}${extraShellOrigins}`;
 
 // T2 (9.1-A) — segregated canvas-content origin. ON BY DEFAULT (opt-OUT) since
 // phase-9.1: a second listener binds an OS-assigned free port, advertised as

package/apps/studio/sync/agent.ts

@@ -55,6 +55,8 @@ import {
   markSeeded,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
+  movedToFromDoc,
+  repairSharedMeta,
   seededByFromDoc,
   stampAnnotationsEdit,
   stampBodyEdit,
@@ -66,6 +68,7 @@ import {
   isExactRepeat,
   unionCommentsById,
 } from './cold-start.ts';
+import { applyColdStart } from './cold-start-apply.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 
@@ -258,6 +261,13 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
 
   async function flush(): Promise<void> {
     if (!dirty || stopped) return;
+    // A RETIRED document is write-inert. Its canvas moved to a new path in a
+    // new document; landing another byte from THIS one is how a moved canvas
+    // resurrected itself at its old path on every machine (see stampMovedTo).
+    if (movedToFromDoc(doc) !== null) {
+      dirty = false;
+      return;
+    }
     dirty = false;
     if (flushTimer) {
       clearTimeout(flushTimer);
@@ -345,6 +355,9 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
 
   function applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean {
     if (stopped) return false;
+    // Write-inert both ways — a local edit to a stale pre-move file must not
+    // revive the retired document either (see stampMovedTo).
+    if (movedToFromDoc(doc) !== null) return false;
     // Echo of our own atomicWrite — drop.
     if (echoGuard.consume(evt.path, evt.hash)) return false;
 
@@ -404,6 +417,10 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
 
   async function reconcile(): Promise<void> {
     if (stopped) return;
+    // A retired doc reconciles NOTHING — materialising it is the resurrection
+    // this stamp exists to end. The runtime's retirement watcher owns what
+    // happens to the stale local file (quarantine to _trash/).
+    if (movedToFromDoc(doc) !== null) return;
     const localHtml = readLocal(paths.html);
     const localComments = readLocal(paths.comments);
     const localAnnotations = readLocal(paths.annotations);
@@ -472,9 +489,6 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       docBodyEditAtMs: bodyEditAtFromDoc(doc),
     });
 
-    // Which side owns the visually-coupled lanes (annotations/css) below.
-    let bodyWinner: 'local' | 'hub' = 'hub';
-
     const writeBodyFromDoc = (): void => {
       const hash = hashBytes(docHtml);
       echoGuard.record(paths.html, hash);
@@ -497,84 +511,27 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       opts.journal?.record(slug, { bodyHash: hashBytes(body) });
     };
 
-    switch (decision.action) {
-      case 'noop':
-        lastHtml = docHtml;
-        // Identical non-empty sides: checkpoint so the next boot fast-forwards.
-        if (localHtml !== null && localHtml === docHtml && docHtml !== '') {
-          opts.journal?.record(slug, { bodyHash: hashBytes(docHtml) });
-        }
-        break;
-      case 'materialize-hub':
-      case 'fast-forward-hub':
-        writeBodyFromDoc();
-        break;
-      case 'seed-local-up':
-        // The DDR-064 empty-hub guard as a named decision row: an empty hub doc
-        // means the hub holds no body for this slug yet — NOT an authoritative
-        // "this canvas is blank". Seed the doc FROM local so the body survives
-        // AND the hub gets our content.
-        seedBodyUp(localHtml as string);
-        bodyWinner = 'local';
-        break;
-      case 'recover-seed-dup':
-        // F1 — booting against a hub whose body is our local body repeated (a
-        // concurrent cold-seed that already duplicated). Re-apply local so the
-        // diff deletes the extra copy/copies; the content equals local, so the
-        // visually-coupled lanes follow local too. Idempotent across peers.
-        seedBodyUp(localHtml as string);
-        bodyWinner = 'local';
-        break;
-      case 'conflict': {
-        // Divergence: snapshot BOTH versions to `_history/<slug>/` BEFORE any
-        // write, then apply the newest-wins winner. Even a wrong pick costs
-        // one /design:rollback (the incident's class of loss is closed).
-        const snapshots: { local?: string; hub?: string } = {};
-        let snapshotAttempted = false;
-        if (opts.snapshot) {
-          snapshotAttempted = true;
-          try {
-            const localTs = await opts.snapshot(localHtml as string, 'pre-sync-local');
-            if (localTs) snapshots.local = localTs;
-            const hubTs = await opts.snapshot(docHtml, 'pre-sync-hub');
-            if (hubTs) snapshots.hub = hubTs;
-          } catch {
-            /* swallowed below — the missing snapshot ref drives the fail-closed guard */
-          }
-        }
-        // DDR-102 fail-closed (security F1): the whole guarantee is "the loser is
-        // recoverable from _history". A hub-wins resolution OVERWRITES local — so
-        // if we asked for a snapshot but the local one did NOT land (full disk,
-        // read-only `_history/`, a Bun.write error), refuse the destructive
-        // overwrite. Keep local on disk and seed it UP instead, so nothing is
-        // lost on either side (local survives; the hub still gets our content).
-        // `snapshotAttempted` gates this to production wiring — a test/standalone
-        // agent with no snapshot fn keeps the plain newest-wins behavior.
-        const localSnapshotMissing = snapshotAttempted && !snapshots.local;
-        let winner = decision.winner;
-        if (winner === 'hub' && localSnapshotMissing) {
-          winner = 'local';
-          console.error(
-            `[sync/${slug}] cold-start divergence: hub won newest-wins but the local snapshot FAILED — REFUSING to overwrite local (DDR-102 fail-closed). Keeping local + pushing it up; resolve the _history/ write failure (disk full / read-only?) to restore newest-wins.`
-          );
-        }
-        if (winner === 'local') {
-          seedBodyUp(localHtml as string);
-          bodyWinner = 'local';
-        } else {
-          writeBodyFromDoc();
-        }
-        console.warn(`[sync/${slug}] cold-start divergence — ${decision.reason}`);
-        opts.onConflict?.({
-          slug,
-          kind: 'cold-start-diverged',
-          winner,
-          ...(snapshots.local || snapshots.hub ? { snapshots } : {}),
-          ...(localSnapshotMissing ? { snapshotFailed: true } : {}),
-        });
-        break;
-      }
-    }
+    // ONE application body, shared with migrate-seed.ts (DDR-226 Increment 0):
+    // exhaustive over every action with a compile-time `never` default, so the
+    // fail-closed snapshot guard, the conflict report and the row set can never
+    // drift between the two architectures again. Only the three EFFECTS differ
+    // and they are injected here.
+    const applied = await applyColdStart({
+      slug,
+      decision,
+      localBody: localHtml,
+      docBody: docHtml,
+      takeHub: writeBodyFromDoc,
+      takeLocal: seedBodyUp,
+      checkpointIdentity: (body) => opts.journal?.record(slug, { bodyHash: hashBytes(body) }),
+      ...(opts.snapshot ? { snapshot: opts.snapshot } : {}),
+      ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
+    });
+    // `noop` leaves disk and doc alone; the local mirror still tracks the doc.
+    if (applied.action === 'noop') lastHtml = docHtml;
+
+    // Which side owns the visually-coupled lanes (annotations fallback / css).
+    const bodyWinner = applied.bodyWinner;
 
     // ---- comments: id-union merge (DDR-102 — union loses nothing) ----------
     const localParsedComments = localComments !== null ? tryParseJsonArray(localComments) : null;
@@ -656,7 +613,14 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       }
     }
 
-    // ---- meta: shared-subset merge, unchanged in all cases -----------------
+    // ---- meta: hub wins where it has an opinion, local seeds where it does not
+    //
+    // Repair first. Two peers publishing the same meta into an empty lane leave
+    // two identical copies in the Y.Text, which every consumer's `JSON.parse`
+    // rejects — so the canvas reads as having no meta at all on any machine
+    // that syncs it afterwards. Collapsing it here, on a doc that has synced,
+    // is the only place the duplication is provable rather than suspected.
+    repairSharedMeta(doc, origin);
     lastMeta = docMeta;
     if (paths.meta && docMeta !== null) {
       const merged = mergeSharedMetaIntoLocal(localMeta, docMeta);
@@ -665,6 +629,30 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         echoGuard.record(paths.meta, hash);
         writer(paths.meta, merged);
       }
+    } else if (paths.meta && localMeta !== null) {
+      // AN EMPTY DOC IS NOT A CANVAS WITH NO TITLE.
+      //
+      // This branch used to not exist, and the comment above it said meta was
+      // "unchanged in all cases". The consequence: a canvas created on a peer
+      // reached the hub as a body with NO meta — no title, no kind, no
+      // design-system binding — and stayed that way until somebody happened to
+      // move an artboard, because a meta EDIT was the only thing that ever
+      // pushed meta up.
+      //
+      // It looked fine from the cloud, which is what kept it hidden: a cell's
+      // studio child arms `activity:suppress` on create, the container write
+      // bridge turns that into an `fs:any` a quarter-second later, and by then
+      // the new canvas has an agent to receive it. A desktop has no bridge — its
+      // real `fs.watch` fires immediately, before the agent for a
+      // just-created canvas exists, and the event lands nowhere. So the race
+      // was won on one side and lost on the other, and the underlying gap
+      // (cold-start meta was doc→file only) was invisible from the winning end.
+      //
+      // Seeding here is safe by construction: it runs ONLY when the doc carries
+      // no shared meta at all, so it cannot overwrite another peer's opinion —
+      // the same "absence is never authority" rule the rest of the sync applies
+      // to files, applied to the one sidecar that was exempt from it.
+      if (applyMetaToDoc(doc, localMeta, origin)) lastMeta = metaFromDoc(doc);
     }
   }
 

package/apps/studio/sync/asset-push.ts

@@ -1,6 +1,17 @@
-// Desktop→cell file push — DDR-217, the 2026-08-11 addendum, and the
-// feature-sync-file-plane widening (binding decision
-// maude/sync-two-plane-manifest-architecture).
+// THE LEGACY PUSH CLIENT — journal-less hubs only (Sync v2 Increment 5).
+//
+// On any hub that carries a journal, the file plane (`file-plane.ts`) is the
+// one lane for every project file, both directions, and this module is never
+// invoked (the capability probe in `sync/index.ts` decides the lane once per
+// boot). What remains here is the compat client for self-hosted hubs that
+// have not upgraded: the bounded, sequential, in-process push pass the pre-v2
+// desktop ran. Retained AT LEAST TWO RELEASES after the burn-down (Open
+// decision 4 of the journal arc) — delete it only against a compat matrix
+// that says the window has closed.
+//
+// Original charter (still accurate for the hubs this serves) — DDR-217, the
+// 2026-08-11 addendum, and the feature-sync-file-plane widening (binding
+// decision maude/sync-two-plane-manifest-architecture):
 //
 // The sync lanes are text-only (`html`/`css`/`meta`/`syncMeta`), so a
 // desktop-linked project's other files never reached the cell — first seen as
@@ -124,8 +135,9 @@ const UPLOAD_CONNECTION_HEADERS = { connection: 'close' } as const;
  * over a 182-file sweep is one per request, not a leak. Second, the actual
  * fault was isolated elsewhere and fixed: an HTTP/1.1 keep-alive desync after a
  * peer refused a PUT before draining its body (see UPLOAD_CONNECTION_HEADERS).
- * The sweep now also runs in its own process, so whatever these do or do not
- * contribute costs the sweep and not the editor.
+ * That fix is also why this pass runs in-process again — the out-of-process
+ * boundary (deleted in Increment 5) was protecting the editor from a transport
+ * fault that no longer exists.
  *
  * Removing them would trade a suspicion for a certainty: a request with no
  * budget is how a sweep hangs forever with nothing to report — the exact
@@ -176,7 +188,12 @@ function readProjectConfig(designRoot: string): {
     canvasGroups: Array.isArray(parsed?.canvasGroups)
       ? (parsed.canvasGroups as CanvasGroupLike[])
       : undefined,
-    syncFiles: process.env.MAUDE_SYNC_FILES === '1' || parsed?.linkedHub?.syncFiles === true,
+    // Default ON — mirrors `sync/index.ts`. Both read the same key and a drift
+    // between them would mean the sweep and the plane disagree about which
+    // files exist, which is the jurisdiction overlap Sync v2 exists to end.
+    syncFiles:
+      parsed?.linkedHub?.syncFiles !== false &&
+      (process.env.MAUDE_SYNC_FILES !== '0' || parsed?.linkedHub?.syncFiles === true),
   };
 }
 
@@ -425,6 +442,10 @@ export async function pushAssets(opts: {
   onProgress?: (progress: AssetPushProgress) => void;
   /** Injectable clock for the throttle (tests). */
   now?: () => number;
+  /** Asked before every upload — true abandons the rest of the pass (the Sync
+   *  panel's cancel; a multi-hundred-MB upload must be killable). The final
+   *  progress emit still fires, so the panel never freezes mid-count. */
+  cancelled?: () => boolean;
   /** Injectable pause for the 429 backoff (tests — a fake clock, not a wait). */
   sleep?: (ms: number) => Promise<void>;
   /** Injectable per-request time budget (tests — seconds, not minutes). */
@@ -486,6 +507,7 @@ export async function pushAssets(opts: {
       : null;
 
   for (const rel of assets) {
+    if (opts.cancelled?.()) break;
     emitProgress(rel, false);
     const url = `${base}${routeFor(rel).url}`;
     const headers = { authorization: `Bearer ${opts.token()}` };

package/apps/studio/sync/autocommit.ts

@@ -25,9 +25,11 @@
 // commit a precondition of the save would turn a transient git error into
 // data loss, which is precisely backwards.
 
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { withRepoLock } from '../git/repo-lock.ts';
+import { partitionSafeGitRels } from '../git/safe-rel.ts';
 
 /** How long the tree must be quiet before a commit fires. */
 const DEFAULT_DEBOUNCE_MS = 3000;
@@ -72,6 +74,23 @@ export interface AutoCommitOptions {
   /** Committer identity — the machine, never the human. */
   bot?: EditAttribution;
   log?: Pick<Console, 'warn' | 'error' | 'log'>;
+  /**
+   * Stage paths git is ignoring (`git add -f`). **Hub only.**
+   *
+   * On a desktop this must stay off: the ignore file is the user's, and
+   * force-adding would commit what they told git to skip. On the HUB it is the
+   * opposite — the design root IS the product there, not a mirror of it.
+   *
+   * This exists because of a real hole. Once a project goes hub-owned
+   * (DDR-228) its `.gitignore` carries `/.design/`, the hub's checkout is
+   * seeded from that repo and inherits it, and the hub quietly stops
+   * committing the design root. Generation backups are `git bundle --all`, so
+   * they carry committed objects only — meaning the design system had no copy
+   * in any backup, on top of having none in object storage (only `assets/` is
+   * mirrored). A deletion would then have been unrecoverable everywhere except
+   * a per-machine `_trash/` nothing prunes or indexes.
+   */
+  stageIgnored?: boolean;
 }
 
 export interface AutoCommit {
@@ -173,6 +192,7 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
     maxDebounceMs = DEFAULT_MAX_DEBOUNCE_MS,
     bot = DEFAULT_BOT,
     log = console,
+    stageIgnored = false,
   } = opts;
 
   const touched = new Set<string>();
@@ -272,22 +292,103 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
     return inFlight;
   }
 
+  /**
+   * Split a batch into what git can stage and what it cannot.
+   *
+   * `stage` — on disk, or gone but TRACKED (a real deletion to record).
+   * `drop`  — gone and never tracked: git has nothing to say about it, and
+   *           retrying it forever is what wedged the whole agent.
+   *
+   * One `ls-files` call for the whole batch, not one per path: this runs inside
+   * the repo lock and a per-file probe would put a fork on the critical section
+   * for every canvas in a busy window.
+   */
+  async function partitionForStaging(
+    input: string[]
+  ): Promise<{ stage: string[]; drop: string[] }> {
+    // SHAPE GATE FIRST (F-13/B12). These rels are built from `designRel` plus a
+    // path the file plane delivered, and they end up in `git add -- <paths>`.
+    // The `--` defuses a leading `-`, but nothing defuses `..`: a rel escaping
+    // the design root is a well-formed pathspec that stages a file the sync
+    // lane has no business touching — `../../.github/workflows/*` reached from
+    // a lane scoped to `.design/`. Refused paths are DROPPED, not thrown on:
+    // one poisoned rel must not wedge the queue for everybody else's work
+    // (the failure mode this whole function was written to avoid).
+    const { safe: files, refused } = partitionSafeGitRels(input);
+    if (refused.length > 0) {
+      console.warn(
+        `[autocommit] refusing ${refused.length} path(s) that are not safe repo-relative: ${refused
+          .slice(0, 5)
+          .map((r) => JSON.stringify(r))
+          .join(', ')}`
+      );
+    }
+    const missing = files.filter((f) => !existsSync(path.join(repoRoot, f)));
+    if (missing.length === 0) return { stage: files, drop: refused };
+
+    const known = await run(['ls-files', '--', ...missing], { cwd: repoRoot });
+    // If the probe itself fails, keep every path: guessing "untracked" here
+    // would DROP a real deletion, and a missed deletion is worse than a retry.
+    const tracked =
+      known.code === 0
+        ? new Set(
+            known.stdout
+              .split('\n')
+              .map((l) => l.trim())
+              .filter(Boolean)
+          )
+        : new Set(missing);
+    const drop = [...refused, ...missing.filter((f) => !tracked.has(f))];
+    if (drop.length === 0) return { stage: files, drop: [] };
+    const dropSet = new Set(drop);
+    return { stage: files.filter((f) => !dropSet.has(f)), drop };
+  }
+
   /** The critical section: stage exactly these files, commit them, report. */
   async function commitCycle(files: string[], who: EditAttribution): Promise<CommitOutcome> {
     // Stage ONLY what changed. `git add -A` in a workspace would sweep in
     // whatever else is in the tree — including files a future feature drops
     // there — and the cell must never commit something it wasn't told about.
-    const add = await run(['add', '--', ...files], { cwd: repoRoot });
+    // A PATH THAT VANISHED AND WAS NEVER TRACKED IS NOT AN ERROR TO RETRY.
+    //
+    // `git add -- <path that never existed in the index and is gone from disk>`
+    // exits 128 with "did not match any files". The batch then failed, re-queued
+    // ITSELF INCLUDING THAT PATH, and failed again the same way forever — so the
+    // first canvas anybody deleted stopped the cell committing ANYTHING, for the
+    // life of the process. Observed on a local cell: five commits, then
+    // twenty-plus identical `git add failed` lines and thirty canvases sitting
+    // untracked while `/health` answered 200 throughout.
+    //
+    // Paths are noted on the strength of a read taken up to `debounceMs`
+    // earlier, for files whose lifetime this process does not own, so a path
+    // disappearing mid-window is ROUTINE. The question is which kind of gone it
+    // is, and git already knows: a path in the index must be staged as a
+    // deletion (or the checkout and its history diverge permanently); a path
+    // git never heard of has nothing to record and is simply dropped.
+    const staging = await partitionForStaging(files);
+    if (staging.drop.length > 0) {
+      log.warn?.(
+        `[autocommit] ${staging.drop.length} path(s) vanished before staging and were never tracked; nothing to record: ${staging.drop.slice(0, 3).join(', ')}${staging.drop.length > 3 ? '…' : ''}`
+      );
+    }
+    if (staging.stage.length === 0) return { ok: false, reason: 'nothing-to-commit', files };
+    files = staging.stage;
+
+    // `-A` so a tracked path that is gone stages as a DELETION rather than
+    // erroring. It does not widen the scope: the pathspec is still this exact
+    // file list, so the "never commit something it wasn't told about" rule the
+    // comment above states is intact.
+    // `-A` so a tracked path that is gone stages as a DELETION rather than
+    // erroring; `-f` only where the caller asked for it — see `stageIgnored`.
+    const add = await run(['add', '-A', ...(stageIgnored ? ['-f'] : []), '--', ...files], {
+      cwd: repoRoot,
+    });
     if (add.code !== 0) {
       log.warn?.(`[autocommit] git add failed: ${add.stderr.trim()}`);
       // RE-QUEUE, exactly as the `commit` branch below does. `touched` was
       // cleared by `flush()` before we got here, so returning without this
       // drops the whole coalesced batch — including other people's edits in
       // the same window — from history, permanently and silently.
-      // One bad pathspec is enough: `git add -- <path that vanished>` exits
-      // 128, and paths are now noted on the strength of a read taken up to
-      // `debounceMs` earlier, for files whose lifetime this process does not
-      // own (a canvas deleted inside the quiescence window).
       for (const f of files) touched.add(f);
       return { ok: false, reason: 'git-failed', detail: add.stderr.trim(), files };
     }

package/apps/studio/sync/cell-file-events.ts

@@ -0,0 +1,117 @@
+// The cell child's file-event wiring — Sync v2 Increment 2/3 (DDR-226 §4/§6).
+//
+// The doorbell, both buttons, assembled once at boot:
+//
+//   resolveCellCtl      → do we have a loopback hub and a token? (workspace mode)
+//   createCtlProvider   → hold the read-only `maude.files` channel open
+//   createCtlHealer     → hub → child: poke ⇒ read the journal ⇒ emit the
+//                         `fs:any` the container's watcher owed us
+//   createCellWriteNudge → child → hub: we wrote ⇒ name the paths ⇒ the hub
+//                         re-reads its own disk and journals them
+//
+// The two directions are deliberately symmetric and deliberately unequal in
+// what they carry: the hub's frame carries a head and no path (DDR-054 — a path
+// would be a path the hub chose), and the child's carries paths and no content
+// (the hub re-stats and re-hashes for itself). Neither end can make the other
+// believe something about bytes it did not look at.
+//
+// Downstream of the heal, everything is machinery that already exists:
+// `fs:any` → `createHmrBroadcaster` → `canvas-hmr {mode:'asset'|'css'|'module'}`
+// → the iframe repoints a broken `<img>` (DDR-224) or swaps a stylesheet. No new
+// UI path, no new reload semantics.
+//
+// GATED ON WORKSPACE MODE, NOT ON CELL PAIRING — the whole point. Pairing is a
+// one-tenant pilot allowlist; the watcher gap is on every cell. See the header
+// of `ctl-provider.ts` for why the pairing preconditions do not apply to a
+// read-only stateless channel.
+//
+// Locally this never starts: outside a container `fs.watch` fires and a second
+// event source would double-reload every canvas on every edit, exactly the
+// reason `createContainerWriteBridge` carries the same gate.
+
+import type { Context } from '../context.ts';
+import { createCellWriteNudge } from './cell-write-nudge.ts';
+import { createCtlHealer } from './ctl-heal.ts';
+import { createCtlProvider, resolveCellCtl } from './ctl-provider.ts';
+
+export interface CellFileEvents {
+  stop(): void;
+  /** Pokes received on the channel. */
+  received(): number;
+  /** Paths announced onward as `fs:any`. */
+  healed(): number;
+  /** Nudge requests the hub accepted. */
+  nudged(): number;
+  /** Paths named in those requests. */
+  nudgedPaths(): number;
+}
+
+/**
+ * Start the hub→child file-event bridge. Returns null when this process is not
+ * a cell studio child (which is every desktop, and every local dev server).
+ *
+ * Never throws: the studio must start whether or not it has a doorbell.
+ */
+export function startCellFileEvents(
+  ctx: Context,
+  env: Record<string, string | undefined> = process.env
+): CellFileEvents | null {
+  const target = resolveCellCtl(env);
+  if (!target) return null;
+
+  const nudge = createCellWriteNudge({
+    hubUrl: target.url,
+    token: target.token,
+  });
+
+  const healer = createCtlHealer({
+    hubUrl: target.url,
+    token: target.token,
+    // The one side effect: announce a path onto the bus. Nothing here writes a
+    // file, and nothing here trusts the hub's row beyond its shape — the
+    // canvas layer re-reads the real disk to decide what to do about it.
+    //
+    // The mute is what stops us telling the hub a fact it just told us. It is
+    // not a loop guard — `recordWrite` is a no-op on identical bytes, so the
+    // echo would die on its own — it is simply not paying for the round trip.
+    emit: (rel) => {
+      nudge.mute(rel);
+      ctx.bus.emit('fs:any', rel);
+    },
+  });
+
+  // Baseline the heal cursor from the hub's head BEFORE the first poke — see
+  // `anchor`. Fire-and-forget: the studio must start whether or not the hub
+  // answers, and an unanchored healer still works the way it always did.
+  void healer.anchor();
+
+  const provider = createCtlProvider({
+    url: target.url,
+    token: target.token,
+    onPoke: (head) => healer.onPoke(head),
+  });
+
+  // Every write this process makes surfaces here, because both synthetic-event
+  // sources (`createContainerWriteBridge` off `activity:suppress`, and
+  // `announceWrite` off the projector) converge on `fs:any`. See the module
+  // header for why that is the complete set and why incompleteness would only
+  // cost latency.
+  const offFsAny = ctx.bus.on('fs:any', (rel: string) => nudge.note(rel));
+
+  console.log(
+    '[sync/ctl] file-event channel attached to this cell’s own hub — hub-process writes heal open canvases without a reload, and writes made here reach the journal at once instead of on the walk-import belt.'
+  );
+
+  return {
+    stop() {
+      offFsAny();
+      provider.stop();
+      healer.stop();
+      nudge.stop();
+    },
+    received: () => provider.received(),
+    healed: () => healer.healed(),
+    nudged: () => nudge.sent(),
+    nudgedPaths: () => nudge.named(),
+  };
+}