@1agh/maude 1.2.0 → 1.3.0

package/apps/studio/sync/migrate-seed.ts

@@ -35,6 +35,7 @@ import path from 'node:path';
 import type * as Y from 'yjs';
 
 import { Y_TYPES } from '../collab/persistence.ts';
+import { atomicWrite } from './atomic-write.ts';
 import {
   annotationsEditAtFromDoc,
   applyAnnotationsToDoc,
@@ -53,12 +54,18 @@ import {
   decideAnnotationsColdStart,
   decideColdStart,
   decideCssColdStart,
+  isExactRepeat,
   unionCommentsById,
 } from './cold-start.ts';
 import { applyColdStart, type ColdStartSnapshotReason } from './cold-start-apply.ts';
 import { hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
+import { collapseRepeatedModule, collapseRepeatedText } from './repeated-module.ts';
+import { rememberSeed } from './seed-repair.ts';
+import { mergeSource } from './source-merge.ts';
+import { lastValidSource, readRecoveryBody, saveRecoveryBody } from './source-recovery.ts';
+import { sourceError } from './source-validation.ts';
 
 export interface MigrateSeedPaths {
   html: string;
@@ -97,6 +104,13 @@ export interface MigrateSeedOptions {
    * does not have it", which is the pre-existing behaviour.
    */
   hubHasState?: (slug: string) => boolean;
+  /**
+   * A local candidate diverged from the hub body and could not be merged from
+   * their shared base. Neither side is overwritten: the caller hands `base` to
+   * the projection (`adoptBase`) so its write stays blocked with a visible
+   * conflict until a later save resolves it (audit 2026-09-13 P0 #1 / T2).
+   */
+  onHold?: (base: string) => void;
   /** DDR-102 — divergence notification, same contract as the agent's. */
   onConflict?: (info: {
     slug: string;
@@ -123,6 +137,10 @@ export type MigrateSeedResult =
   /** DDR-102 — divergence resolved newest-wins. */
   | 'conflict-local-wins'
   | 'conflict-hub-wins'
+  /** T2 — divergence resolved by a clean three-way merge from the saved base. */
+  | 'conflict-merged'
+  /** T2 — divergence that no merge could prove independent; both kept, held. */
+  | 'conflict-held'
   /** The replica is empty but the HUB is not — its state is still in flight.
    *  Seeding here is the F1 collision (see `hubHasState`), so this seed does
    *  nothing and lets the document arrive. */
@@ -146,11 +164,17 @@ export function docIsEmpty(doc: Y.Doc): boolean {
 export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeedResult> {
   const { slug, doc, paths } = opts;
 
-  const localHtml = readLocal(paths.html);
+  // A file already holding its module k× over (an earlier seed race) enters
+  // as ONE copy — adopting it as-is would plant the repeat in the project.
+  const readHtml = readLocal(paths.html);
+  const diskHtml = readHtml === null ? null : (collapseRepeatedModule(readHtml)?.unit ?? readHtml);
+  const localHtml =
+    diskHtml !== null && sourceError(paths.html, diskHtml) === null ? diskHtml : null;
   const localComments = readLocal(paths.comments);
   const localAnnotations = readLocal(paths.annotations);
   const localMeta = paths.meta ? readLocal(paths.meta) : null;
-  const localCss = paths.css ? readLocal(paths.css) : null;
+  const readCss = paths.css ? readLocal(paths.css) : null;
+  const localCss = readCss === null ? null : (collapseRepeatedText(readCss)?.unit ?? readCss);
 
   // Hub was empty → adopt local. Build the doc from the local files ONCE, inside
   // a single MIGRATION transaction. The apply* codecs delete-then-insert, so
@@ -182,6 +206,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
 
     doc.transact(() => {
       if (localHtml) {
+        rememberSeed(doc, localHtml, localCss, ORIGINS.MIGRATION);
         if (applyHtmlToDoc(doc, localHtml, ORIGINS.MIGRATION)) {
           stampBodyEdit(doc, ORIGINS.MIGRATION);
         }
@@ -219,6 +244,16 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // boot — not spam) so non-body files keep their pre-cutover backup too.
   snapshotLocal(opts);
 
+  // Invalid hub source must reach the projector's quarantine unchanged. Never
+  // checkpoint it, elect it by timestamp, or merge a healthy local file into it
+  // merely because the connection restarted. A deliberate file edit can repair it.
+  if (
+    sourceError(paths.html, doc.getText(Y_SYNC_TYPES.html).toString()) !== null &&
+    !(localHtml && isExactRepeat(doc.getText(Y_SYNC_TYPES.html).toString(), localHtml))
+  ) {
+    return 'hub-wins';
+  }
+
   // Body resolution via the DDR-102 decision table.
   const docHtml = doc.getText(Y_SYNC_TYPES.html).toString();
   const decision = decideColdStart({
@@ -235,6 +270,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
    *  below (decideAnnotationsColdStart), independent of the body winner. */
   const rebuildBodyFromLocal = (): void => {
     doc.transact(() => {
+      if (docHtml === '' && localHtml) rememberSeed(doc, localHtml, localCss, ORIGINS.MIGRATION);
       if (applyHtmlToDoc(doc, localHtml as string, ORIGINS.MIGRATION)) {
         stampBodyEdit(doc, ORIGINS.MIGRATION);
       }
@@ -253,22 +289,61 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // fail-closed refusal, the conflict report, and crucially the
   // `recover-seed-dup` row this switch used to be missing — now lives in
   // exactly one place.
-  const applied = await applyColdStart({
-    slug,
-    decision,
-    localBody: localHtml,
-    docBody: docHtml,
-    takeHub: () => {
-      /* the projection materializes the doc; nothing to do here */
-    },
-    takeLocal: rebuildBodyFromLocal,
-    checkpointIdentity: (body) => opts.journal?.record(slug, { bodyHash: hashBytes(body) }),
-    logLabel: 'shared-doc',
-    ...(opts.snapshot ? { snapshot: opts.snapshot } : {}),
-    ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
-  });
-
-  const result: MigrateSeedResult = resultFor(applied.action, applied.bodyWinner);
+  // A DIVERGENCE WITH A KNOWN BASE IS NOT A COIN TOSS. Newest-wins keeps one
+  // side and snapshots the other — recoverable, but the peer's edit is gone
+  // from the canvas. When the projection saved the body both sides last agreed
+  // on (and the journal proves it is that body), merge from it exactly as a
+  // live save does; if the edits touch, hold both and let the projection keep
+  // the conflict visible. No base (older state) keeps DDR-102's table.
+  const journalHash = opts.journal?.get(slug)?.bodyHash ?? null;
+  const savedBase =
+    decision.action === 'conflict' && opts.historyDir && journalHash !== null
+      ? readRecoveryBody(opts.historyDir, paths.html, 'base')
+      : null;
+  const base = savedBase !== null && hashBytes(savedBase) === journalHash ? savedBase : null;
+  let applied: { action: ColdStartAction; bodyWinner: 'local' | 'hub' };
+  let result: MigrateSeedResult;
+  if (base !== null && localHtml !== null) {
+    const merged = mergeSource(base, localHtml, docHtml);
+    if (opts.snapshot) {
+      try {
+        await opts.snapshot(localHtml, 'pre-sync-local');
+        await opts.snapshot(docHtml, 'pre-sync-hub');
+      } catch {
+        /* best-effort — neither branch below overwrites a side it did not merge */
+      }
+    }
+    if (merged.ok && sourceError(paths.html, merged.merged) === null) {
+      doc.transact(() => {
+        if (applyHtmlToDoc(doc, merged.merged, ORIGINS.MIGRATION)) {
+          stampBodyEdit(doc, ORIGINS.MIGRATION);
+        }
+      }, ORIGINS.MIGRATION);
+      // The projection writes the merged body and checkpoints it.
+      result = 'conflict-merged';
+    } else {
+      opts.onHold?.(base);
+      result = 'conflict-held';
+    }
+    // The coupled lanes resolve per-lane against the hub, as on a hub-wins boot.
+    applied = { action: 'conflict', bodyWinner: 'hub' };
+  } else {
+    applied = await applyColdStart({
+      slug,
+      decision,
+      localBody: localHtml,
+      docBody: docHtml,
+      takeHub: () => {
+        /* the projection materializes the doc; nothing to do here */
+      },
+      takeLocal: rebuildBodyFromLocal,
+      checkpointIdentity: (body) => opts.journal?.record(slug, { bodyHash: hashBytes(body) }),
+      logLabel: 'shared-doc',
+      ...(opts.snapshot ? { snapshot: opts.snapshot } : {}),
+      ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
+    });
+    result = resultFor(applied.action, applied.bodyWinner);
+  }
 
   // ---- annotations: PER-LANE newest-wins (the 2026-08-14 eraser fix; the
   // same table as agent.ts reconcile). Under sharedDoc the collab room's
@@ -394,7 +469,23 @@ function snapshotLocal(opts: MigrateSeedOptions): void {
       opts.paths.css,
     ]) {
       if (p && existsSync(p)) {
-        copyFileSync(p, path.join(dir, path.basename(p)));
+        const target = path.join(dir, path.basename(p));
+        if (p === opts.paths.html) {
+          const current = readLocal(p);
+          // A body holding the same module twice over parses, but it is the
+          // corruption this snapshot exists to survive — never its "valid"
+          // copy, and never a reason to replace a healthy earlier snapshot.
+          const healthy = (body: string | null): body is string =>
+            !!body?.trim() &&
+            sourceError(p, body) === null &&
+            collapseRepeatedModule(body) === null;
+          const valid = healthy(current) ? current : lastValidSource(opts.historyDir, p);
+          if (valid && healthy(valid)) {
+            saveRecoveryBody(opts.historyDir, p, 'last-valid', valid);
+            const prior = readLocal(target);
+            if (!healthy(prior)) atomicWrite(target, valid);
+          }
+        } else copyFileSync(p, target);
       }
     }
   } catch {

package/apps/studio/sync/poke.ts

@@ -22,6 +22,8 @@ const MAX_POKE_BYTES = 512;
 export interface Poke {
   /** The hub's journal head at emit time. A hint, never an authority. */
   head: number;
+  /** Only document membership changed; do not scan or transfer the file plane. */
+  documents?: true;
 }
 
 /**
@@ -42,9 +44,9 @@ export function parsePoke(payload: unknown): Poke | null {
     return null;
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
-  const frame = parsed as { t?: unknown; head?: unknown };
+  const frame = parsed as { t?: unknown; head?: unknown; documents?: unknown };
   if (frame.t !== 'files') return null;
   const head = frame.head;
   if (typeof head !== 'number' || !Number.isInteger(head) || head < 0) return null;
-  return { head };
+  return frame.documents === true ? { head, documents: true } : { head };
 }

package/apps/studio/sync/presentation.ts

@@ -25,7 +25,9 @@ export type SyncPhase =
   | 'stalled'
   | 'refused'
   | 'offline'
-  | 'nothing-syncable';
+  | 'nothing-syncable'
+  /** The link works, but part of the project did not get through. */
+  | 'attention';
 
 /**
  * How long `connecting…` may honestly stay on screen with ZERO documents
@@ -71,6 +73,18 @@ export interface SyncStatusLike extends Partial<SyncStatusSnapshot> {
   tsxCount?: number;
   reason?: string;
   canvases?: number;
+  /**
+   * The other lanes `_sync.json` carries (`status.ts`): source-sync conflicts,
+   * the file plane, the asset push. Typed `unknown` on purpose — they are read
+   * off disk with no schema and validated below, never trusted.
+   */
+  conflicts?: unknown;
+  files?: unknown;
+  assets?: unknown;
+  /** Accepted-revisions save counters (plan T29) — validated below. */
+  accepted?: unknown;
+  /** An AI action open or held (plan T16) — validated below. */
+  aiAction?: unknown;
 }
 
 /** Hub-supplied text that reaches a UI. Bounded, never markup. */
@@ -143,6 +157,118 @@ function readCounts(
   return { synced: docs.synced, pending: docs.pending, rejected: docs.rejected };
 }
 
+const isCount = (n: unknown): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 0;
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** What the non-document lanes say, validated. */
+interface LaneFacts {
+  /** A payload field we cannot read. Fail closed: never "synced". */
+  unreadable: boolean;
+  /** Canvases whose source change was refused and is waiting (#121 / T2). */
+  sourceSlugs: string[];
+  failedFiles: number;
+  tooLarge: number;
+  blockedOther: number;
+  /** Changes a breaker is holding for a person's decision. */
+  held: number;
+  failedMedia: number;
+  /** Files or media still moving on their own. */
+  moving:
+    | { delivered: number; tracked: number }
+    | { media: { done: number; total: number } }
+    | null;
+  paused: boolean;
+}
+
+/**
+ * Audit 2026-09-13 P0 #3 — "synced" is a claim about the whole project, not
+ * about the document sockets. The payload already carried refused source
+ * changes, failed files, a blocked seed and failed uploads; the summary read
+ * none of them and said "Synced … all 91 canvases" over all four.
+ */
+function readLanes(status: SyncStatusLike): LaneFacts {
+  const facts: LaneFacts = {
+    unreadable: false,
+    sourceSlugs: [],
+    failedFiles: 0,
+    tooLarge: 0,
+    blockedOther: 0,
+    held: 0,
+    failedMedia: 0,
+    moving: null,
+    paused: false,
+  };
+  const { conflicts, files, assets } = status;
+  if (conflicts !== undefined) {
+    if (!Array.isArray(conflicts)) facts.unreadable = true;
+    else {
+      for (const c of conflicts) {
+        // `body-rejected` is the only kind that stays until it is resolved
+        // (`clearSourceConflict`); cold-start notes record a decision made.
+        if (isRecord(c) && c.kind === 'body-rejected') {
+          facts.sourceSlugs.push(typeof c.slug === 'string' ? c.slug : '(unnamed)');
+        }
+      }
+    }
+  }
+  if (files !== undefined) {
+    if (!isRecord(files)) facts.unreadable = true;
+    else {
+      for (const key of ['synced', 'pulled', 'conflicts', 'pushed', 'failed'] as const) {
+        if (files[key] !== undefined && !isCount(files[key])) facts.unreadable = true;
+      }
+      if (isCount(files.failed)) facts.failedFiles = files.failed;
+      if (Array.isArray(files.held)) {
+        for (const h of files.held) facts.held += isRecord(h) && isCount(h.count) ? h.count : 1;
+      }
+      if (isRecord(files.rateLimited)) facts.paused = true;
+      const progress = files.progress;
+      if (isRecord(progress)) {
+        if (Array.isArray(progress.blocked)) {
+          for (const b of progress.blocked) {
+            if (!isRecord(b) || !isCount(b.count)) continue;
+            if (b.class === 'too-large') facts.tooLarge += b.count;
+            else facts.blockedOther += b.count;
+          }
+        }
+        if (progress.phase === 'paused') facts.paused = true;
+        if (
+          progress.phase === 'scanning' ||
+          progress.phase === 'seeding' ||
+          progress.phase === 'paused'
+        ) {
+          facts.moving =
+            isCount(progress.delivered) && isCount(progress.tracked)
+              ? {
+                  delivered: Math.min(progress.delivered, progress.tracked),
+                  tracked: progress.tracked,
+                }
+              : { delivered: 0, tracked: 0 };
+        }
+      } else if (progress !== undefined) facts.unreadable = true;
+    }
+  }
+  if (assets !== undefined) {
+    if (!isRecord(assets)) facts.unreadable = true;
+    else {
+      if (isCount(assets.failedCount)) facts.failedMedia = assets.failedCount;
+      else if (assets.failedCount !== undefined) facts.unreadable = true;
+      if (assets.finished === false && !facts.moving) {
+        facts.moving = {
+          media: {
+            done: isCount(assets.done) ? assets.done : 0,
+            total: isCount(assets.total) ? assets.total : 0,
+          },
+        };
+      }
+    }
+  }
+  return facts;
+}
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
 /**
  * Read a sync payload the way a person would.
  *
@@ -224,6 +350,54 @@ export function syncPresentation(
   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';
+  const lanes = readLanes(status);
+
+  /**
+   * Part of the project did not get through. `sourceOnly` is the ranking
+   * split: a refused source change never heals on its own, so it outranks an
+   * unreachable hub; a failed transfer may be the outage itself, so file and
+   * media problems rank below it.
+   */
+  const attention = (sourceOnly: boolean): SyncPresentation | null => {
+    const parts: string[] = [];
+    let items = 0;
+    const add = (n: number, text: string) => {
+      if (n <= 0) return;
+      parts.push(text);
+      items += n;
+    };
+    const src = lanes.sourceSlugs.length;
+    add(src, `${plural(src, 'source change')} ${src === 1 ? 'was' : 'were'} not applied`);
+    if (!sourceOnly) {
+      add(lanes.failedFiles, `${plural(lanes.failedFiles, 'file')} could not be delivered`);
+      add(
+        lanes.tooLarge,
+        `${plural(lanes.tooLarge, 'file')} ${lanes.tooLarge === 1 ? 'is' : 'are'} too large to sync`
+      );
+      add(
+        lanes.blockedOther,
+        `${plural(lanes.blockedOther, 'file')} ${lanes.blockedOther === 1 ? 'is' : 'are'} blocked`
+      );
+      add(
+        lanes.held,
+        `${plural(lanes.held, 'change')} ${lanes.held === 1 ? 'is' : 'are'} held for your decision`
+      );
+      add(lanes.failedMedia, `${plural(lanes.failedMedia, 'media upload')} failed`);
+    }
+    if (items === 0) return null;
+    return {
+      phase: 'attention',
+      online: false,
+      label: `${items} to review`,
+      title:
+        `${items === 1 ? 'A change needs' : `${items} changes need`} your attention in ${project}: ` +
+        `${parts.join('; ')}.` +
+        (unreachable ? ' The hub is also unreachable right now.' : '') +
+        queueNote,
+      next: 'Open the Sync panel to see what is waiting and why.',
+      names: shownNames(lanes.sourceSlugs),
+    };
+  };
   // 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.
@@ -253,6 +427,14 @@ export function syncPresentation(
     };
   }
 
+  // A refused SOURCE change outranks an unreachable hub for the same reason a
+  // refusal does: it is sticky, and it is the part that needs a person.
+  // (With the hub reachable, the same sentence lists every other lane too.)
+  if (lanes.sourceSlugs.length > 0) {
+    const sourceAttention = attention(unreachable);
+    if (sourceAttention) return sourceAttention;
+  }
+
   // 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.
@@ -270,7 +452,7 @@ export function syncPresentation(
     };
   }
 
-  if (unreadable) {
+  if (unreadable || lanes.unreadable) {
     // A payload we cannot read is not a payload that says everything is fine.
     return {
       phase: 'connecting',
@@ -289,6 +471,8 @@ export function syncPresentation(
     // Pre-DDR-102 payload — no per-document counts, so a refusal cannot be
     // ruled out and the credential hedge stays.
     if (!online && isStalled) return stalled(true);
+    const laneAttention = online ? attention(false) : null;
+    if (laneAttention) return laneAttention;
     return {
       phase: online ? 'synced' : 'connecting',
       online,
@@ -315,6 +499,25 @@ export function syncPresentation(
     };
   }
 
+  // Needs a person, so it outranks work that will finish by itself.
+  const laneAttention = attention(false);
+  if (laneAttention) return laneAttention;
+
+  // Plan T16 — an AI edit that did not finish is kept on this device, not
+  // shared. It is the person's decision, so it reads as attention.
+  const ai = readAiAction(status.aiAction);
+  if (ai?.state === 'held') {
+    const n = ai.canvases;
+    return {
+      phase: 'attention',
+      online: true,
+      label: 'AI edit held',
+      title: `An unfinished AI edit to ${n} canvas${n === 1 ? '' : 'es'} is kept on this device — it is not shared with ${project} yet.`,
+      next: 'Open the Sync panel to publish it as it stands or discard it.',
+      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.
@@ -332,6 +535,61 @@ export function syncPresentation(
     };
   }
 
+  // Every canvas is in step, but files or media are still moving: that is
+  // syncing, not synced. The denominator is the ledger's (seed-progress.ts).
+  if (lanes.moving) {
+    const m = lanes.moving;
+    const detail =
+      'media' in m
+        ? `uploading media (${m.media.done} of ${m.media.total})`
+        : m.tracked > 0
+          ? `files ${m.delivered} of ${m.tracked} delivered`
+          : 'checking project files';
+    return {
+      phase: 'syncing',
+      online: true,
+      label:
+        'media' in m ? 'media ↑' : m.tracked > 0 ? `${m.delivered}/${m.tracked} files` : 'files…',
+      title:
+        `Syncing with ${project} — all ${total} canvas${total === 1 ? '' : 'es'} in step, ${detail}.` +
+        (lanes.paused ? ' Paused while the hub asks us to wait.' : '') +
+        queueNote,
+      next: 'Nothing to do — this continues on its own.',
+      names: [],
+    };
+  }
+
+  // Plan T29 — accepted revisions: "synced" documents only mean the replica is
+  // current. A change still waiting for the project's durable answer is saved
+  // on this device, not yet shared — so it is Saving, never Saved.
+  if (ai?.state === 'open') {
+    return {
+      phase: 'syncing',
+      online: true,
+      label: 'AI editing',
+      title: `An AI edit is in progress — its changes are shared with ${project} together when it finishes.`,
+      next: null,
+      names: [],
+    };
+  }
+  const acceptedPending = readAcceptedPending(status.accepted);
+  if (acceptedPending) {
+    const ageS = acceptedPending.oldestPendingAt
+      ? Math.max(0, Math.round((Date.now() - acceptedPending.oldestPendingAt) / 1000))
+      : 0;
+    return {
+      phase: 'syncing',
+      online: true,
+      label: `saving ${acceptedPending.pending}`,
+      title:
+        `Saving ${acceptedPending.pending} change${acceptedPending.pending === 1 ? '' : 's'} to ${project}` +
+        (ageS >= 10 ? ` — the oldest has waited ${ageS} s.` : '.') +
+        ' They are kept on this device until the project confirms them.',
+      next: ageS >= 60 ? 'Maude keeps trying. If this persists, check your connection.' : null,
+      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`
@@ -359,3 +617,28 @@ export function syncPresentation(
     names: pulledCount > 0 ? shownNames(status.pulled?.names) : [],
   };
 }
+
+/** `status.accepted`, validated — it is read off disk like every other count. */
+function readAcceptedPending(
+  raw: unknown
+): { pending: number; oldestPendingAt: number | null } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const r = raw as { pending?: unknown; oldestPendingAt?: unknown };
+  const pending = r.pending;
+  if (typeof pending !== 'number' || !Number.isInteger(pending) || pending <= 0 || pending > 1e6)
+    return null;
+  const at = r.oldestPendingAt;
+  return {
+    pending,
+    oldestPendingAt: typeof at === 'number' && Number.isFinite(at) && at > 0 ? at : null,
+  };
+}
+
+/** `status.aiAction`, validated — never trusted off disk. */
+function readAiAction(raw: unknown): { state: 'open' | 'held'; canvases: number } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const r = raw as { state?: unknown; canvases?: unknown };
+  if (r.state !== 'open' && r.state !== 'held') return null;
+  const canvases = Array.isArray(r.canvases) ? Math.min(r.canvases.length, 10_000) : 0;
+  return { state: r.state, canvases };
+}