@1agh/maude 0.56.0 → 0.57.0

package/apps/studio/http.ts

@@ -17,7 +17,14 @@ import {
   startSignin,
 } from './acp/login-state.ts';
 import { probeAcpAvailabilityAuthed } from './acp/probe.ts';
-import { deleteChat, listChats, readChatMessages, writeChatMeta } from './acp/transcript.ts';
+import { activitySnapshot, runningChats } from './acp/running.ts';
+import {
+  chatTranscriptSeq,
+  deleteChat,
+  listChats,
+  readChatMessages,
+  writeChatMeta,
+} from './acp/transcript.ts';
 import { type Api, ASSET_MAX_BYTES, ASSET_MAX_VIDEO_BYTES } from './api.ts';
 import { ImportAssetError, importSvg, SVG_MAX_BYTES } from './bin/_import-asset.mjs';
 import { ImportBrandError, importBrand } from './bin/_import-brand.mjs';
@@ -1319,6 +1326,40 @@ export function createHttp(
       return Response.json({ ok: true }, { headers: { 'Cache-Control': 'no-store' } });
     },
 
+    // Addendum Task 9 — "is a chat mid-turn right now?", asked by
+    // RepoBranchSwitcher.jsx before any of its three `window.location.reload()`
+    // call sites. A `git checkout` moves the worktree under a running agent
+    // (read on `draft-a`, written back after the checkout to `main` — a silent
+    // cross-branch clobber that `_history/`, being per-canvas-slug with no
+    // branch awareness, cannot undo), so this gates a confirm rather than
+    // reloading silently. MAIN-ORIGIN ONLY, read-only, no chat CONTENT — just
+    // how many are busy, so it says nothing the canvas origin could want.
+    '/_api/acp/running': (req: Request) => {
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const running = runningChats();
+      return Response.json(
+        { running: running.length, chats: running },
+        { headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
+    // feature-acp-turn-notifications Task 3 — the native shell's poller reads
+    // this to decide whether to fire an OS notification for a NON-visible
+    // project (Decision C). A sibling of `/_api/acp/running` above rather than
+    // an extension of it — that route stays exactly as-is because the reaper's
+    // `has_running_chat` (sidecar.rs) already depends on its `{running,chats}`
+    // shape and has no reason to grow one. MAIN-ORIGIN ONLY, same gate, and —
+    // load-bearing (Decision D) — NEVER a chat title, message text, or any
+    // transcript content: just chat ids (opaque, already exposed by `running`
+    // above) and a three-value state. Anyone adding a field here should ask
+    // what it would look like rendered on a lock screen.
+    '/_api/acp/activity': (req: Request) => {
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      return Response.json(activitySnapshot(), { headers: { 'Cache-Control': 'no-store' } });
+    },
+
     // Phase 31 — repo-level chat list + history (for the chat switcher +
     // hydration). MAIN-ORIGIN ONLY. Read-only; ids are sanitized before disk.
     '/_api/acp/chats': () =>
@@ -1365,8 +1406,16 @@ export function createHttp(
         return Response.json(meta, { headers: { 'Cache-Control': 'no-store' } });
       }
       if (!id) return Response.json([], { headers: { 'Cache-Control': 'no-store' } });
+      // Addendum Task 8 — the re-attach seam. Read the sequence marker BEFORE
+      // the messages: a line appended between the two reads then shows up in
+      // neither, and the client's `attach` will replay it. Reading it after
+      // would risk the opposite (a line counted but not returned), which the
+      // client would silently drop as "already hydrated" — a hole in the feed.
+      // Shipped as a header rather than a body field so the response SHAPE
+      // stays the plain message array every existing consumer expects.
+      const seq = chatTranscriptSeq(ctx.paths.designRoot, id);
       return Response.json(readChatMessages(ctx.paths.designRoot, id), {
-        headers: { 'Cache-Control': 'no-store' },
+        headers: { 'Cache-Control': 'no-store', 'X-Maude-Chat-Seq': String(seq) },
       });
     },
 

package/apps/studio/server.ts

@@ -735,6 +735,17 @@ async function shutdown() {
   // previously-unanswered "how does app-quit reach the grandchild" question.
   cancelSignin();
   cancelInstall();
+  // Addendum Task 8 — bridges now outlive their WebSocket, so socket-close is
+  // no longer the reaper it used to be. App quit / dev-server shutdown is the
+  // ONE lifetime boundary the detached model deliberately does NOT survive
+  // (DDR-166's SIGTERM-first path): extending a session across a project or
+  // branch *switch* is the point; extending it across a quit is not, and a
+  // surviving `claude` subprocess after quit would be an orphan.
+  try {
+    acp.stopAll();
+  } catch {
+    /* best-effort — the process is exiting either way */
+  }
   fsWatch.stop();
   try {
     gitWatch.stop();

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

@@ -47,6 +47,22 @@ export interface SyncStatusSnapshot {
   /** DDR-102 — slugs currently auth-rejected, capped at 20 (see docs.rejected
    *  for the true count). Treat as text, never HTML. */
   rejectedSlugs?: string[];
+  /**
+   * Canvases this run brought DOWN from the project — documents that existed
+   * only on the hub and are now real local files.
+   *
+   * This field was briefly `remoteGap`, "what the project has that this machine
+   * does not". That name stopped being true the moment the pull landed: the
+   * diff is computed before providers are built and recorded after, so it
+   * enumerated exactly the documents that had just arrived. Observed live —
+   * `_sync.json` naming two canvases that were sitting on disk.
+   *
+   * "What arrived this run" is both true and the more useful fact: it is what
+   * the Synced state tells the user to go and open. Absent when the hub could
+   * not be asked (old hub, offline) or when nothing was pulled. Names are
+   * hub-controlled — treat as text, never HTML, and see the cap in `notePulled`.
+   */
+  pulled?: { names: string[]; count: number };
 }
 
 type TimerHandle = ReturnType<typeof setTimeout>;
@@ -75,6 +91,8 @@ export interface ConnectionMonitor {
   /** DDR-102 — real sync activity for a slug (reconcile done, hub-pushed flush
    *  applied): bumps `lastSyncAt` to now. */
   noteSyncActivity(slug: string): void;
+  /** Record the canvases this run pulled down from the project (see `pulled`). */
+  notePulled(slugs: readonly string[]): void;
   /** Current snapshot (defensive copy). */
   snapshot(): SyncStatusSnapshot;
   /** Tear down timers. */
@@ -100,7 +118,14 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   // DDR-102 — per-doc states (pending/connected/auth-rejected).
   const docStates = new Map<string, DocSyncState>();
 
-  let state: SyncState = 'online';
+  // NOT born connected. The monitor used to start `online`, so from the instant
+  // a link was created — before a socket, before a token was accepted, before a
+  // byte moved — every surface reading `state` reported success. On a healthy
+  // fast connect that was harmless (the truth arrived milliseconds later); on a
+  // refused or unreachable one it was the whole bug: the user was shown the
+  // intention and read it as the result. `connecting` is the honest seed, and
+  // it is the state a link genuinely occupies until a provider says otherwise.
+  let state: SyncState = 'connecting';
   let queuedOps = 0;
   let lastSyncAt: number | null = null;
   let offlineSince: number | null = null;
@@ -111,6 +136,25 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   let flashTimer: TimerHandle | null = null;
   let stopped = false;
 
+  /** Canvases pulled down from the project this run. */
+  let pulled: SyncStatusSnapshot['pulled'];
+
+  /**
+   * Start the clock at construction, not at the first provider event.
+   *
+   * `enterGrace` is reachable ONLY from `noteProviderStatus`, so a link where
+   * no provider ever reports — every provider rejected during boot, a hub that
+   * never completes an upgrade — would have sat in `connecting` forever and
+   * never reached the offline banner. Seeding `state` honestly is not enough on
+   * its own; something has to be counting from the moment the link exists.
+   */
+  function armInitialGrace(): void {
+    graceTimer = setTimer(() => {
+      graceTimer = null;
+      goOffline();
+    }, graceMs);
+  }
+
   function snapshot(): SyncStatusSnapshot {
     const docs = { synced: 0, pending: 0, rejected: 0 };
     const rejectedSlugs: string[] = [];
@@ -130,9 +174,31 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       updatedAt: now(),
       docs,
       rejectedSlugs,
+      ...(pulled ? { pulled } : {}),
     };
   }
 
+  /**
+   * Record the canvases this run pulled down from the project.
+   *
+   * `names` is capped like `rejectedSlugs` — this reaches a UI and a JSON file,
+   * and an unbounded list of hub-chosen names is a hub-controlled payload size.
+   * `count` keeps the true total, so the cap never falsifies the number the
+   * user is shown. An empty list clears the field rather than recording a zero:
+   * a run that pulled nothing has nothing to say.
+   */
+  function notePulled(slugs: readonly string[]): void {
+    // Every other mutator carries this guard; without it a late call could
+    // write `_sync.json` and broadcast for a monitor that has been torn down.
+    // Unreachable today (the sole caller checks `stopped` too) — kept so the
+    // invariant does not depend on the caller remembering it.
+    if (stopped) return;
+    pulled = slugs.length
+      ? { names: slugs.slice(0, MAX_REJECTED_SLUGS), count: slugs.length }
+      : undefined;
+    emit();
+  }
+
   function emit(): void {
     onChange?.(snapshot());
   }
@@ -181,15 +247,20 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   }
 
   function enterGrace(): void {
-    // Already counting down or already offline — don't restart the clock.
-    if (state !== 'online') return;
+    // Already offline — stay there until a provider reports 'connected'.
+    if (state === 'offline' || state === 'offline-long') return;
+    // Already counting down — don't restart the clock. The guard used to be
+    // `state !== 'online'`; the timer, not the state, is what says whether a
+    // countdown is running, and with the `connecting` seed those are no longer
+    // the same question.
+    if (graceTimer !== null) return;
     state = 'connecting';
-    if (graceTimer !== null) clearTimer(graceTimer);
     graceTimer = setTimer(() => {
       graceTimer = null;
       goOffline();
     }, graceMs);
-    emit();
+    // No emit here — the sole caller emits once for the whole update, so a
+    // demotion that does not change `state` still reaches the readers.
   }
 
   function goOffline(): void {
@@ -204,19 +275,56 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
     emit();
   }
 
+  armInitialGrace();
+
   return {
     noteProviderStatus(providerId, status) {
       if (stopped) return;
+
+      // EMIT ONLY ON A REAL CHANGE.
+      //
+      // Every emit is a synchronous `_sync.json` write plus a WS broadcast to
+      // every open tab. Provider status is driven by the socket lifecycle,
+      // which the hub controls, and there is one provider per canvas — 75+ in
+      // the reported project. An unconditional emit here turns a flapping (or
+      // deliberately hostile) hub into a sustained disk-write and fan-out loop
+      // on the dev-server's main thread. The pre-existing code emitted only on
+      // a transition; adding the demotion below must not cost that property.
+      const prevStatus = providerStatuses.get(providerId);
       providerStatuses.set(providerId, status);
+      let changed = prevStatus !== status;
+
+      // A document whose socket is gone is not a synced document.
+      //
+      // `docs.synced` used to only ever RISE — nothing demoted a `connected`
+      // doc, so a hub that died left the last count frozen on screen, which is
+      // the most convincing form of the lie: it was true a moment ago. The
+      // provider id IS the slug (`index.ts` passes `canvas.slug`), so the
+      // monitor already knows which document just lost its socket.
+      //
+      // `auth-rejected` is deliberately NOT demoted. The hub gave an answer;
+      // losing the socket afterwards does not turn that answer back into
+      // "still trying", and letting it would hide a rotated credential behind
+      // a spinner.
+      if (status !== 'connected' && docStates.get(providerId) === 'connected') {
+        docStates.set(providerId, 'pending');
+        changed = true;
+      }
+
       const agg = aggregate();
       if (agg === 'connected') {
+        // goOnline() emits for the transition; otherwise only a real change
+        // (this provider's status moved, or a document was demoted) is news.
         if (state !== 'online') goOnline();
+        else if (changed) emit();
         return;
       }
       // Aggregate is connecting or disconnected → start (or continue) the
       // grace countdown. Once offline/offline-long we stay there until a
       // provider reports 'connected' again.
-      if (state === 'online') enterGrace();
+      const before = state;
+      enterGrace();
+      if (changed || state !== before) emit();
     },
 
     noteLocalEdit() {
@@ -245,6 +353,8 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       emit();
     },
 
+    notePulled,
+
     snapshot,
 
     stop() {

package/apps/studio/sync/index.ts

@@ -45,6 +45,7 @@ import { loadJournal, type SyncJournal } from './journal.ts';
 import { isLoopbackHost } from './loopback.ts';
 import { migrateSeed } from './migrate-seed.ts';
 import { createDocProjection, type DocProjection } from './projection.ts';
+import { describeRemoteDiff, diffRemoteDocs, fetchRemoteDocs, pullTargets } from './remote-docs.ts';
 import { createSyncStatusStore, type SyncStatusStore } from './status.ts';
 import { writeUntrustedMarkers } from './untrusted.ts';
 
@@ -424,7 +425,46 @@ export function createSyncRuntime(
     const scan = opts.canvases ? { canvases: opts.canvases, tsxCount: 0 } : await scanCanvases(ctx);
     // DDR-064 pre-cutover A4 + A6 — two files must never share a document, and
     // the pinned set must be bounded. See `admitCanvases`.
-    const canvases = admitCanvases(scan.canvases, useSharedDoc);
+    const localCanvases = admitCanvases(scan.canvases, useSharedDoc);
+
+    // PULL THE REST OF THE PROJECT DOWN.
+    //
+    // The scan above only sees this machine's disk, and Yjs cannot enumerate —
+    // so before this, a document that existed only on the hub was invisible to
+    // a peer forever. A desktop carrying 72 of a project's 75 canvases synced
+    // 72, reported "72/72 synced", and was accurate about the wrong universe.
+    // That is what "Open in Maude does nothing" was.
+    //
+    // A project you have access to is a project you get, in full and in both
+    // directions. Hub-only documents become real local files (flat under the
+    // design root — see `pullTargets` for why flat); local-only canvases go up
+    // as they always did. Best-effort: an older hub without the listing route,
+    // or an unreachable one, syncs exactly as before.
+    const remoteDocs = await fetchRemoteDocs(linkedHub.url, resolvedToken);
+    const remoteDiff = diffRemoteDocs(
+      localCanvases.map((c) => docNameFor(c.slug)),
+      remoteDocs
+    );
+    const pulled = pullTargets(
+      remoteDiff.hubOnly,
+      ctx.paths.designRoot,
+      path.join,
+      path.resolve,
+      path.sep
+    );
+    const pullNote = describeRemoteDiff(remoteDiff);
+    if (pullNote) console.log(`[sync] ${pullNote}`);
+    const canvases = [
+      ...localCanvases,
+      ...pulled.map((t) => ({
+        slug: t.slug,
+        html: t.bodyAbs,
+        comments: path.join(ctx.paths.commentsDir, `${t.slug}.json`),
+        annotations: path.join(ctx.paths.designRoot, `${t.slug}.annotations.svg`),
+        meta: t.bodyAbs.replace(/\.tsx$/i, '.meta.json'),
+        css: t.bodyAbs.replace(/\.tsx$/i, '.css'),
+      })),
+    ];
     // T4.5 (DDR-054 §3 F3) — every syncable canvas can receive hub-pushed
     // content, so the whole set is untrusted Claude-context. Mark it (writes
     // `_untrusted/INDEX.json` + a managed `.claudeignore` block; clears both
@@ -981,6 +1021,15 @@ export function createSyncRuntime(
       console.log(
         `[sync] ${linkedHub.url}: ${parts.join(' · ')} · shared-doc:${useSharedDoc ? 'on' : 'off'}`
       );
+      // What this run brought DOWN, recorded for `_sync.json` and the UI.
+      //
+      // This used to record `remoteDiff` under the name `remoteGap` — "what the
+      // project has that this machine does not". By the time it ran, that was
+      // false: the diff is taken BEFORE providers are built and recorded after
+      // the pull, so it named exactly the canvases that had just arrived and
+      // were sitting on disk. `pulled` is the same list under the name that is
+      // true, and it is the fact the user is told to act on.
+      mon.notePulled(pulled.map((t) => t.slug));
     });
   }
 

package/apps/studio/sync/presentation.ts

@@ -0,0 +1,273 @@
+// One rule for "what is the hub link doing", shared by every surface.
+//
+// There were two answers to that question and they disagreed. The status bar
+// keyed off `state` alone — it referenced `docs` zero times, so a link whose
+// every document the hub had refused still showed a green dot and the word
+// "synced". The connect note in the cloud rail keyed off the ATTACH RESPONSE,
+// a value that means "the runtime started", and never updated again. A user
+// who distrusted one was sent to the other, which was wrong in a different way.
+//
+// So the rule lives here, once, as a pure function over the payload both
+// surfaces already receive. Agreement between them is then structural rather
+// than a thing two files have to remember.
+//
+// DDR-054 — document names and project names originate at the hub. Counts come
+// first in every sentence so a hostile name cannot dominate it, names are
+// capped, and nothing here produces markup.
+
+import type { SyncStatusSnapshot } from './connection-state.ts';
+
+/** Where a link is, in the terms a person cares about. */
+export type SyncPhase =
+  | 'connecting'
+  | 'syncing'
+  | 'synced'
+  | 'refused'
+  | 'offline'
+  | 'nothing-syncable';
+
+export interface SyncPresentation {
+  phase: SyncPhase;
+  /** Green dot — reserved for a link that is genuinely carrying edits. */
+  online: boolean;
+  /** Status-bar slot text. Terse; never contains a hub-supplied name. */
+  label: string;
+  /** Full sentence — the rail note and the status-bar hover. */
+  title: string;
+  /**
+   * What the person should do now, or null when the honest answer is "nothing,
+   * it is working". Every non-null phase names one — being told a state without
+   * being told the move is the complaint this whole change exists for.
+   */
+  next: string | null;
+  /** Up to 3 hub-supplied names relevant to the phase (refused / pulled). */
+  names: string[];
+}
+
+/**
+ * The `/_sync-status` payload, in its three historical shapes:
+ *   - `{ linked: false }`                      — solo project, no link
+ *   - `{ notSyncable, tsxCount, reason }`      — DDR-060, linked but 0 syncable
+ *   - the connection-state snapshot + url/canvases (the common case)
+ *
+ * Every field is optional on purpose: pre-DDR-102 payloads have no `docs`, and
+ * the browser and the CLI read the same JSON.
+ */
+export interface SyncStatusLike extends Partial<SyncStatusSnapshot> {
+  linked?: boolean;
+  notSyncable?: boolean;
+  tsxCount?: number;
+  reason?: string;
+  canvases?: number;
+}
+
+/** Hub-supplied text that reaches a UI. Bounded, never markup. */
+const MAX_NAME_LEN = 60;
+const SHOWN_NAMES = 3;
+
+export function safeName(raw: unknown, fallback: string): string {
+  // Length alone was not enough. A name is hub-supplied (cell mode sets it from
+  // `MAUDE_PROJECT_NAME`; `.design/config.json` is a committed file anyone with
+  // repo access can author), and it lands in trusted app chrome — including a
+  // `title=` tooltip, where a newline RENDERS and can push the true clause out
+  // of view. `All 75 canvases synced.\n\n\n` fits inside 60 characters and
+  // reads as a reassuring sentence of ours.
+  //
+  // So: strip control and format characters (which covers the bidi overrides
+  // U+202A–U+202E / U+2066–U+2069 — a name that reverses the rest of the line
+  // is the same attack by a different mechanism), then collapse whitespace to
+  // single spaces so no name can ever contain a line break.
+  const s = String(raw ?? '')
+    .replace(/[\p{Cc}\p{Cf}]/gu, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!s) return fallback;
+  return s.length > MAX_NAME_LEN ? `${s.slice(0, MAX_NAME_LEN)}…` : s;
+}
+
+function shownNames(list: readonly string[] | undefined): string[] {
+  return (list ?? []).slice(0, SHOWN_NAMES).map((n) => safeName(n, '(unnamed)'));
+}
+
+/**
+ * The per-document counts, or null if they cannot be trusted.
+ *
+ * FAIL CLOSED. `/_sync-status` returns `JSON.parse` of `_sync.json` with no
+ * schema, so this function's input is whatever is on disk — a partial write, an
+ * older producer, a newer one. `synced` was the FALL-THROUGH branch, which made
+ * the reassuring answer the only reachable one for any shape not recognised:
+ * `docs: {}` gave `total === NaN`, failed both `> 0` and `=== 0`, and rendered
+ * "Synced — all NaN canvases", green. For a module whose entire premise is that
+ * it does not overstate, the unreadable case must land in `connecting`, never
+ * in `synced`.
+ */
+function readCounts(
+  docs: SyncStatusLike['docs']
+): { synced: number; pending: number; rejected: number } | null {
+  if (!docs) return null;
+  const ok = (n: unknown): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 0;
+  if (!ok(docs.synced) || !ok(docs.pending) || !ok(docs.rejected)) return null;
+  return { synced: docs.synced, pending: docs.pending, rejected: docs.rejected };
+}
+
+/**
+ * Read a sync payload the way a person would.
+ *
+ * Returns null when there is nothing to say — an unlinked project has no hub
+ * status, and inventing one would put a slot on screen that can only ever be
+ * empty.
+ */
+export function syncPresentation(
+  status: SyncStatusLike | null | undefined,
+  opts: { project?: string | null } = {}
+): SyncPresentation | null {
+  if (!status || status.linked === false) return null;
+  const project = safeName(opts.project, 'the workspace');
+
+  if (status.notSyncable) {
+    const tsx = status.tsxCount ?? 0;
+    return {
+      phase: 'nothing-syncable',
+      online: false,
+      label: `0 syncable${tsx > 0 ? ` · ${tsx} tsx` : ''}`,
+      title: status.reason
+        ? safeName(status.reason, 'No canvases in this project are syncable yet.')
+        : `Connected to ${project} — no canvases here are syncable yet.`,
+      next: 'Create a canvas — it will start syncing on its own.',
+      names: [],
+    };
+  }
+
+  const queued = status.queuedOps ?? 0;
+  const queueNote = queued > 0 ? ` ${queued} local edit${queued === 1 ? '' : 's'} are queued.` : '';
+  const unreachable = status.state === 'offline' || status.state === 'offline-long';
+  // Validated, not taken on trust — see `readCounts`. `null` means "unreadable",
+  // which is deliberately NOT the same as "absent" (an old payload, handled
+  // below) and must never reach the synced branch.
+  const docs = readCounts(status.docs);
+  const unreadable = status.docs !== undefined && docs === null;
+
+  // A REFUSAL OUTRANKS EVERYTHING, including an unreachable hub.
+  //
+  // The offline branch used to sit above this one, and that was the bug from
+  // one branch up: a hub can refuse auth on the documents it wants silenced and
+  // then drop the sockets, and the user would be told "your edits are safe and
+  // queued — nothing to do". For an auth-rejected document that is false and
+  // never self-heals. Rejections are deliberately sticky (a dropped socket does
+  // not launder them), so if one is on record it is still true while offline —
+  // and it is the only part of the picture that needs a person.
+  if (docs && docs.rejected > 0) {
+    const total = docs.synced + docs.pending + docs.rejected;
+    return {
+      phase: 'refused',
+      online: false,
+      label: `${docs.rejected} refused`,
+      title:
+        `${docs.rejected} of ${total} canvas${total === 1 ? '' : 'es'} were refused by ${project} — their edits are not syncing.` +
+        (unreachable ? ' The hub is also unreachable right now.' : ''),
+      next: 'Reconnect the workspace — the credential may have been rotated.',
+      names: shownNames(status.rejectedSlugs),
+    };
+  }
+
+  // Otherwise an unreachable hub outranks every count. Whatever the documents
+  // last said, nothing is moving — and "72 synced" over a dead socket is the
+  // exact shape of lie this module exists to stop.
+  //
+  // Count first, name second: `project` is hub-supplied, and a leading name is
+  // a name that gets to set the tone of our own sentence.
+  if (unreachable) {
+    return {
+      phase: 'offline',
+      online: false,
+      label: queued > 0 ? `offline · ${queued} ↑` : 'offline',
+      title: `Not reachable: ${project}. Your edits are safe on this machine and queued.${queueNote}`,
+      next: 'Nothing to do — syncing resumes by itself when the hub is back.',
+      names: [],
+    };
+  }
+
+  if (unreadable) {
+    // A payload we cannot read is not a payload that says everything is fine.
+    return {
+      phase: 'connecting',
+      online: false,
+      label: 'status unreadable',
+      title: `Cannot read the sync status for ${project} — the counts on disk are malformed.`,
+      next: 'Reconnect the workspace; if it persists, restart Maude.',
+      names: [],
+    };
+  }
+
+  if (!docs) {
+    // Pre-DDR-102 payload: `state` is all there is. Report it as the weaker
+    // evidence it is, rather than promoting it to a document-level claim.
+    const online = status.state === 'online' || status.flash === 'synced';
+    return {
+      phase: online ? 'synced' : 'connecting',
+      online,
+      label: online ? (queued > 0 ? `${queued} ↑` : 'synced') : 'connecting…',
+      title: online ? `Syncing with ${project}.${queueNote}` : `Connecting to ${project}…`,
+      next: online ? null : 'Nothing to do — this usually takes a moment.',
+      names: [],
+    };
+  }
+
+  // Refusals were already handled above — they outrank an unreachable hub, so
+  // that branch has to come first. Everything from here on has `rejected === 0`.
+  const total = docs.synced + docs.pending + docs.rejected;
+
+  if (total === 0) {
+    return {
+      phase: 'connecting',
+      online: false,
+      label: 'connecting…',
+      title: `Connecting to ${project}…`,
+      next: 'Nothing to do — this usually takes a moment.',
+      names: [],
+    };
+  }
+
+  if (docs.pending > 0) {
+    // Zero settled yet is a different fact from some settled: one is a
+    // handshake in flight, the other is visible progress.
+    const started = docs.synced > 0;
+    return {
+      phase: started ? 'syncing' : 'connecting',
+      online: false,
+      label: started ? `${docs.synced}/${total}` : 'connecting…',
+      title: started
+        ? `Syncing with ${project} — ${docs.synced} of ${total} canvas${total === 1 ? '' : 'es'} so far.`
+        : `Connecting to ${project}…`,
+      next: 'Nothing to do — this usually takes a moment.',
+      names: [],
+    };
+  }
+
+  // Clamped and validated for the same reason as the doc counts: `count` is
+  // read off disk, and "1000000000 came down from the project" is not a
+  // sentence this module should be capable of producing. The ceiling is `total`
+  // — a pulled document becomes one of the canvases being counted, so more
+  // pulled than exist is not a big number, it is a broken payload.
+  const rawPulled = status.pulled?.count;
+  const pulledCount =
+    typeof rawPulled === 'number' && Number.isInteger(rawPulled) && rawPulled >= 0
+      ? Math.min(rawPulled, total)
+      : 0;
+  return {
+    phase: 'synced',
+    online: true,
+    label: queued > 0 ? `${queued} ↑` : 'synced',
+    title:
+      `Synced with ${project} — all ${total} canvas${total === 1 ? '' : 'es'}.` +
+      (pulledCount > 0 ? ` ${pulledCount} came down from the project on this connect.` : '') +
+      queueNote,
+    // Deliberately NOT "open one of the canvases that just arrived". A pulled
+    // canvas is hub-authored TSX (DDR-054, and the DDR-079 residual it carries),
+    // and an imperative in our own green success sentence is the strongest
+    // possible endorsement of content we do not vouch for. State the fact; the
+    // decision to open stays the person's.
+    next: pulledCount > 0 ? 'They are new to this machine — look them over before editing.' : null,
+    names: pulledCount > 0 ? shownNames(status.pulled?.names) : [],
+  };
+}