@1agh/maude 1.0.9 → 1.2.0

package/apps/studio/exporters/pdf.ts

@@ -42,6 +42,8 @@ import { readArtboardPrintProp } from '../canvas-edit.ts';
 import { computeMarksGeometry, MARK_STROKE_PT, requiredSlugPt } from '../print/marks.ts';
 import { CSS_DPI, getPaperPreset, mmToPt, resolveBleedMm, trimSizeMm } from '../print/units.ts';
 import { exportShimPath, runShim } from './_runtime.ts';
+import type { ExportDegradation } from './degraded.ts';
+import { outlinePdf } from './ghostscript.ts';
 import {
   canvasShellUrl,
   type ExportContext,
@@ -49,6 +51,7 @@ import {
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
+import { analyzePdfFonts, describeFontProblem, unprintableFonts } from './pdf-fonts.ts';
 import { clampDpi } from './png.ts';
 import type { Target } from './scope.ts';
 
@@ -205,6 +208,121 @@ export function parsePageFit(raw: unknown): string | null {
   return getPaperPreset(raw) ? raw : null;
 }
 
+/**
+ * How the export should treat text (issue #116).
+ *
+ *  - `keep`    — today's behaviour. Text stays selectable and searchable; the
+ *                fonts are whatever Chromium emitted. A preflight NOTICE is
+ *                attached when some of those are unprintable.
+ *  - `embed`   — assert every font is a real embedded font program. Type 3 is
+ *                a hard failure, named — never a silent pass.
+ *  - `outline` — every glyph becomes a vector path (Ghostscript). Print-safe
+ *                by construction; text is no longer selectable and the file
+ *                can grow substantially.
+ */
+export type PdfTextMode = 'keep' | 'embed' | 'outline';
+
+/**
+ * `options.text` — TOP-LEVEL, not nested under `pdfPrint`, deliberately.
+ * `pdfPrint`'s presence is what switches the boxes/marks post-pass on, and
+ * text handling is orthogonal to that: a plain non-print PDF can carry Type 3
+ * fonts just as easily as a leaflet can.
+ *
+ * Degrades to `keep` on anything unrecognised rather than throwing, per this
+ * adapter's standing rule that a malformed options bag must never break an
+ * export (`ExportOptions` is free-form with no schema gate upstream).
+ */
+export function parsePdfText(raw: unknown): PdfTextMode {
+  return raw === 'embed' || raw === 'outline' ? raw : 'keep';
+}
+
+/**
+ * Classify the fonts in the bytes we are about to hand back.
+ *
+ * On the SAVED BYTES, not the in-memory `PDFDocument`, and that is load-bearing:
+ * pdf-lib DEFERS `embedPage` until flush, so before a save the `pageFit` path's
+ * page XObject is a dangling ref and a font walk finds nothing at all. Analysing
+ * the document would silently report "no fonts" for exactly the scale-to-paper
+ * exports print shops receive. `test/pdf-font-preflight.test.ts` pins both
+ * halves of that.
+ *
+ * Returns null when pdf-lib cannot read the bytes. A preflight is a warning
+ * mechanism; it must never become a new way for a successful export to fail.
+ */
+async function analyzeFinalBytes(bytes: Uint8Array) {
+  try {
+    const doc = await PDFDocument.load(bytes, { updateMetadata: false });
+    return analyzePdfFonts(doc);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Apply `options.text` to the assembled bytes — the one place all three modes
+ * are decided, so the fast path and the post-pass path can never disagree about
+ * what `embed` means.
+ */
+export async function applyTextMode(
+  bytes: Uint8Array,
+  mode: PdfTextMode,
+  hooks?: ExportHooks
+): Promise<{ body: Uint8Array; degraded?: ExportDegradation }> {
+  if (mode === 'outline') {
+    const outlined = await outlinePdf(bytes, { signal: hooks?.signal });
+    // Ghostscript exited 0 — but "it ran" is not "it worked". Re-run the same
+    // preflight over its output: if a font survived, the file LOOKS converted
+    // and is not, which is the failure this whole feature exists to make
+    // impossible. Better to fail than to hand back a plausible lie.
+    const after = await analyzeFinalBytes(outlined);
+    if (after && after.length) {
+      throw new Error(
+        `Ghostscript reported success but ${after.length} font(s) survived outlining ` +
+          `(${after.map((f) => f.name).join(', ')}). The PDF was not converted to curves; ` +
+          'do not send it to print.'
+      );
+    }
+    assertOutlinedSizeOk(outlined.byteLength);
+    return { body: outlined };
+  }
+
+  const fonts = await analyzeFinalBytes(bytes);
+  if (!fonts) return { body: bytes };
+  const bad = unprintableFonts(fonts);
+  if (!bad.length) return { body: bytes };
+
+  const { reason, remedy } = describeFontProblem(bad);
+  if (mode === 'embed') {
+    throw new Error(`text=embed: ${reason} ${remedy}`);
+  }
+  return {
+    body: bytes,
+    degraded: { fontsNotEmbedded: bad.map((f) => f.name), reason, remedy },
+  };
+}
+
+/**
+ * Outlining trades file size for print safety — glyphs become path data, and a
+ * photo-heavy piece can grow by an order of magnitude. That is a legitimate
+ * print deliverable, not a bug, so this reuses the SAME generous ceiling
+ * `assertTotalSizeOk` applies to captures rather than a tighter one; it exists
+ * to catch a runaway, not to cap ordinary print output.
+ *
+ * Checked separately because `assertTotalSizeOk` runs on the CAPTURED files,
+ * before assembly and long before outlining — the pass that actually creates
+ * the growth was downstream of every existing guard.
+ */
+export function assertOutlinedSizeOk(byteLength: number): void {
+  if (byteLength <= MAX_TOTAL_OUTPUT_BYTES) return;
+  const mb = Math.round(byteLength / 1024 / 1024);
+  const maxMb = Math.round(MAX_TOTAL_OUTPUT_BYTES / 1024 / 1024);
+  throw new Error(
+    `Outlined PDF is too large (~${mb}MB, limit ~${maxMb}MB) — converting text to curves ` +
+      'grows the file. Try exporting fewer artboards per file, a lower DPI, or ' +
+      'text=embed (which verifies the fonts without converting them).'
+  );
+}
+
 /**
  * PDF's own device-scale resolver — deliberately NOT `png.ts`'s
  * `resolveDeviceScale`, which defaults an absent `dpi` to `clampScale(undefined)`
@@ -361,6 +479,7 @@ export async function run(
   const timeoutSec = (options.timeoutSec as number | undefined) ?? 12;
   const printOpts = parsePdfPrintOptions(options.pdfPrint);
   const pageFit = parsePageFit(options.pageFit);
+  const textMode = parsePdfText(options.text);
   // Dogfood follow-up — raster CONTENT on the artboard (a dropped photo, a
   // large-format piece authored at a fraction of its physical size) needs a
   // real deviceScaleFactor to embed at print density; the page itself stays
@@ -407,11 +526,25 @@ export async function run(
     // Fast path — no print/pageFit options given: pass Chromium's vector PDF
     // straight through, exactly as before this feature (zero pdf-lib
     // round-trip overhead for the common "just export a PDF" case).
+    //
+    // The font preflight (`applyTextMode`) DOES parse here, and that is a
+    // deliberate cost. This path is what `/design:export pdf` with no options
+    // takes — i.e. the most likely way someone exports a leaflet — and a PDF
+    // that a print shop will reject while saying nothing is precisely the bug
+    // being fixed. The parse is a tokenize + object-table build (raw streams
+    // are copied by length, never decoded), and it degrades to silence rather
+    // than an error on a PDF pdf-lib cannot read.
     if (!needsPostPass) {
       const [only] = written;
       if (written.length === 1 && only) {
         const bytes = new Uint8Array(readFileSync(only.path));
-        return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+        const finished = await applyTextMode(bytes, textMode, hooks);
+        return {
+          filename: `${baseSlug}.pdf`,
+          contentType: 'application/pdf',
+          body: finished.body,
+          ...(finished.degraded ? { degraded: finished.degraded } : {}),
+        };
       }
       const out = await PDFDocument.create();
       for (const w of written) {
@@ -420,7 +553,13 @@ export async function run(
         for (const page of pages) out.addPage(page);
       }
       const bytes = await out.save();
-      return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+      const finished = await applyTextMode(bytes, textMode, hooks);
+      return {
+        filename: `${baseSlug}.pdf`,
+        contentType: 'application/pdf',
+        body: finished.body,
+        ...(finished.degraded ? { degraded: finished.degraded } : {}),
+      };
     }
 
     // Post-pass path — every page goes through pdf-lib (single-page case now
@@ -473,7 +612,17 @@ export async function run(
       }
     }
     const bytes = await out.save();
-    return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+    // Text handling runs LAST, on the fully assembled document: the boxes are
+    // set and the vector crop/registration marks are drawn, so they are part of
+    // what Ghostscript preserves rather than something applied to an already
+    // outlined file (pdf-lib could not re-open and re-mark it as cleanly).
+    const finished = await applyTextMode(bytes, textMode, hooks);
+    return {
+      filename: `${baseSlug}.pdf`,
+      contentType: 'application/pdf',
+      body: finished.body,
+      ...(finished.degraded ? { degraded: finished.degraded } : {}),
+    };
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }

package/apps/studio/exporters/remote.ts

@@ -54,6 +54,41 @@ function safeArtifactName(raw: string | null, format: Format): string {
   return base.slice(0, 255);
 }
 
+/**
+ * Reduce whatever the render service put in `x-maude-degraded` to a value the
+ * rest of the system can hold, mirroring `safeArtifactName` above.
+ *
+ * The header was previously `JSON.parse`d and cast straight to
+ * `ExportDegradation` — the one field on this boundary that skipped the file's
+ * own "everything crossing back is untrusted" rule. It mattered less while the
+ * only consumer read a boolean; it matters now that a degradation can carry a
+ * `fontsNotEmbedded` ARRAY which `client/export-center.jsx` renders with
+ * `.join(', ')`. A hostile or simply mixed-version worker sending an object
+ * there turns the export panel into a TypeError, and unbounded `reason` /
+ * `remedy` strings land verbatim in the on-disk history ledger.
+ *
+ * Returns undefined for anything unusable — a malformed note must never cost a
+ * real artifact, which is the same reason the caller swallows parse errors.
+ */
+function safeDegradation(raw: unknown): ExportDegradation | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const o = raw as Record<string, unknown>;
+  const text = (v: unknown, max: number): string | undefined =>
+    typeof v === 'string' && v ? v.slice(0, max) : undefined;
+
+  const reason = text(o.reason, 2000);
+  if (!reason) return undefined; // `reason` is the only required field
+  const fonts = Array.isArray(o.fontsNotEmbedded)
+    ? o.fontsNotEmbedded.flatMap((f) => text(f, 200) ?? []).slice(0, 50)
+    : undefined;
+  return {
+    reason,
+    ...(o.audioDropped === true ? { audioDropped: true } : {}),
+    ...(fonts?.length ? { fontsNotEmbedded: fonts } : {}),
+    ...(text(o.remedy, 2000) ? { remedy: text(o.remedy, 2000) } : {}),
+  };
+}
+
 /** Read a response body with a hard byte ceiling — `arrayBuffer()` has none. */
 async function readCapped(res: Response, max: number): Promise<Uint8Array> {
   const declared = Number(res.headers.get('content-length'));
@@ -274,7 +309,7 @@ export async function renderRemotely(args: {
       const raw = /^[A-Za-z0-9+/=]+$/.test(degradedHeader)
         ? Buffer.from(degradedHeader, 'base64').toString('utf8')
         : degradedHeader;
-      degraded = JSON.parse(raw) as ExportDegradation;
+      degraded = safeDegradation(JSON.parse(raw));
     } catch {
       /* a malformed degradation note must not fail a real artifact */
     }

package/apps/studio/fs-watch.ts

@@ -15,6 +15,34 @@ export interface FsWatch {
 
 const DEBOUNCE_MS = 50;
 
+/**
+ * Runtime-state DIRECTORIES with no `fs:any` subscriber — see the note at the
+ * skip site for why this is deliberately NOT the sync taxonomy.
+ *
+ * `_comments/`, `_canvas-state/` and `_state/` are POINTEDLY absent: the first
+ * drives comment collab, and the other two are small and per-user, so there is
+ * no volume argument for suppressing them and a real risk in guessing. Add to
+ * this list only after confirming no `bus.on('fs:any' | 'fs:json' | …)`
+ * subscriber acts on the path.
+ */
+const RUNTIME_DIRS = ['_history', '_chat', '_trash', '_smoke'] as const;
+
+/**
+ * True when `rel` is one of `RUNTIME_DIRS` or a path inside one, on either
+ * separator (`fs.watch` hands back platform-native separators on Windows).
+ *
+ * Matching the BARE directory name is load-bearing, not tidiness: macOS raises
+ * an event for the containing directory as well as the file, so a write to
+ * `_chat/c-1.jsonl` arrives as BOTH `_chat/c-1.jsonl` and a bare `_chat`.
+ * Suppressing only the prefixed form would leave every streamed ACP update
+ * still waking every `fs:any` subscriber — the wakeup this list exists to stop.
+ */
+function isUnderRuntimeDir(rel: string): boolean {
+  return RUNTIME_DIRS.some(
+    (d) => rel === d || rel.startsWith(`${d}/`) || rel.startsWith(`${d}${path.sep}`)
+  );
+}
+
 export function createFsWatch(ctx: Context): FsWatch {
   let watcher: ReturnType<typeof watch> | null = null;
   const seen = new Map<string, number>();
@@ -48,10 +76,26 @@ export function createFsWatch(ctx: Context): FsWatch {
       watcher = watch(ctx.paths.designRoot, { recursive: true }, (_event, filename) => {
         if (!filename) return;
         // Skip our own runtime artifacts.
+        //
+        // NOT `isRuntimeStateRel` (sync/file-membership.ts), even though this
+        // list looks like a narrower copy of it. That classifier answers "may
+        // this file travel to a peer", and it excludes `_comments/` — but
+        // `_comments/` IS needed on this bus: collab/index.ts matches
+        // `^_comments/(.+)\.json$` on `fs:any`, and git/watch.ts treats it as
+        // versionable. Routing this list through the sync taxonomy would
+        // silently kill comment collaboration. The two lists answer different
+        // questions and are deliberately not the same list.
+        //
+        // What IS added here (#119) are the high-volume runtime directories
+        // with no `fs:any` subscriber. `_chat/` matters most: the bridge
+        // appends to it on every streamed update, so each chunk of an agent
+        // turn was raising an `fs:any` that woke canvas-list-watch, the
+        // activity tracker and gitWatch (the last running git status against
+        // the project's whole repo) for a file none of them can act on.
         if (filename.startsWith('_server.json')) return;
         if (filename.startsWith('_active.json')) return;
         if (filename.startsWith('_sync.json')) return;
-        if (filename.startsWith(`_history${path.sep}`) || filename.startsWith('_history/')) return;
+        if (isUnderRuntimeDir(filename)) return;
         emit(filename);
       });
     } catch (err) {

package/apps/studio/http.ts

@@ -4509,7 +4509,13 @@ export function createHttp(
       const serviceUrl = process.env.MAUDE_RENDER_URL;
       if (!serviceUrl) return Response.json({ ok: false, lane: resolveRenderLane() });
       try {
-        const r = await fetch(`${serviceUrl.replace(/\/+$/, '')}/_health`, {
+        // `globalThis.fetch`, never a bare `fetch(` — this module scope has
+        // carried a same-named local handler before, and a bare call silently
+        // resolved to it instead of the network (RCA
+        // issue-report-a-bug-http-500). The handler is `handleFallthrough`
+        // today; the rule stands so a rename can never reintroduce that, and
+        // `report-proxy.test.ts` fails the build on any bare call site here.
+        const r = await globalThis.fetch(`${serviceUrl.replace(/\/+$/, '')}/_health`, {
           signal: AbortSignal.timeout(8_000),
         });
         const body = (await r.json().catch(() => null)) as { ok?: boolean } | null;

package/apps/studio/mem.ts

@@ -5,8 +5,30 @@
 // not the primary path. The primary path is the explicit `iframe:closed` event
 // emitted on the bus, which calls cleanupFn synchronously.
 
-const HEAP_WARN_BYTES = 256 * 1024 * 1024; // 256 MB — log only
-const HEAP_PANIC_BYTES = 384 * 1024 * 1024; // 384 MB — force GC
+// #119 — these thresholds are read against `rss`, NOT `heapTotal`.
+//
+// The watch originally polled `process.memoryUsage().heapTotal`, which is a V8
+// intuition that does not carry over: under Bun/JSC it barely moves for the
+// allocations that actually grow this process. Measured while the server read
+// 554 MB of chat transcripts, `rss` peaked at 1.29 GB while `heapTotal` peaked
+// at 5 MB — three orders of magnitude apart. Neither threshold below was
+// reachable, so the one guard written for a runaway-memory failure could never
+// fire, and the `[mem]` line that would have named the problem never reached
+// the log ring (and therefore never reached a bug report's `serverLogTail`).
+// The bug it was meant to catch shipped past it in silence.
+//
+// `rss` is the number the user sees in Activity Monitor, which is also the
+// number they report. Sized for a server whose steady state is a few hundred
+// MB: WARN is "something is wrong", PANIC is "intervene before the machine
+// starts swapping".
+const RSS_WARN_BYTES = 1024 * 1024 * 1024; // 1 GB — log only
+const RSS_PANIC_BYTES = 2 * 1024 * 1024 * 1024; // 2 GB — log + force GC
+
+/** Once past PANIC, back off exponentially instead of forcing a full GC on
+ *  every tick forever. `Bun.gc(true)` is synchronous — it runs on the same
+ *  single thread that serves the ACP socket and every HTTP route — so a
+ *  permanently-crossed threshold must not become a permanent stutter. */
+const PANIC_BACKOFF_MAX = 16;
 
 let registry: FinalizationRegistry<{ id: string; cleanupFn: () => void }> | null = null;
 
@@ -73,17 +95,31 @@ let heapTimer: ReturnType<typeof setInterval> | null = null;
 
 export function startHeapWatch(intervalMs = 60_000) {
   if (heapTimer) return;
+  let ticksUntilPanic = 0;
+  let panicBackoff = 1;
   heapTimer = setInterval(() => {
     const u = process.memoryUsage();
-    if (u.heapTotal > HEAP_PANIC_BYTES) {
+    const mb = (n: number) => (n / 1024 / 1024).toFixed(0);
+    if (u.rss > RSS_PANIC_BYTES) {
+      // ALWAYS log — the log line is the diagnostic that survives into a bug
+      // report, and it must not be suppressed by the GC backoff below.
       console.warn(
-        `[mem] heap ${(u.heapTotal / 1024 / 1024).toFixed(0)}MB > panic threshold — forcing GC`
+        `[mem] rss ${mb(u.rss)}MB > panic threshold (heapUsed ${mb(u.heapUsed)}MB) — memory is not being reclaimed`
       );
-      // Bun.gc(true) is sync; Node has no equivalent without --expose-gc.
-      const gc = (globalThis as { Bun?: { gc?: (sync: boolean) => void } }).Bun?.gc;
-      if (gc) gc(true);
-    } else if (u.heapTotal > HEAP_WARN_BYTES) {
-      console.warn(`[mem] heap ${(u.heapTotal / 1024 / 1024).toFixed(0)}MB > warn threshold`);
+      if (ticksUntilPanic > 0) {
+        ticksUntilPanic--;
+      } else {
+        const gc = (globalThis as { Bun?: { gc?: (sync: boolean) => void } }).Bun?.gc;
+        if (gc) gc(true);
+        ticksUntilPanic = panicBackoff;
+        panicBackoff = Math.min(panicBackoff * 2, PANIC_BACKOFF_MAX);
+      }
+    } else {
+      ticksUntilPanic = 0;
+      panicBackoff = 1;
+      if (u.rss > RSS_WARN_BYTES) {
+        console.warn(`[mem] rss ${mb(u.rss)}MB > warn threshold (heapUsed ${mb(u.heapUsed)}MB)`);
+      }
     }
   }, intervalMs);
   // Don't keep the event loop alive just for the heap watch.

package/apps/studio/readiness.ts

@@ -214,8 +214,22 @@ export async function probeReadiness(): Promise<ReadinessReport> {
   const authStatus =
     e2eForce === 'signed-out' ? { loggedIn: false } : claude ? await getClaudeAuthStatus() : null;
   const signedIn = !!authStatus?.loggedIn;
-  const offSubscription =
-    signedIn && authStatus?.apiProvider && authStatus.apiProvider !== 'firstParty';
+  // Issue #107 — a resolvable CLI whose auth status we could not READ is NOT
+  // the same as a signed-out one, and must not be reported as one. Claiming
+  // "not signed in" to a user who is signed in is a false accusation they
+  // can't argue with, and it routes them to a Sign-in button that can only
+  // dead-end (the poll re-runs the same failing probe until it times out).
+  // The probe's own tolerance for wrapper stdout noise now lives in probe.ts;
+  // this is the honest fallback for whatever noise that still can't read.
+  const authUnreadable = !!claude && e2eForce !== 'signed-out' && authStatus === null;
+  // Anything that is not an explicit `firstParty` counts as off-subscription,
+  // ABSENT included (attacker R2-3). The old `authStatus?.apiProvider &&`
+  // truthiness guard meant a metered user could suppress DDR-123's billing
+  // warning by OMITTING the field rather than forging `firstParty` — the exact
+  // outcome `narrowStatusTag`'s sentinel was written to prevent, reached through
+  // a different input shape. Over-warning is the safe direction here.
+  const offSubscription = signedIn && authStatus?.apiProvider !== 'firstParty';
+  const providerLabel = authStatus?.apiProvider ?? 'provider not reported';
   // DDR-166 Decision 5 — the settings-UI opt-out (prefs.rs `claude_auto_setup`,
   // DEFAULT ON) reaches the dev-server as an env var set fresh at each sidecar
   // spawn. Disabled → fall back to guide-only: no automated action offered,
@@ -226,21 +240,42 @@ export async function probeReadiness(): Promise<ReadinessReport> {
     id: 'claude',
     label: 'Claude Code (the `claude` CLI)',
     required: true,
-    status: claude && signedIn ? 'present' : 'missing',
+    status: claude && signedIn ? 'present' : authUnreadable ? 'unknown' : 'missing',
     detail: !claude
       ? 'Not found on PATH.'
       : signedIn
         ? offSubscription
-          ? `Signed in, but not on a Claude subscription (${authStatus?.apiProvider}) — AI editing may bill metered API usage.`
+          ? `Signed in, but not on a Claude subscription (${providerLabel}) — AI editing may bill metered API usage.`
           : `Signed in${authStatus?.subscriptionType ? ` · ${authStatus.subscriptionType}` : ''} — AI editing runs on your own Pro/Max subscription.`
-        : 'Installed, but not signed in.',
+        : authUnreadable
+          ? "Installed, but Maude couldn't read its sign-in state."
+          : 'Installed, but not signed in.',
     remediation: !claude
       ? 'Install Claude Code, then sign in. AI editing runs on your own Pro/Max subscription — never API billing.'
       : signedIn
         ? undefined
-        : 'Sign in to connect it to your Pro/Max subscription.',
+        : authUnreadable
+          ? // Deliberately does NOT interpolate the resolved path (attacker
+            // R2-2). This row carries a Copy affordance, and `copyFix` strips
+            // the backticks — so a path containing shell metacharacters would
+            // land on the clipboard inside a sentence the user is being told to
+            // paste. Worse, it would turn the possibly-hijacked binary that
+            // DDR-166 Decision 3 shows them precisely so they can DOUBT it into
+            // an instruction to run it. The path renders on its own line below.
+            'Maude ran `claude auth status --json` and could not read a status back. The usual cause is a version-manager shim or wrapper (mise, asdf, volta) fronting the real binary — check the path below, fix or quiet the wrapper, then Re-check.'
+          : 'Sign in to connect it to your Pro/Max subscription.',
     installCommand: !claude ? 'curl -fsSL https://claude.ai/install.sh | bash' : undefined,
-    action: !autoSetupEnabled ? undefined : !claude ? 'install' : !signedIn ? 'signin' : undefined,
+    // No Sign-in button when the status is unreadable: `pollForSignin` in
+    // ReadinessList.jsx polls THIS probe, so a button whose success signal we
+    // can't read can only ever end in "Sign-in timed out" (issue #107). The
+    // remediation text above is the actionable path in that state.
+    action: !autoSetupEnabled
+      ? undefined
+      : !claude
+        ? 'install'
+        : !signedIn && !authUnreadable
+          ? 'signin'
+          : undefined,
     resolvedPath: claude ?? undefined,
     resolvedViaMaude: !!claude && claude === process.env.MAUDE_CLAUDE_BIN,
   });

package/apps/studio/server.ts

@@ -78,16 +78,23 @@ let collab: ReturnType<typeof createCollab> | null = null;
 let inspectHandle: ReturnType<typeof createInspectRegistry> | null = null;
 
 const api = createApi(ctx, {
-  onCommentsChanged: async (file) => {
-    // After every comments mutation, re-broadcast the updated list.
-    const comments = await api.loadCommentsForFile(file);
-    ctx.bus.emit('comments', { file, comments });
+  onCommentsChanged: (file, comments) => {
     // Phase 8 Task 3 — bridge into the live Y.Array so collab peers see the
     // change without waiting for cold-open re-seeding. No-op when no room is
     // live for this canvas slug.
+    //
+    // Issue #111 — this runs BEFORE the mutation reaches disk (see
+    // `publishComments`), and `comments` is the post-mutation list handed over
+    // in memory. It used to be `await api.loadCommentsForFile(file)`: a disk
+    // round-trip sitting between the file write and this publish, wide enough
+    // for a `Room.flush()` to project the pre-mutation doc back over the file.
+    // Nothing here touches disk any more, and the doc is updated synchronously,
+    // so there is no window for a flush to be the stale writer.
     if (collab) {
       collab.registry.syncRoomFromComments(api.fileSlug(file), comments);
     }
+    // After every comments mutation, re-broadcast the updated list.
+    ctx.bus.emit('comments', { file, comments });
   },
   // Phase 8 Task 5 — same bridge for annotations. PUT /_api/annotations writes
   // the SVG blob to disk; we mirror it into the live Y.Map for collab peers.