@1agh/maude 0.59.0 → 0.60.0

package/apps/studio/figma/to-artboard.ts

@@ -78,6 +78,12 @@ export interface PendingExport {
   placeholder: string;
   /** True when this export stands in for a whole cluster (D8 mitigation 2). */
   collapsed: boolean;
+  /**
+   * Figma's content hash for an IMAGE fill, when this export is a fill rather
+   * than a server-side render. The LOCAL door resolves it straight out of the
+   * archive (`images/<imageRef>`) with no network at all — DDR-221 D6.
+   */
+  imageRef?: string;
 }
 
 export interface ToArtboardOptions {
@@ -245,6 +251,35 @@ function emitNode(node: FigmaNode, depth: number, parentIsFlex: boolean, ctx: Em
   const name = identifierFromNodeId(node.id);
   const label = attrValue(node.name) || name;
 
+  // An IMAGE fill is a real picture, not a colour. It used to fall through to
+  // the generic leaf path, where `style-map` has nothing to say about it, and
+  // the node emitted as an EMPTY positioned div — the photo silently gone while
+  // the import reported success. Measured on a real export (2026-08-12).
+  const imageFill = (node.fills ?? []).find((f) => f.type === 'IMAGE' && f.visible && f.imageRef);
+  if (imageFill?.imageRef && !isVectorCluster(node)) {
+    const placeholder = `/assets/pending-${node.id.replace(/[^0-9]+/g, '-')}.png`;
+    ctx.pendingExports.push({
+      nodeId: node.id,
+      format: 'png',
+      placeholder,
+      collapsed: false,
+      imageRef: imageFill.imageRef,
+    });
+    ctx.report.add(node.id, node.type, 'asset-pending', 'image fill');
+    ctx.metrics.totalLeaves += 1;
+    const bb = node.absoluteBoundingBox;
+    const pos = positionStyle(node, parentIsFlex, ctx);
+    if (pos.absolute) ctx.metrics.absoluteLeaves += 1;
+    const style = {
+      ...pos.decls,
+      ...(bb ? { width: `${Math.round(bb.width)}px`, height: `${Math.round(bb.height)}px` } : {}),
+      objectFit: 'cover',
+    };
+    return [
+      `${pad}<img src=${JSON.stringify(placeholder)} alt=${JSON.stringify(label)} data-dc-element=${JSON.stringify(label)} style=${styleObjectLiteral(style, false)} />`,
+    ];
+  }
+
   // A whole vector cluster becomes ONE asset reference, never one per leaf.
   if (isVectorCluster(node)) {
     const placeholder = `/assets/pending-${node.id.replace(/[^0-9]+/g, '-')}.svg`;
@@ -450,9 +485,14 @@ export function toArtboard(
   const artboardGround = rawFillHex(frame);
   const bgProp = artboardGround ? `\n        background=${JSON.stringify(artboardGround)}` : '';
 
+  // Name the door that actually produced this. `--fig` (DDR-221) reads a local
+  // export with no network at all, which is a materially different provenance
+  // claim from a REST fetch — a banner that says `--frames` on a file nobody
+  // fetched is simply wrong.
+  const verb = doc.origin === 'fig' ? '--fig (offline, local export)' : '--frames';
   const tsx = `// Imported from Figma — THIRD-PARTY CONTENT (DDR-216).
 //
-// Generated by \`maude design import-figma --frames\` with deterministic code:
+// Generated by \`maude design import-figma ${verb}\` with deterministic code:
 // no vision model and no agent read this document (DDR-216 D1). That is the
 // structural difference from \`/design:import --reconstruct\` (DDR-174).
 //

package/apps/studio/http.ts

@@ -2468,6 +2468,53 @@ export function createHttp(
       return gitJson(await cloudApi.detach());
     },
 
+    // ── Resync (feature-sync-resync-and-out-of-process-sweep) ───────────────
+    // MAIN-ORIGIN ONLY: absent from BOTH CANVAS_SAFE_API and startCanvasServer's
+    // `routes` map (DDR-088's two-allowlist rule). Canvas content is untrusted
+    // (DDR-054) and must not be able to command the desktop to re-push a whole
+    // project — a canvas that could would be an amplification primitive against
+    // 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 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      const control = ctx.syncControl;
+      if (!control) {
+        return gitJson({
+          status: 200,
+          json: { ok: false, reason: 'no-supervisor', detail: 'Restart Maude to start syncing.' },
+        });
+      }
+      // REFUSED, not queued — see `SyncSupervisor.busy`. A second press must
+      // not buy a second full re-link of every canvas.
+      if (control.busy?.()) {
+        return gitJson({
+          status: 409,
+          json: { ok: false, reason: 'busy', detail: 'Syncing is already restarting.' },
+        });
+      }
+      // No argument: KEEP the configured hub. Only an explicit `null` unlinks,
+      // and this route must never be able to.
+      const sync = await control.restart();
+      return gitJson({ status: 200, json: { ok: true, sync } });
+    },
+
+    '/_api/sync/cancel-assets': async (req: Request) => {
+      // Cancel is scoped to the ASSET SWEEP: killing a reconnect mid-handshake
+      // is not a meaningful gesture, killing a multi-hundred-megabyte upload
+      // 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 (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      const cancelled = ctx.syncControl?.current?.()?.cancelAssetSweep() ?? false;
+      return gitJson({ status: 200, json: { ok: true, cancelled } });
+    },
+
     '/_api/github/identity': async (req: Request) => {
       if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
       if (!isTrustedRequestHost(req))

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

@@ -0,0 +1,84 @@
+// The asset sweep, in its own process — feature-sync-resync-and-out-of-process-sweep.
+//
+// WHY A SEPARATE PROCESS.
+//
+// The sweep crashes Bun 1.3.3 *when it runs alongside the dev server*, proven by
+// isolation: the identical sweep against the same live hub completes standalone
+// (182/182, 0 failures) and crash-loops in-process (three `Segmentation fault at
+// address 0x0` plus a bus error, then the supervisor gave up after 3 restarts).
+// Nobody has a fix for the fault itself, so the boundary is the fix: a fault
+// here costs the sweep, and the editor — canvases, browser UI, ACP panel —
+// stays up. The parent reports the dead child as a failed sweep.
+//
+// It is also what makes a Resync button safe to offer at all: pressing it
+// re-runs this, and a button that can kill the person's dev server is not a
+// button.
+//
+// PROTOCOL. argv gives the design root, the hub URL and a file holding the
+// credential. stdout carries NDJSON — one tagged JSON object per line:
+//
+//   {"t":"progress", …AssetPushProgress}   many, throttled by pushAssets
+//   {"t":"result",   …AssetPushResult}     exactly one, on a clean finish
+//   {"t":"error", "message": "…"}          exactly one, on a thrown sweep
+//
+// Tagged rather than positional ("the last line is the result") so a parent
+// reading a truncated stream can still tell a final answer from a progress
+// tick. Nothing else may reach stdout — one stray `console.log` from an import
+// would land mid-stream — so diagnostics go to stderr, which the parent logs.
+//
+// THE CREDENTIAL ARRIVES IN A FILE, NEVER IN ARGV. `ps` is world-readable on
+// every platform this ships to; a hub token on a command line is a hub token
+// handed to every other user on the machine. The file is written 0600 by the
+// parent and unlinked when the sweep ends. It is re-read per call, not cached,
+// so a parent that rewrites it after a silent renewal is picked up mid-sweep.
+
+import { readFileSync } from 'node:fs';
+
+import { type AssetPushProgress, type AssetPushResult, pushAssets } from './asset-push.ts';
+
+const [, , designRoot, hubUrl, tokenFile] = process.argv;
+
+/** One NDJSON line. Synchronous — ordering with the result line is the contract. */
+function emit(line: { t: 'progress' | 'result' | 'error' } & Record<string, unknown>): void {
+  process.stdout.write(`${JSON.stringify(line)}\n`);
+}
+
+async function main(): Promise<void> {
+  if (!designRoot || !hubUrl || !tokenFile) {
+    emit({ t: 'error', message: 'usage: <designRoot> <hubUrl> <tokenFile>' });
+    process.exit(2);
+  }
+
+  // Read at call time — `pushAssets` asks per request, and a renewal mid-sweep
+  // rewrites the file underneath us. A read that fails (the parent unlinked it
+  // during teardown) falls back to the last value we saw rather than sending an
+  // empty Authorization, which the hub would answer 401 for every remaining
+  // file and report as 182 failures instead of one dead sweep.
+  let lastToken = '';
+  const token = (): string => {
+    try {
+      lastToken = readFileSync(tokenFile, 'utf8').trim() || lastToken;
+    } catch {
+      /* keep the last good one */
+    }
+    return lastToken;
+  };
+
+  const result: AssetPushResult = await pushAssets({
+    designRoot,
+    hubUrl,
+    token,
+    // stderr, never stdout — stdout is the protocol.
+    log: {
+      log: (...a: unknown[]) => process.stderr.write(`${a.join(' ')}\n`),
+      warn: (...a: unknown[]) => process.stderr.write(`${a.join(' ')}\n`),
+    },
+    onProgress: (p: AssetPushProgress) => emit({ t: 'progress', ...p }),
+  });
+  emit({ t: 'result', ...result });
+}
+
+main().catch((err) => {
+  emit({ t: 'error', message: String((err as Error)?.message ?? err).slice(0, 2000) });
+  process.exit(1);
+});

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

@@ -136,10 +136,35 @@ const ERROR_SNIPPET_CHARS = 80;
  */
 const UPLOAD_CONNECTION_HEADERS = { connection: 'close' } as const;
 
+/**
+ * THE PER-REQUEST TIME BUDGETS BELOW STAY — reviewed and kept, RCA step 3
+ * (feature-sync-resync-and-out-of-process-sweep, Task 7).
+ *
+ * They were suspects: the crash reports went from `abort_signal(2)` to
+ * `abort_signal(79)` in the same change that introduced them, which reads like
+ * a cause. Two things settle it the other way.
+ *
+ * First, the count is what a bounded sweep LOOKS like — 79 in-flight budgets
+ * 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.
+ *
+ * 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
+ * invisibility this whole feature exists to end. So they stay.
+ */
+
 /** HEAD is a small, bodyless probe — a hub that has not answered in 30 s is not
  *  about to. */
 const HEAD_TIMEOUT_MS = 30_000;
 
+/** The batch probe asks about a whole project at once, and the hub may have to
+ *  reach the object store for a few hundred keys — but it is still one small
+ *  request, so a minute is generous. */
+const PROBE_TIMEOUT_MS = 60_000;
+
 /**
  * How long one upload may take before the sweep abandons it: a fixed floor plus
  * an allowance for the bytes at a deliberately pessimistic 100 kB/s, capped.
@@ -214,6 +239,48 @@ function routeFor(rel: string): { url: string } {
   return { url: `/_asset-file/${rel.split('/').map(encodeURIComponent).join('/')}` };
 }
 
+/**
+ * Ask the hub, in ONE request, which of these it already holds — or null when
+ * this hub cannot answer (then the caller falls back to per-file probes).
+ *
+ * WHY THIS EXISTS (RCA 2026-08-11 part 2). The sweep used to ask per file with
+ * `HEAD`, and on a Cloud cell a HEAD never arrives as a HEAD — it is converted
+ * to GET before it reaches the hub. So the DS half's probe answered `405` and
+ * the sweep re-uploaded that project's ENTIRE asset set on every boot, while
+ * the bucket half's converted probe took the hub's GET branch and pulled whole
+ * objects out of R2 to answer an existence question. `POST` survives the trip,
+ * and one request replaces N.
+ *
+ * A hub that does not know this route answers 404/405 — that is NOT "it holds
+ * nothing", it is "ask the old way", so it returns null rather than an empty
+ * set. Getting that backwards would skip every upload against every hub older
+ * than this change.
+ */
+async function probePresent(ctx: {
+  fetchImpl: typeof fetch;
+  base: string;
+  headers: Record<string, string>;
+  paths: string[];
+}): Promise<Set<string> | null> {
+  try {
+    const res = await ctx.fetchImpl(`${ctx.base}/_asset-probe`, {
+      method: 'POST',
+      headers: { ...ctx.headers, 'content-type': 'application/json' },
+      body: JSON.stringify({ paths: ctx.paths }),
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { present?: unknown };
+    // Hub-supplied (DDR-054): keep only strings we actually asked about, so a
+    // malformed or hostile answer can never make us skip a file we never named.
+    if (!Array.isArray(data?.present)) return null;
+    const asked = new Set(ctx.paths);
+    return new Set(data.present.filter((p): p is string => typeof p === 'string' && asked.has(p)));
+  } catch {
+    return null;
+  }
+}
+
 /** `Retry-After: <seconds>` → ms, clamped. Only the delta-seconds form is
  *  parsed; the HTTP-date form is not something our hub emits. */
 function retryAfterMs(header: string | null): number {
@@ -363,17 +430,39 @@ export async function pushAssets(opts: {
     }
   };
 
+  // One question for the whole set, when the hub can answer it. Null = this hub
+  // predates the route, so every file falls back to its own probe below.
+  const known =
+    assets.length > 0
+      ? await probePresent({
+          fetchImpl,
+          base,
+          headers: { authorization: `Bearer ${opts.token()}` },
+          paths: assets,
+        })
+      : null;
+
   for (const rel of assets) {
     emitProgress(rel, false);
     const url = `${base}${routeFor(rel).url}`;
     const headers = { authorization: `Bearer ${opts.token()}` };
+    if (known) {
+      if (known.has(rel)) {
+        out.skipped += 1;
+        continue;
+      }
+      // The batch answered, and it said this one is missing — no per-file probe
+      // can add anything, so go straight to the upload.
+    }
     try {
-      const head = await fetchImpl(url, {
-        method: 'HEAD',
-        headers,
-        signal: AbortSignal.timeout(HEAD_TIMEOUT_MS),
-      });
-      if (head.ok) {
+      const head = known
+        ? null
+        : await fetchImpl(url, {
+            method: 'HEAD',
+            headers,
+            signal: AbortSignal.timeout(HEAD_TIMEOUT_MS),
+          });
+      if (head?.ok) {
         out.skipped += 1;
         continue;
       }
@@ -381,7 +470,12 @@ export async function pushAssets(opts: {
       // anyway just streams megabytes at a door that already said no. The
       // cloud studio door answers exactly this for a route the deployed hub
       // does not have yet, once per asset, for the whole DS asset set.
-      if (head.status === 401 || head.status === 403) {
+      //
+      // Only 401/403 mean that. Every OTHER refusal — notably the 405 a cell
+      // returns when it turned our HEAD into a GET — means "I cannot answer",
+      // NOT "I do not have it", so it falls through to the upload rather than
+      // being read as a refusal.
+      if (head && (head.status === 401 || head.status === 403)) {
         out.failed.push({ key: rel, reason: await failureReason(head) });
         emitProgress(rel, false, true);
         continue;

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

@@ -0,0 +1,262 @@
+// The parent half of the out-of-process asset sweep — feature-sync-resync-and-
+// out-of-process-sweep. The child is `asset-push-worker.ts`; read its header
+// first, it carries the protocol and the reason the boundary exists at all.
+//
+// What this module owns:
+//
+//   • spawning the child the way the packaged app can actually run it (DDR-177 —
+//     the compiled sidecar re-entered as a JS runtime, never a user-installed
+//     `bun`), reusing the sandbox's own resolver so the two cannot drift;
+//   • handing over the credential through a 0600 file that is unlinked when the
+//     sweep ends, because argv is world-readable via `ps`;
+//   • turning NDJSON lines back into the `AssetPushProgress` the panel already
+//     consumes, so `_sync.json`, the WS fanout and the Sync panel are untouched;
+//   • making a DEAD CHILD a reported failure instead of a silent stall. Before
+//     the boundary, a fault took the dev server with it; after it, the sweep is
+//     the only casualty and the panel has to say so — an asset lane frozen at
+//     "92 of 182" forever is the failure mode this whole change is about.
+
+import { mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { resolveBunPath, workerEnv } from '../canvas-build-sandbox.ts';
+import { DEV_SERVER_ROOT } from '../paths.ts';
+import type { AssetPushProgress, AssetPushResult } from './asset-push.ts';
+
+/** A stray unterminated flood must not grow the parent's heap. */
+const MAX_LINE_BYTES = 1024 * 1024;
+
+/** How much of the child's stderr is kept for the failure message. */
+const STDERR_KEEP = 2000;
+
+/** Grace between SIGTERM and SIGKILL when a sweep is cancelled. */
+const KILL_GRACE_MS = 2000;
+
+/**
+ * How often the parent checks whether the credential has been renewed.
+ *
+ * A sweep can run for minutes; `scheduleRenewal` can swap the runtime's token
+ * underneath it. In-process that was free (the old call read `() => token` per
+ * request). Across the boundary the child re-reads its file per request, so the
+ * PARENT has to keep that file current or a renewal mid-sweep turns every
+ * remaining upload into a 401.
+ */
+const TOKEN_REFRESH_MS = 30_000;
+
+export interface AssetSweepHandle {
+  /** The sweep's result, or `null` when it did not finish (crash / cancel). */
+  done: Promise<AssetPushResult | null>;
+  /** Stop the sweep. Idempotent; safe after completion. */
+  cancel(): void;
+}
+
+/** Absolute path to the child entry, resolved per DDR-045 (never a bunfs path). */
+export function assetWorkerScript(): string {
+  return join(DEV_SERVER_ROOT, 'sync', 'asset-push-worker.ts');
+}
+
+export function runAssetSweep(opts: {
+  designRoot: string;
+  hubUrl: string;
+  /**
+   * Read at call time — silent renewal swaps the credential in place, exactly
+   * as the in-process sweep's `() => token` did. The value is written 0600 to a
+   * temp file the child re-reads, and re-written when it changes.
+   */
+  token: () => string;
+  onProgress?: (p: AssetPushProgress) => void;
+  env?: NodeJS.ProcessEnv;
+  log?: Pick<Console, 'log' | 'warn'>;
+  /** Test injection — the spawn and the script path. */
+  spawn?: typeof Bun.spawn;
+  script?: string;
+}): AssetSweepHandle {
+  const log = opts.log ?? console;
+  const spawn = opts.spawn ?? Bun.spawn;
+  const env = opts.env ?? process.env;
+
+  let cancelled = false;
+  let child: Bun.Subprocess<'ignore', 'pipe', 'pipe'> | null = null;
+  let killTimer: ReturnType<typeof setTimeout> | null = null;
+  // The last thing the child told us — the base for the final emit we have to
+  // synthesize ourselves when it never gets to send one.
+  let last: AssetPushProgress | null = null;
+
+  const emit = (p: AssetPushProgress): void => {
+    last = p;
+    try {
+      opts.onProgress?.(p);
+    } catch (err) {
+      log.warn(`[sync/assets] progress listener threw: ${(err as Error).message}`);
+    }
+  };
+
+  /**
+   * The sweep stopped without finishing. Say so ONCE, in the payload the panel
+   * already reads, keeping whatever counts we had — a lane that stops at "92 of
+   * 182" and stays there is the exact lie this replaces.
+   */
+  const emitStopped = (reason: string): void => {
+    const base = last;
+    const failures = (base?.failures ?? []).slice();
+    failures.push({ key: '(sweep)', reason });
+    emit({
+      total: base?.total ?? 0,
+      done: base?.done ?? 0,
+      pushed: base?.pushed ?? 0,
+      skipped: base?.skipped ?? 0,
+      failedCount: (base?.failedCount ?? 0) + 1,
+      failures,
+      active: null,
+      finished: true,
+    });
+  };
+
+  const done = (async (): Promise<AssetPushResult | null> => {
+    // A temp DIRECTORY, so the 0600 file is also inside a 0700 dir — the file
+    // mode alone is enough on every platform we ship to, but a private parent
+    // costs nothing and closes the window between create and chmod.
+    const dir = mkdtempSync(join(tmpdir(), 'maude-sweep-'));
+    const tokenFile = join(dir, 'hub-token');
+    let refresh: ReturnType<typeof setInterval> | null = null;
+    try {
+      // Temp-then-rename on every write, including the first: the child reads
+      // this file per request, and a plain overwrite can be observed half-done.
+      let written = '';
+      const putToken = (value: string): void => {
+        if (!value || value === written) return;
+        const tmp = `${tokenFile}.tmp`;
+        writeFileSync(tmp, value, { mode: 0o600 });
+        renameSync(tmp, tokenFile);
+        written = value;
+      };
+      putToken(opts.token());
+      refresh = setInterval(() => {
+        try {
+          putToken(opts.token());
+        } catch (err) {
+          log.warn(
+            `[sync/assets] could not refresh the sweep credential: ${(err as Error).message}`
+          );
+        }
+      }, TOKEN_REFRESH_MS);
+      refresh.unref?.();
+
+      const script = opts.script ?? assetWorkerScript();
+      try {
+        child = spawn([resolveBunPath(env), script, opts.designRoot, opts.hubUrl, tokenFile], {
+          env: workerEnv(env),
+          cwd: opts.designRoot,
+          stdin: 'ignore',
+          stdout: 'pipe',
+          stderr: 'pipe',
+        }) as Bun.Subprocess<'ignore', 'pipe', 'pipe'>;
+      } catch (err) {
+        // Never fall back to sweeping in-process: that is the crash this whole
+        // boundary exists to survive, and it would come back invisibly.
+        emitStopped(`the asset sweep could not start: ${(err as Error).message}`);
+        return null;
+      }
+
+      // Cancel may have been called between the handle being returned and the
+      // spawn landing — honour it rather than letting a doomed sweep run.
+      if (cancelled) child.kill('SIGTERM');
+
+      let result: AssetPushResult | null = null;
+      let childError: string | null = null;
+      let stderr = '';
+
+      const drainErr = (async () => {
+        try {
+          stderr = (await new Response(child?.stderr).text()).slice(-STDERR_KEEP);
+        } catch {
+          /* the stream died with the process — nothing to keep */
+        }
+      })();
+
+      let buf = '';
+      const decoder = new TextDecoder();
+      try {
+        for await (const chunk of child.stdout as ReadableStream<Uint8Array>) {
+          buf += decoder.decode(chunk, { stream: true });
+          let nl = buf.indexOf('\n');
+          while (nl !== -1) {
+            const line = buf.slice(0, nl);
+            buf = buf.slice(nl + 1);
+            nl = buf.indexOf('\n');
+            if (!line.trim()) continue;
+            let parsed: { t?: string; message?: unknown } & Record<string, unknown>;
+            try {
+              parsed = JSON.parse(line);
+            } catch {
+              // Defensive: a stray write from an import would land mid-stream.
+              // Dropping the line keeps the sweep readable instead of ending it.
+              continue;
+            }
+            // The tag is transport, not payload — `progress` lands in
+            // `_sync.json` and every open tab, so it goes out the way the
+            // in-process sweep used to emit it, with no extra field.
+            const { t, ...payload } = parsed;
+            if (t === 'progress') emit(payload as unknown as AssetPushProgress);
+            else if (t === 'result') result = payload as unknown as AssetPushResult;
+            else if (t === 'error') childError = String(parsed.message ?? 'unknown');
+          }
+          if (buf.length > MAX_LINE_BYTES) buf = '';
+        }
+      } catch (err) {
+        childError ??= `the sweep's output could not be read: ${(err as Error).message}`;
+      }
+
+      await child.exited;
+      await drainErr;
+      if (killTimer) clearTimeout(killTimer);
+
+      const code = child.exitCode;
+      const signal = child.signalCode;
+
+      if (cancelled) {
+        emitStopped('cancelled');
+        return null;
+      }
+      if (result && code === 0) return result;
+
+      // Everything below is a sweep that did not finish. Name WHY as concretely
+      // as the child let us — a signal is the segfault class this boundary was
+      // built for, and the panel saying "stopped unexpectedly (SIGSEGV)" is what
+      // turns an invisible stall into a bug report.
+      const why = childError
+        ? `the asset sweep failed: ${childError}`
+        : signal
+          ? `the asset sweep stopped unexpectedly (${signal})`
+          : `the asset sweep exited with code ${code}`;
+      log.warn(`[sync/assets] ${why}${stderr ? `\n${stderr.trim()}` : ''}`);
+      emitStopped(why);
+      return null;
+    } finally {
+      if (refresh) clearInterval(refresh);
+      child = null;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  })();
+
+  return {
+    done,
+    cancel(): void {
+      if (cancelled) return;
+      cancelled = true;
+      if (!child) return;
+      child.kill('SIGTERM');
+      // A child wedged inside a socket read will not notice SIGTERM; the whole
+      // point of cancel is that it always ends.
+      killTimer = setTimeout(() => {
+        try {
+          child?.kill('SIGKILL');
+        } catch {
+          /* already gone */
+        }
+      }, KILL_GRACE_MS);
+      killTimer.unref?.();
+    },
+  };
+}