@1agh/maude 0.60.2 → 0.60.4

package/apps/studio/http.ts

@@ -651,6 +651,12 @@ async function serveCanvasTsx(
     try {
       result = await buildCanvasModule(absPath, source, {
         designRoot: ctx.paths.designRoot,
+        // UNCONDITIONAL, desktop included (feature-sync-file-plane, Task 9 —
+        // the binding debate's CONDITION on the `code-module` class): a
+        // canvas import resolves inside the design root on EVERY runtime, so
+        // a synced module cannot make the build read the wider filesystem.
+        // The cell worker has always armed this (canvas-build-worker.ts).
+        restrictImportsTo: ctx.paths.designRoot,
       });
     } catch (err) {
       if (err instanceof TranspileError) {
@@ -769,7 +775,12 @@ async function serveHistoricalCanvas(
     const source = await gitShowFile(ctx.paths.repoRoot, sha, repoRel);
     if (source == null) return new Response('No saved version of this canvas', { status: 404 });
     try {
-      const result = await buildCanvasModule(absPath, source, { designRoot: ctx.paths.designRoot });
+      const result = await buildCanvasModule(absPath, source, {
+        designRoot: ctx.paths.designRoot,
+        // Same unconditional allowlist as the live build above — a HISTORICAL
+        // source is still tenant/peer-authored content.
+        restrictImportsTo: ctx.paths.designRoot,
+      });
       cached = {
         js: result.js,
         etag: `${result.etag}-${sha}-${RUNTIME_BOOT_ID}-${CHROME_EPOCH}`,
@@ -1194,6 +1205,28 @@ export function createHttp(
   const gitJson = (r: { status: number; json: unknown }) =>
     Response.json(r.json, { status: r.status, headers: { 'Cache-Control': 'no-store' } });
 
+  /**
+   * A refused `/_api/sync/*` call, in the shape the Sync panel can actually
+   * render: `{ ok: false, reason, detail }`.
+   *
+   * The panel falls back to a fixed string when a response carries no `detail`,
+   * so every plain-text refusal on these routes surfaced as the same causeless
+   * "Resync could not start." — the failure the 2026-08-13 report ends on. The
+   * gate decisions are untouched; only the answer is.
+   *
+   * The `detail` is written for a person and names no request internals: which
+   * origin or host was presented is in the server log, where it is diagnostic,
+   * not in a body a canvas iframe could read back.
+   */
+  const syncRefusal = (reason: 'cross-origin' | 'untrusted-host', what: string): Response => {
+    console.warn(`[sync] ${reason} request to a sync control route — refused.`);
+    const detail =
+      reason === 'cross-origin'
+        ? `${what} from Maude itself, not from inside a canvas.`
+        : `${what} from the Maude app or this machine's own browser tab.`;
+    return gitJson({ status: 403, json: { ok: false, reason, detail } });
+  };
+
   // Shared by /_api/export and /_api/export-jobs — build the exportJobs.enqueue()
   // args from a validated request body. `inspect.state` is the live `_active.json`;
   // readers narrow to the resolver's subset locally so the export pipeline doesn't
@@ -2476,10 +2509,19 @@ export function createHttp(
     // the person's own hub, and a way to spend their rate-limit budget.
     '/_api/sync/resync': async (req: Request) => {
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
-      if (!sameOriginWrite(req))
-        return new Response('cross-origin write rejected', { status: 403 });
+      // REFUSALS ANSWER IN JSON, WITH A REASON.
+      //
+      // These were plain-text 403s, so the panel — which reads `json.detail` and
+      // falls back to a fixed string — rendered every one of them as "Resync
+      // could not start.", a sentence naming no cause and offering no next step.
+      // A person hitting the gate legitimately (a canvas iframe, a stale tab,
+      // the wrong host) got the same six words as a person hitting a bug, and
+      // neither could tell which they had. The GATES are unchanged: what a
+      // refusal SAYS is not a security property, and saying nothing was never
+      // protecting anything.
+      if (!sameOriginWrite(req)) return syncRefusal('cross-origin', 'Resync must be started');
       if (!isTrustedRequestHost(req))
-        return new Response('local request required', { status: 403 });
+        return syncRefusal('untrusted-host', 'Resync must be started');
       const control = ctx.syncControl;
       if (!control) {
         return gitJson({
@@ -2507,10 +2549,9 @@ export function createHttp(
       // is. Safe by construction — uploads are idempotent and the hub writes
       // temp-then-rename, so no half-written asset can survive this.
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
-      if (!sameOriginWrite(req))
-        return new Response('cross-origin write rejected', { status: 403 });
+      if (!sameOriginWrite(req)) return syncRefusal('cross-origin', 'Cancelling must be started');
       if (!isTrustedRequestHost(req))
-        return new Response('local request required', { status: 403 });
+        return syncRefusal('untrusted-host', 'Cancelling must be started');
       const cancelled = ctx.syncControl?.current?.()?.cancelAssetSweep() ?? false;
       return gitJson({ status: 200, json: { ok: true, cancelled } });
     },

package/apps/studio/server.ts

@@ -685,6 +685,17 @@ ctx.bus.on('fs:json', (rel: string) => {
 // Connect starts syncing instead of printing "restart the studio server".
 const syncRuntime = createSyncSupervisor(ctx, collab ? { registry: collab.registry } : {});
 ctx.syncControl = syncRuntime;
+// A linked project that had NOTHING syncable at boot asks for one cycle the
+// moment it gains its first canvas — see the zero-canvas branch in
+// `sync/index.ts`. The runtime cannot cycle itself (the supervisor owns the
+// serialization), so it asks and this answers. Refused while a cycle is already
+// in flight, exactly like the Resync button.
+ctx.bus.on('sync:needs-restart', () => {
+  if (syncRuntime.busy()) return;
+  void syncRuntime.restart().catch((err) => {
+    console.error('[sync] first-canvas restart failed:', err);
+  });
+});
 try {
   await syncRuntime.start();
 } catch (err) {

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

@@ -0,0 +1,210 @@
+// Cell→desktop asset pull — the downward half of the asset lane.
+//
+// THE BUG THIS EXISTS TO END. `asset-push.ts` is, in its own words, a
+// "Desktop→cell asset push", and the cell never runs it at all (the
+// `cellPairing` guard on `scheduleAssetSweep`). That is correct as designed —
+// the desktop is the peer that HAS the bytes — but nothing was ever built for
+// the other direction, so an image dropped onto a canvas IN THE BROWSER had its
+// bytes stranded on the cell forever.
+//
+// The text lanes hid how total that was. `<slug>.annotations.svg` syncs, so the
+// image stroke arrives on the desktop with its position, its size and its alt
+// text intact, and renders as a broken-image glyph: a canvas that is visibly
+// there and permanently empty. Confirmed on alligators — `assets/c0fa9c7f.png`
+// referenced by a synced annotation, absent from every local disk.
+//
+// WHAT IT WANTS IS DERIVED LOCALLY, NOT DICTATED. The hub is untrusted to peers
+// (DDR-054), so this never asks "what should I download" — it reads the files
+// this peer ALREADY HOLDS, collects the `assets/…` references in them, and asks
+// only for the ones missing from its own disk. A hostile hub cannot use this to
+// place a file nobody referenced.
+//
+// AND THE REFERENCES THEMSELVES ARE UNTRUSTED. An annotation can have arrived
+// from the hub, so a name found inside one is hub-controlled input. Every
+// candidate is re-validated against `ASSET_NAME_RE` before it becomes a path:
+// one segment, no scheme, no traversal, allowlisted extension — the same shape
+// `ASSET_IMAGE_HREF_RE` enforces on the way in.
+//
+// MISSING-ONLY AND IDEMPOTENT, so a whole machine costs one directory scan and
+// no requests, and a failed pull is retried for free on the next pass.
+
+import {
+  type Dirent,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+
+/** How long to wait for one asset. Generous — these are photographs and clips. */
+const GET_TIMEOUT_MS = 120_000;
+
+/** Refuse an implausible body outright rather than streaming it to disk. */
+const MAX_PULL_BYTES = 512 * 1024 * 1024;
+
+/**
+ * How many assets one pass will fetch.
+ *
+ * The same reasoning as the pull lane's `MAX_PULLS_PER_POLL`: every accepted
+ * name becomes a real file in the design root, and this runs on a schedule for
+ * the life of the process. A cap makes one answer unable to land thousands, and
+ * the remainder is simply picked up by the next pass.
+ */
+const MAX_PULLS_PER_PASS = 200;
+
+/**
+ * A content-addressed asset name: ONE segment, no traversal, known extension.
+ *
+ * Deliberately the same shape as the annotation sanitizer's
+ * `ASSET_IMAGE_HREF_RE`, widened to the media + font types the push lane already
+ * carries. Anchored, so `assets/../../etc/passwd` and `assets/x.png?../` are
+ * both refused before a path is built from them.
+ */
+const ASSET_NAME_RE =
+  /^[A-Za-z0-9._-]+\.(?:png|jpe?g|webp|gif|avif|svg|mp4|webm|mov|m4v|mp3|wav|m4a|aac|ogg|woff2?|ttf|otf)$/i;
+
+/** Every `assets/<name>` reference in a blob of text. */
+const REFERENCE_RE = /assets\/([A-Za-z0-9._-]+\.[A-Za-z0-9]+)/g;
+
+/** Files worth reading for references — the canvas and its sidecars. */
+const SCANNED_EXT = /\.(?:annotations\.svg|tsx|jsx|css|meta\.json)$/i;
+
+/** Runtime directories that never hold a live reference (DDR-115). */
+const SKIPPED_DIRS = new Set(['_trash', '_history', '_untrusted', '_smoke', 'node_modules']);
+
+export interface AssetPullResult {
+  pulled: string[];
+  /** Referenced, missing, and the hub could not supply it. */
+  failed: { name: string; reason: string }[];
+  /** Referenced and already on disk — the steady state. */
+  present: number;
+}
+
+/**
+ * Collect every `assets/<name>` this project references, validated.
+ *
+ * Reads the canvas bodies and their sidecars. A reference that does not survive
+ * `ASSET_NAME_RE` is dropped silently: it is either not an asset or not a name
+ * this peer will ever turn into a path.
+ */
+export function referencedAssets(designRoot: string): string[] {
+  const out = new Set<string>();
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 8) return;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // `assets/` itself is the destination, not a source of references.
+        if (SKIPPED_DIRS.has(entry.name) || entry.name === 'assets') continue;
+        walk(abs, depth + 1);
+        continue;
+      }
+      if (!SCANNED_EXT.test(entry.name)) continue;
+      let text: string;
+      try {
+        text = readFileSync(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const match of text.matchAll(REFERENCE_RE)) {
+        const name = match[1];
+        if (name && ASSET_NAME_RE.test(name)) out.add(name);
+      }
+    }
+  };
+  walk(designRoot, 0);
+  return [...out].sort();
+}
+
+/**
+ * Fetch the referenced assets this machine does not have.
+ *
+ * Sequential on purpose, exactly like `pushAssets`: these run to videos, and
+ * saturating a link the sync is also using would starve the handshakes. Never
+ * throws — a failure is a line in `failed` and a free retry next pass.
+ */
+export async function pullAssets(opts: {
+  designRoot: string;
+  hubUrl: string;
+  /** Read at call time — silent renewal swaps the credential in place. */
+  token: () => string;
+  fetchImpl?: typeof fetch;
+  log?: Pick<Console, 'log' | 'warn'>;
+}): Promise<AssetPullResult> {
+  const { designRoot, hubUrl } = opts;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? console;
+  const base = hubUrl.replace(/\/+$/, '');
+  const assetsDir = path.join(designRoot, 'assets');
+  const out: AssetPullResult = { pulled: [], failed: [], present: 0 };
+
+  const wanted: string[] = [];
+  for (const name of referencedAssets(designRoot)) {
+    if (existsSync(path.join(assetsDir, name))) out.present += 1;
+    else wanted.push(name);
+  }
+  if (wanted.length === 0) return out;
+
+  // A peer that has never held an asset has no `assets/` yet — the first pull
+  // is exactly when that is true.
+  try {
+    mkdirSync(assetsDir, { recursive: true });
+  } catch (err) {
+    log.warn(`[sync/assets] cannot create ${assetsDir}: ${(err as Error).message}`);
+    return out;
+  }
+
+  const batch = wanted.slice(0, MAX_PULLS_PER_PASS);
+  if (batch.length < wanted.length) {
+    // Named loudly, for the same reason the pull lane names its cap: a silent
+    // truncation reads as "sync is broken" with no cause.
+    log.warn(
+      `[sync/assets] ${wanted.length} referenced assets are missing here; taking ${batch.length} this pass.`
+    );
+  }
+
+  for (const name of batch) {
+    try {
+      const res = await fetchImpl(`${base}/assets/${encodeURIComponent(name)}`, {
+        headers: { authorization: `Bearer ${opts.token()}` },
+        signal: AbortSignal.timeout(GET_TIMEOUT_MS),
+      });
+      if (!res.ok) {
+        // A 404 is ordinary: the other peer has not pushed it yet. It costs a
+        // line here and is retried next pass, when it may well be there.
+        out.failed.push({ name, reason: `HTTP ${res.status}` });
+        continue;
+      }
+      const body = new Uint8Array(await res.arrayBuffer());
+      if (body.byteLength === 0 || body.byteLength > MAX_PULL_BYTES) {
+        out.failed.push({ name, reason: `implausible size (${body.byteLength} B)` });
+        continue;
+      }
+      // Write beside the target and rename, so a reader (the dev server serving
+      // this very path) never sees a half-written image.
+      const finalAbs = path.join(assetsDir, name);
+      const tmpAbs = `${finalAbs}.part`;
+      writeFileSync(tmpAbs, body);
+      renameSync(tmpAbs, finalAbs);
+      out.pulled.push(name);
+    } catch (err) {
+      out.failed.push({ name, reason: (err as Error).message });
+    }
+  }
+
+  if (out.pulled.length > 0) {
+    log.log(
+      `[sync/assets] pulled ${out.pulled.length} asset(s) down from the project (${out.failed.length} still missing).`
+    );
+  }
+  return out;
+}

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

@@ -1,66 +1,42 @@
-// Desktop→cell asset push — DDR-217 + the 2026-08-11 addendum (fix 6 of the
-// 2026-08-10 sync RCA, completed).
+// 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 sync lanes are text-only (`html`/`css`/`meta`/`syncMeta`), so a
-// desktop-linked project's binary assets never reached the cell — the grey
-// boxes. The desktop is the one peer that HAS the bytes and already holds an
-// authenticated channel to the hub, so it pushes them. There are TWO asset
-// classes, served two different ways, so they push to two different routes:
+// desktop-linked project's other files never reached the cell — first seen as
+// grey boxes (binary assets), then as a whole design system that never
+// arrived (the 103-file RCA). The desktop is the one peer that HAS the bytes
+// and already holds an authenticated channel to the hub, so it pushes them.
+//
+// MEMBERSHIP IS THE CLASSIFIER'S (`file-membership.ts`) — the same positive
+// enumeration the downward plane and the hub's own admission use: inert
+// media, companion text (`brand.css`, `README.md`), and code modules
+// (`_brand-css.ts`), with `canvas-owned` (the CRDT lanes') and `never`
+// (config, runtime state, everything unclassified) excluded. The old
+// assets-dir walk + binary-extension pair lived here; it is subsumed, not
+// joined, by the classifier.
+//
+// TWO ROUTES REMAIN, split by PATH (`routeFor`):
 //
 //   1. TOP-LEVEL content-addressed uploads (`<designRoot>/assets/<sha8>.<ext>`)
 //      — referenced by the `/assets/<key>` shortcut, served on the cloud from
 //      the BUCKET proxy. Push → `PUT /assets/<key>` (bucket + checkout mirror).
-//   2. DS / BRAND assets (`<designRoot>/system/<ds>/assets/logos/x.svg`, fonts,
-//      photos) — referenced by their FULL designRoot path
-//      (`/.design/system/<ds>/assets/…`) and served from the CHECKOUT by the
-//      studio child, never the bucket. The original fix only swept class 1, so
-//      these stayed grey (alligators has 93 of them). Push → `PUT
-//      /_asset-file/<designRoot-rel>` (checkout only, no bucket).
+//   2. EVERYTHING ELSE (DS assets, stylesheets, docs, shared modules) —
+//      referenced by designRoot path, served from the CHECKOUT. Push →
+//      `PUT /_asset-file/<designRoot-rel>` (classifier-gated on the hub too).
 //
-// Both are HEAD-first (skip what the cloud already holds) and streamed. The
+// Both are probe-first (skip what the cloud already holds) and streamed. The
 // HUB's validation is the authoritative gate at each trust boundary; the
 // filters here are the courtesy layer that keeps junk off the wire.
 
-import { type Dirent, readdirSync, statSync } from 'node:fs';
+import { type Dirent, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-/** One path segment charset — matches the hub's component regexes. */
-const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+import { type CanvasGroupLike, classifyProjectFile, isFilePlaneClass } from './file-membership.ts';
 
-/** Max designRoot-relative depth (matches the hub's 8-segment cap). */
+/** Max designRoot-relative depth (matches the classifier's 8-segment cap). */
 const MAX_SEGMENTS = 8;
 
-/** Max relative-path length (matches the hub's 512 cap). */
-const MAX_REL_LEN = 512;
-
-/**
- * The binary asset extensions that actually render — images, fonts, media.
- * Deliberately NOT `.json`/`.meta.json`/`.photo.json`/`.tsx`/`.css`: a
- * `.photo.json` sidecar is edit metadata, not a served asset, and the checkout
- * route refuses non-asset extensions anyway (so pushing them would just waste
- * the wire and 400). Case-insensitive — a DS ships `…P1020428.JPG`.
- */
-const ASSET_EXTS = new Set([
-  'png',
-  'jpg',
-  'jpeg',
-  'gif',
-  'webp',
-  'avif',
-  'svg',
-  'mp4',
-  'webm',
-  'mov',
-  'mp3',
-  'wav',
-  'm4a',
-  'ogg',
-  'woff2',
-  'woff',
-  'ttf',
-  'otf',
-]);
-
 /** A 2 GB file in an assets dir is a mistake — don't move it silently. */
 const MAX_PUSH_BYTES = 512 * 1024 * 1024;
 
@@ -181,21 +157,63 @@ export function putTimeoutMs(bytes: number): number {
  *  final emit always go out regardless. */
 const PROGRESS_INTERVAL_MS = 200;
 
-function extOf(name: string): string {
-  const dot = name.lastIndexOf('.');
-  return dot < 0 ? '' : name.slice(dot + 1).toLowerCase();
+/**
+ * Canvas groups + the file-plane flag from `<designRoot>/config.json`. Read
+ * here rather than threaded through the worker protocol: the sweep runs
+ * out-of-process, and the config is the ONE source both processes share.
+ */
+function readProjectConfig(designRoot: string): {
+  canvasGroups?: readonly CanvasGroupLike[];
+  syncFiles: boolean;
+} {
+  let parsed: { canvasGroups?: unknown; linkedHub?: { syncFiles?: unknown } } | null = null;
+  try {
+    parsed = JSON.parse(readFileSync(path.join(designRoot, 'config.json'), 'utf8'));
+  } catch {
+    parsed = null;
+  }
+  return {
+    canvasGroups: Array.isArray(parsed?.canvasGroups)
+      ? (parsed.canvasGroups as CanvasGroupLike[])
+      : undefined,
+    syncFiles: process.env.MAUDE_SYNC_FILES === '1' || parsed?.linkedHub?.syncFiles === true,
+  };
+}
+
+/**
+ * Would `listPushableAssets` have returned this designRoot-relative path?
+ *
+ * The cheap, no-disk half of the same rule, for deciding whether an `fs:any`
+ * event is worth a sweep. Classifier-judged, with NO tree knowledge on
+ * purpose: this is a scheduling hint, and the conservative direction is
+ * answering true — a group `.css` whose sibling status is unknowable here
+ * answers true and lets the sweep itself decide with the disk in hand. A
+ * `false` means a file silently never uploads until the next boot, which is
+ * the bug this predicate exists to end.
+ */
+export function isPushableAssetRel(
+  rel: string,
+  canvasGroups?: readonly CanvasGroupLike[]
+): boolean {
+  if (typeof rel !== 'string' || !rel) return false;
+  const norm = rel.replace(/\\/g, '/');
+  return isFilePlaneClass(classifyProjectFile(norm, { canvasGroups }));
 }
 
 /**
- * Every pushable binary asset under designRoot, as a designRoot-relative path.
- * Walks into any directory named `assets` at any level (top-level `assets/`,
- * `system/<ds>/assets/`, …) and collects the asset-extension files inside it.
- * Skips runtime-state (`_*`), `.git`, `node_modules`. Missing root → [].
+ * Every pushable project file under designRoot, as a designRoot-relative
+ * path: the classifier's three flowing classes, judged against the walked
+ * snapshot (so a canvas's sibling css is recognized as canvas-owned and
+ * stays home). Skips runtime-state directories (`_*`), dotfiles,
+ * `node_modules`; refuses oversized files. Missing root → [].
  */
-export function listPushableAssets(designRoot: string): string[] {
-  const out: string[] = [];
-  // Walk the tree; once inside an `assets` dir, collect asset files below it.
-  const walk = (dir: string, rel: string, insideAssets: boolean): void => {
+export function listPushableAssets(
+  designRoot: string,
+  opts: { canvasGroups?: readonly CanvasGroupLike[]; syncFiles?: boolean } = {}
+): string[] {
+  const found: string[] = [];
+  const walk = (dir: string, rel: string, depth: number): void => {
+    if (depth > MAX_SEGMENTS) return;
     let entries: Dirent[];
     try {
       entries = readdirSync(dir, { withFileTypes: true });
@@ -204,26 +222,43 @@ export function listPushableAssets(designRoot: string): string[] {
     }
     for (const entry of entries) {
       const name = entry.name;
-      if (name.startsWith('_') || name === '.git' || name === 'node_modules') continue;
-      if (!SEGMENT.test(name)) continue; // dotfiles + odd charset
+      if (name.startsWith('.') || name === 'node_modules') continue;
+      if (name.startsWith('_') && entry.isDirectory()) continue;
       const childRel = rel ? `${rel}/${name}` : name;
-      if (childRel.length > MAX_REL_LEN || childRel.split('/').length > MAX_SEGMENTS) continue;
       if (entry.isDirectory()) {
-        walk(path.join(dir, name), childRel, insideAssets || name === 'assets');
-      } else if (entry.isFile()) {
-        if (!insideAssets) continue; // only files under some assets/ dir
-        if (!ASSET_EXTS.has(extOf(name))) continue;
-        try {
-          if (statSync(path.join(dir, name)).size > MAX_PUSH_BYTES) continue;
-        } catch {
-          continue;
-        }
-        out.push(childRel);
+        walk(path.join(dir, name), childRel, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue; // symlinks stay home
+      try {
+        if (statSync(path.join(dir, name)).size > MAX_PUSH_BYTES) continue;
+      } catch {
+        continue;
       }
+      found.push(childRel);
     }
   };
-  walk(designRoot, '', false);
-  return out.sort();
+  walk(designRoot, '', 1);
+
+  const cfg = readProjectConfig(designRoot);
+  const syncFiles = opts.syncFiles ?? cfg.syncFiles;
+  const fileSet = new Set(found);
+  const clsOpts = {
+    canvasGroups: opts.canvasGroups ?? cfg.canvasGroups,
+    hasFile: (r: string) => fileSet.has(r),
+  };
+  return found
+    .filter((rel) => {
+      const cls = classifyProjectFile(rel, clsOpts);
+      if (!isFilePlaneClass(cls)) return false;
+      if (syncFiles) return true;
+      // Flag OFF ⇒ today's DDR-217 lane, unchanged in reach: binary media
+      // under some `assets/` directory. The file plane (companion text, code
+      // modules, media outside assets/) waits for `linkedHub.syncFiles` /
+      // MAUDE_SYNC_FILES=1 — the flag gates ONLY the new plane.
+      return cls === 'inert-media' && rel.split('/').slice(0, -1).includes('assets');
+    })
+    .sort();
 }
 
 /** Where a given asset pushes: the bucket-backed route (top-level `assets/`) or
@@ -378,6 +413,11 @@ export async function pushAssets(opts: {
   hubUrl: string;
   /** Read at call time — silent renewal swaps the credential in place. */
   token: () => string;
+  /** Declared canvas groups; absent ⇒ read from `<designRoot>/config.json`
+   *  (the out-of-process worker's path — see `readProjectConfig`). */
+  canvasGroups?: readonly CanvasGroupLike[];
+  /** The file-plane flag; absent ⇒ read from config/env the same way. */
+  syncFiles?: boolean;
   fetchImpl?: typeof fetch;
   log?: Pick<Console, 'log' | 'warn'>;
   /** feature-sync-progress-modal — incremental progress (throttled; failures
@@ -406,7 +446,10 @@ export async function pushAssets(opts: {
   const base = hubUrl.replace(/\/+$/, '');
   const out: AssetPushResult = { pushed: [], skipped: 0, failed: [] };
 
-  const assets = listPushableAssets(designRoot);
+  const assets = listPushableAssets(designRoot, {
+    canvasGroups: opts.canvasGroups,
+    syncFiles: opts.syncFiles,
+  });
   // -Infinity seeds the throttle open, so the first emit always passes.
   let lastEmit = -Infinity;
   const emitProgress = (active: string | null, finished: boolean, force = false): void => {

package/apps/studio/sync/connection-state.ts

@@ -119,6 +119,16 @@ export interface ConnectionMonitor {
    *  `reason` (feature-sync-progress-modal) is the classification for an
    *  auth-rejected doc — our own vocabulary, ignored for other states. */
   noteDocState(slug: string, state: DocSyncState, reason?: string): void;
+  /**
+   * Drop every trace of a slug — its doc state, its rejection reason and its
+   * provider status.
+   *
+   * The counterpart to `noteDocState` for a canvas the runtime has RELEASED
+   * (deleted on disk, or moved out of a synced group). Without it a released
+   * canvas stays in the item list as a row that can never settle, and its stale
+   * provider status keeps voting in the session's online/offline derivation.
+   */
+  forgetDoc(slug: string): void;
   /** DDR-102 — real sync activity for a slug (reconcile done, hub-pushed flush
    *  applied): bumps `lastSyncAt` to now. */
   noteSyncActivity(slug: string): void;
@@ -422,6 +432,19 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       emit();
     },
 
+    forgetDoc(slug) {
+      if (stopped) return;
+      // A released canvas must leave the counters, not linger as a `pending` row
+      // nothing will ever settle. `providerStatuses` is keyed by the same slug
+      // (see `noteProviderStatus`'s `providerId`), so it is dropped here too —
+      // otherwise a deleted canvas's last known status would keep voting in
+      // `deriveState` forever and could hold the whole session in `offline`.
+      const had = docStates.delete(slug);
+      docReasons.delete(slug);
+      const hadStatus = providerStatuses.delete(slug);
+      if (had || hadStatus) emit();
+    },
+
     noteSyncActivity(slug) {
       if (stopped) return;
       lastSyncAt = now();