flowviant 0.97.0 → 0.99.0

package/bin/lib/knowledge.mjs

@@ -63,7 +63,8 @@
  * `research/<slug>-v<N>.md`, with a generated `LIBRARY.md` at the root naming
  * every one (path, title, kind, the card that asked for it, the date, what it
  * supersedes). So "implement design A" is an agent opening LIBRARY.md, finding
- * design A, and reading the page.
+ * design A, and reading the page. At 0.99.0 a kept design is one folder,
+ * including its original relative sidecar paths and measured preview.
  *
  * SUBDIRECTORIES, AND EXACTLY TWO. The safe-name rule for a knowledge file
  * forbids every separator; a library item is the one thing allowed ONE, and
@@ -132,7 +133,7 @@ export const FLOWVIANT_OWN_PATHS = [
 export const LIBRARY_FILE = 'LIBRARY.md';
 /** The two subdirectories a kept item may live in, by kind. */
 export const LIBRARY_DIRS = { design: 'designs', research: 'research' };
-const LIBRARY_EXT = { design: '.html', research: '.md' };
+const LIBRARY_EXT = { design: ['.html', '.htm', '.gltf', '.obj', '.glb', '.bin'], research: ['.md'] };
 /** The server caps a library at 200 items; a longer manifest is cut. */
 const MAX_LIBRARY_ITEMS = 256;
 
@@ -148,23 +149,55 @@ const MARKER = '.flowviant/knowledge.rev';
  *  this is somebody's disk, and one place checking is one deploy away from
  *  zero places — the attachment fetch's own rule. */
 export const KNOWLEDGE_FILE_MAX_BYTES = 10 * 1024 * 1024;
+export const KNOWLEDGE_BINARY_MODEL_MAX_BYTES = 20 * 1024 * 1024;
+const knowledgeMaxFor = (name, base) => /\.(glb|bin)$/i.test(name)
+  ? Math.max(base, KNOWLEDGE_BINARY_MODEL_MAX_BYTES) : base;
 /** The manifest is capped at the server (25 files); a manifest longer than
  *  this is not one the product produced, and is cut rather than trusted. */
 const MAX_FILES = 64;
 
+/** FNV-1a, 32-bit, as 8 hex — deterministic, so the same long name always maps
+ *  to the same stored name. Verbatim against the server's `fnv1a8`
+ *  (apps/api/src/routes/sessionsAttachments.routes.ts). */
+function fnv1a8(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+/** What counts as an extension worth keeping through a cut. */
+const SAFE_EXT_RE = /^[A-Za-z0-9]{1,10}$/;
+const SAFE_NAME_MAX = 80;
+
 /**
- * `safeUploadName`, verbatim in effect (work.mjs): keeps the extension, drops
- * every path separator, never starts with a dot or a dash. Re-applied here
- * although the server did it, because this string becomes a path on this box.
+ * `safeFileName`, verbatim (apps/api/src/routes/sessionsAttachments.routes.ts):
+ * drops every path separator, never starts with a dot or a dash, and — since
+ * 2026-09-24 — THE EXTENSION SURVIVES A CUT. A bare `slice(0, 80)` truncated
+ * an over-long name mid-extension (an 84-character `….html` mockup stored as
+ * `….` with an unrecognised type and its bytes discarded), so a long name's
+ * stem is now cut and an 8-hex FNV-1a hash of the WHOLE sanitised name is
+ * appended before the extension: stable across calls, at most 80 characters,
+ * idempotent over its own output, and — the reason it is re-applied here
+ * rather than trusted to the server's own pass — byte-identical to what
+ * `safeFileName` computes there, so a knowledge file synced under this name
+ * and one requested by name later never disagree over the cut.
  */
 export function safeKnowledgeName(raw) {
-  const base = String(raw ?? '')
+  const clean = String(raw ?? '')
     .split(/[\\/]/)
     .pop()
     .replace(/[^A-Za-z0-9._-]/g, '_')
-    .replace(/^[.-]+/, '')
-    .slice(0, 80);
-  return base || 'file';
+    .replace(/^[.-]+/, '');
+  if (!clean) return 'file';
+  if (clean.length <= SAFE_NAME_MAX) return clean;
+  const dot = clean.lastIndexOf('.');
+  const ext = dot > 0 && SAFE_EXT_RE.test(clean.slice(dot + 1)) ? clean.slice(dot + 1) : '';
+  const stem = ext ? clean.slice(0, dot) : clean;
+  const tag = `-${fnv1a8(clean)}`;
+  const room = SAFE_NAME_MAX - tag.length - (ext ? ext.length + 1 : 0);
+  return `${stem.slice(0, room)}${tag}${ext ? `.${ext}` : ''}`;
 }
 
 /**
@@ -326,12 +359,30 @@ function writeKnowledgeMarker(checkoutDir, rev, lib = false) {
 export function safeLibraryPath(name, kind) {
   if (typeof name !== 'string' || !(kind in LIBRARY_DIRS)) return null;
   const parts = name.split('/');
-  if (parts.length !== 2) return null;
-  const [dir, file] = parts;
+  if (parts.length !== 2 && !(kind === 'design' && parts.length >= 3 && parts.length <= 7)) return null;
+  const [dir, ...rest] = parts;
+  const file = rest.at(-1);
   if (dir !== LIBRARY_DIRS[kind]) return null;
-  if (!file || file !== safeKnowledgeName(file)) return null;
-  if (!file.toLowerCase().endsWith(LIBRARY_EXT[kind]) || file.length <= LIBRARY_EXT[kind].length) return null;
-  return `${dir}/${file}`;
+  if (rest.length >= 2 && !/^[a-z0-9-]+-v[1-9][0-9]*$/.test(rest[0])) return null;
+  if (rest.slice(1, -1).some((p) => !safeBundleSegment(p))) return null;
+  if (!file || (rest.length === 1 ? file !== safeKnowledgeName(file) : !safeBundleSegment(file))) return null;
+  if (!LIBRARY_EXT[kind].some((ext) => file.toLowerCase().endsWith(ext) && file.length > ext.length)) return null;
+  return name;
+}
+
+function safeBundleSegment(part) {
+  return typeof part === 'string' && part.length > 0 && part.length <= 80 &&
+    /^[A-Za-z0-9][A-Za-z0-9._ -]*$/.test(part) && !part.endsWith('.');
+}
+
+function safeBundleFile(path, rootDir) {
+  if (typeof path !== 'string' || !path.startsWith(`${rootDir}/`)) return null;
+  const relative = path.slice(rootDir.length + 1);
+  if (relative === 'preview.png') return null;
+  const parts = relative.split('/');
+  if (!parts.length || parts.some((p) => !safeBundleSegment(p))) return null;
+  if (!/\.(gltf|obj|glb|bin|png|jpg|jpeg|gif|webp|svg|json)$/i.test(relative)) return null;
+  return path;
 }
 
 /** The manifest's library items that are safe to write, in manifest order, or
@@ -347,7 +398,14 @@ function libraryItemsOf(manifest) {
     const path = safeLibraryPath(it.name, it.kind);
     if (!path || seen.has(path.toLowerCase())) continue;
     seen.add(path.toLowerCase());
-    out.push({ ...it, path });
+    const bundleDir = path.split('/').length >= 3 ? path.split('/').slice(0, 2).join('/') : null;
+    const expectedPreview = bundleDir ? `${bundleDir}/preview.png` : it.name.replace(/\.html$/, '.png');
+    const previewPath = it.kind === 'design' && it.preview && it.preview.name === expectedPreview ? expectedPreview : null;
+    const files = bundleDir && Array.isArray(it.files) ? it.files.map((f, index) => ({ ...f,
+      index, path: safeBundleFile(f.name, bundleDir),
+    })).filter((f) => f.path && !seen.has(f.path.toLowerCase())) : [];
+    for (const f of files) seen.add(f.path.toLowerCase());
+    out.push({ ...it, path, files, previewPath, previewUnknown: it.kind === 'design' && path.endsWith('.html') && it.preview === undefined });
   }
   return out;
 }
@@ -408,6 +466,32 @@ function ensureSubdir(dir, name) {
   return path;
 }
 
+function ensureLibraryParents(dir, relativePath) {
+  const parts = relativePath.split('/');
+  let at = dir;
+  for (const part of parts.slice(0, -1)) at = ensureSubdir(at, part);
+}
+
+function sweepLibraryTree(dir, sub, wanted, result) {
+  const walk = (at, prefix = '') => {
+    let entries;
+    try { entries = readdirSync(at); } catch { return; }
+    for (const name of entries) {
+      const rel = prefix ? `${prefix}/${name}` : name;
+      const path = join(at, name);
+      let st;
+      try { st = lstatSync(path); } catch { continue; }
+      if (st.isDirectory() && !st.isSymbolicLink()) {
+        walk(path, rel);
+        try { if (readdirSync(path).length === 0) rmSync(path, { recursive: true, force: true }); } catch { /* next sync */ }
+      } else if (!wanted.has(rel)) {
+        try { rmSync(path, { recursive: true, force: true }); result.removed.push(`${sub}/${rel}`); } catch { /* next sync */ }
+      }
+    }
+  };
+  walk(join(dir, sub));
+};
+
 /** Does this manifest look like one the server produced? Anything else is
  *  ignored whole rather than half-applied. */
 export function isKnowledgeManifest(k) {
@@ -486,7 +570,8 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
 
   for (const f of planned) {
     const path = join(dir, f.local);
-    if (Number(f.bytes) > maxBytes) {
+    const fileMax = knowledgeMaxFor(f.name, maxBytes);
+    if (Number(f.bytes) > fileMax) {
       // Permanent for this rev, and NOT a reason to delete the rest. Any stale
       // local copy under this name goes, because it is not the file the
       // manifest now names.
@@ -497,7 +582,7 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
     if (typeof f.sha256 === 'string' && localSha(path) === f.sha256.toLowerCase()) continue;
     try {
       const buf = await fetchFile(f.id);
-      if (!Buffer.isBuffer(buf) || buf.byteLength > maxBytes) {
+      if (!Buffer.isBuffer(buf) || buf.byteLength > fileMax) {
         result.refused.push(f.local);
         keep.delete(f.local);
         continue;
@@ -574,58 +659,84 @@ async function syncLibrary({ dir, items, fetchFile, maxBytes, keep, result }) {
     }
   }
   for (const it of items) {
-    const [sub, file] = it.path.split('/');
-    const path = join(dir, sub, file);
+    const [sub, ...tail] = it.path.split('/');
+    const file = tail.join('/');
+    const path = join(dir, ...it.path.split('/'));
+    ensureLibraryParents(dir, it.path);
+    const itemMax = knowledgeMaxFor(it.path, maxBytes);
     wanted[sub].add(file);
-    if (Number(it.bytes) > maxBytes) {
+    if (it.previewPath) wanted[sub].add(it.previewPath.split('/').slice(1).join('/'));
+    if (it.previewUnknown) {
+      const oldPng = file.includes('/') ? `${file.slice(0, file.lastIndexOf('/'))}/preview.png` : file.replace(/\.html$/, '.png');
+      if (localSha(join(dir, sub, ...oldPng.split('/'))) !== null) wanted[sub].add(oldPng);
+    }
+    if (Number(it.bytes) > itemMax) {
       result.refused.push(it.path);
       wanted[sub].delete(file);
       continue;
     }
     if (typeof it.sha256 === 'string' && localSha(path) === it.sha256.toLowerCase()) {
       onDisk.push(it);
-      continue;
-    }
-    try {
-      const buf = await fetchFile(it.id, { library: true });
-      if (!Buffer.isBuffer(buf) || buf.byteLength > maxBytes) {
-        result.refused.push(it.path);
-        wanted[sub].delete(file);
-        continue;
+    } else {
+      try {
+        const buf = await fetchFile(it.id, { library: true });
+        if (!Buffer.isBuffer(buf) || buf.byteLength > itemMax) {
+          result.refused.push(it.path);
+          wanted[sub].delete(file);
+          continue;
+        }
+        if (typeof it.sha256 === 'string' && sha256Of(buf) !== it.sha256.toLowerCase()) {
+          throw new Error('sha256 mismatch');
+        }
+        ensureLibraryParents(dir, it.path);
+        writeAtomic(path, buf);
+        result.wrote.push(it.path);
+        onDisk.push(it);
+      } catch {
+        result.ok = false;
+        result.failed.push(it.path);
+        if (localSha(path) !== null) onDisk.push(it);
       }
-      if (typeof it.sha256 === 'string' && sha256Of(buf) !== it.sha256.toLowerCase()) {
-        throw new Error('sha256 mismatch');
+    }
+    if (it.previewPath && it.preview?.sha256) {
+      ensureLibraryParents(dir, it.previewPath);
+      const previewFile = join(dir, ...it.previewPath.split('/'));
+      if (localSha(previewFile) !== it.preview.sha256.toLowerCase()) {
+        try {
+          const buf = await fetchFile(it.id, { library: true, preview: true });
+          if (!Buffer.isBuffer(buf) || buf.byteLength > 2 * 1024 * 1024 || sha256Of(buf) !== it.preview.sha256.toLowerCase()) throw new Error('preview mismatch');
+          ensureLibraryParents(dir, it.previewPath);
+          writeAtomic(previewFile, buf);
+          result.wrote.push(it.previewPath);
+        } catch {
+          result.ok = false;
+          result.failed.push(it.previewPath);
+        }
       }
-      writeAtomic(path, buf);
-      result.wrote.push(it.path);
-      onDisk.push(it);
-    } catch {
-      result.ok = false;
-      result.failed.push(it.path);
-      // A stale copy is better than none until the retry lands — and it stays
-      // in the catalog only if it is actually there.
-      if (localSha(path) !== null) onDisk.push(it);
+    }
+    for (const f of it.files ?? []) {
+      ensureLibraryParents(dir, f.path);
+      const rel = f.path.split('/').slice(1).join('/');
+      wanted[sub].add(rel);
+      const filePath = join(dir, ...f.path.split('/'));
+      const fileMax = knowledgeMaxFor(f.path, maxBytes);
+      if (Number(f.bytes) > fileMax) { result.refused.push(f.path); wanted[sub].delete(rel); continue; }
+      if (localSha(filePath) === String(f.sha256).toLowerCase()) continue;
+      try {
+        const buf = await fetchFile(it.id, { library: true, fileIndex: f.index });
+        if (!Buffer.isBuffer(buf) || buf.byteLength > fileMax) { result.refused.push(f.path); wanted[sub].delete(rel); continue; }
+        if (sha256Of(buf) !== String(f.sha256).toLowerCase()) throw new Error('sha256 mismatch');
+        ensureLibraryParents(dir, f.path);
+        writeAtomic(filePath, buf);
+        result.wrote.push(f.path);
+      } catch { result.ok = false; result.failed.push(f.path); }
     }
   }
   // Each subdirectory holds exactly what the manifest names.
   for (const sub of Object.values(LIBRARY_DIRS)) {
     const subPath = join(dir, sub);
-    let entries = [];
-    try {
-      if (!lstatSync(subPath).isDirectory()) continue;
-      entries = readdirSync(subPath);
-    } catch {
-      continue;
-    }
-    for (const name of entries) {
-      if (wanted[sub].has(name)) continue;
-      try {
-        rmSync(join(subPath, name), { recursive: true, force: true });
-        result.removed.push(`${sub}/${name}`);
-      } catch {
-        /* best-effort */
-      }
-    }
+    try { if (!lstatSync(subPath).isDirectory()) continue; } catch { continue; }
+    sweepLibraryTree(dir, sub, wanted[sub], result);
     // An emptied subdirectory leaves with its last item.
     if (wanted[sub].size === 0) keep.delete(sub);
   }
@@ -697,18 +808,26 @@ function libraryStale(checkoutDir, manifest, { synced, refused }) {
   const items = libraryItemsOf(manifest);
   if (items === null) return false;
   if (!synced) return true;
-  const expected = items.filter((it) => !(Number(it.bytes) > KNOWLEDGE_FILE_MAX_BYTES) && !refused.has(it.path));
+  const expected = items.filter((it) => !(Number(it.bytes) > knowledgeMaxFor(it.path, KNOWLEDGE_FILE_MAX_BYTES)) && !refused.has(it.path));
   if (expected.length === 0) return false;
   const dir = join(checkoutDir, KNOWLEDGE_DIR);
   const isFile = (p) => {
     try {
+      let parent = dir;
+      for (const part of p.slice(dir.length + 1).split('/').slice(0, -1)) {
+        parent = join(parent, part);
+        const st = lstatSync(parent);
+        if (st.isSymbolicLink() || !st.isDirectory()) return false;
+      }
       return lstatSync(p).isFile();
     } catch {
       return false;
     }
   };
   if (!isFile(join(dir, LIBRARY_FILE))) return true;
-  return expected.some((it) => !isFile(join(dir, ...it.path.split('/'))));
+  return expected.some((it) => !isFile(join(dir, ...it.path.split('/'))) ||
+    (it.previewPath && !refused.has(it.previewPath) && !isFile(join(dir, ...it.previewPath.split('/')))) ||
+    (it.files ?? []).some((f) => !refused.has(f.path) && !isFile(join(dir, ...f.path.split('/')))));
 }
 
 /**
@@ -827,13 +946,14 @@ export function createKnowledgeSync({
  * URL is derived from the roster URL the way every `/fleet/*` path is, so a
  * self-hosted `FLOWVIANT_FLEET_URL` is honoured.
  */
-export function knowledgeFetcher({ fleetUrl, token, userAgent, maxBytes = KNOWLEDGE_FILE_MAX_BYTES }) {
+export function knowledgeFetcher({ fleetUrl, token, userAgent, maxBytes = KNOWLEDGE_BINARY_MODEL_MAX_BYTES }) {
   const base = String(fleetUrl).replace(/\/agents\/?$/, '/knowledge');
   // A kept library item (0.97.0) is its sibling, `GET /fleet/library/:id` —
   // the same credential, the same shape, the same caps.
   const libraryBase = String(fleetUrl).replace(/\/agents\/?$/, '/library');
-  return async (id, { library = false } = {}) => {
-    const res = await fetch(`${library ? libraryBase : base}/${encodeURIComponent(id)}`, {
+  return async (id, { library = false, preview = false, fileIndex = null } = {}) => {
+    const suffix = preview ? '/preview' : Number.isSafeInteger(fileIndex) && fileIndex >= 0 ? `/file/${fileIndex}` : '';
+    const res = await fetch(`${library ? libraryBase : base}/${encodeURIComponent(id)}${suffix}`, {
       headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent },
       signal: AbortSignal.timeout(60_000),
     });

package/bin/lib/landed.mjs

@@ -29,7 +29,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { git, baseBranchName } from './git.mjs';
-import { stripDelims, taskIdsFromMessage } from './worktreeDiff.mjs';
+import { commitRecord, stripDelims, taskIdsFromMessage } from './worktreeDiff.mjs';
 import { warn } from './ui.mjs';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 
@@ -95,41 +95,39 @@ export function createLandedObserver({ repoRoot, baseRef }) {
    *  merge commit describes a range rather than doing work, and its
    *  constituents are walked as themselves.
    *
-   *  THE SHA LIST COMES FROM REV-LIST, NEVER FROM THE FORMATTED LOG. Git
-   *  preserves the 0x1e/0x1f delimiter bytes inside a commit BODY (verified
-   *  empirically), so a crafted message can fabricate whole records — an
-   *  arbitrary sha plus Flowviant-Task ids that /fleet/base-landed would close
-   *  cards on. rev-list prints nothing an author controls, so its output is
-   *  the set of commits that exist: a parsed record whose sha is not in the
-   *  batch is a forgery and is dropped, a repeated sha is the same forgery
-   *  wearing a real commit's name, and the delimiter bytes are stripped from
-   *  every surviving field.
+   *  THE SHA LIST COMES FROM REV-LIST, NEVER FROM THE FORMATTED LOG, and each
+   *  commit is then read BY ITS OWN SHA (`commitRecord`, one `git show` per
+   *  commit) rather than as one delimited multi-record log. A batched log
+   *  used to print every commit's `%H%x1f%s%x1f%B%x1e` back to back and split
+   *  the blob on those same delimiter bytes — bytes git preserves verbatim
+   *  inside a commit BODY (verified empirically), so a crafted message could
+   *  embed its own fake `%x1e`/`%x1f%1f` run and fabricate an extra "record"
+   *  naming an arbitrary sha and Flowviant-Task ids that /fleet/base-landed
+   *  would close cards on. Reading one sha at a time removes the multi-record
+   *  parse entirely — there is no blob to split, so there is nothing for an
+   *  embedded delimiter to forge a SECOND record out of. `stripDelims` still
+   *  scrubs whatever lands in the subject/body of the commit it actually
+   *  belongs to, the same defence-in-depth `branchCommits` above keeps.
    *
-   *  BOUNDING THE BODY FETCH TO THE BATCH is what makes the header's batching
-   *  contract true at any range size: `%B` over the whole range grows without
-   *  bound, so the formatted log runs over exactly the shas being reported
-   *  this beat (`--no-walk=unsorted` shows precisely the commits named, in
-   *  argv order — measured). */
+   *  ONE UNREADABLE COMMIT IS SKIPPED, NOT AN ABORT OF THE WHOLE BATCH:
+   *  `commitRecord` runs through `gitRaw`, whose `maxBuffer` is git.mjs's
+   *  plain default (1MiB) rather than this module's widened `gitWide` — a
+   *  single commit whose message alone exceeds that returns null and is
+   *  dropped, while every other commit in the batch still reports. */
   const walk = (from, to) => {
     const shas = gitWide(['rev-list', '--reverse', '--no-merges', `${from}..${to}`])
       .split('\n')
       .filter((s) => SHA_RE.test(s));
     const batch = shas.slice(0, MAX_COMMITS);
     const tipAfter = shas.length > MAX_COMMITS ? batch[batch.length - 1] : null;
-    if (batch.length === 0) return { commits: [], tipAfter };
-    const real = new Set(batch);
-    const raw = gitWide(['log', '--no-walk=unsorted', '--format=%H%x1f%s%x1f%B%x1e', ...batch]);
     const out = [];
-    for (const rec of raw.split('\x1e')) {
-      const line = rec.replace(/^\n+/, '');
-      if (!line.trim()) continue;
-      const [sha, subject, ...bodyParts] = line.split('\x1f');
-      if (!real.has(sha)) continue;
-      real.delete(sha);
+    for (const sha of batch) {
+      const rec = commitRecord(sha, repoRoot);
+      if (!rec) continue;
       out.push({
         sha,
-        subject: stripDelims(subject).slice(0, 200),
-        taskIds: taskIdsFromMessage(stripDelims(bodyParts.join('\n'))).slice(0, 8),
+        subject: stripDelims(rec.subject).slice(0, 200),
+        taskIds: taskIdsFromMessage(stripDelims(rec.body)).slice(0, 8),
       });
     }
     return { commits: out, tipAfter };
@@ -202,13 +200,23 @@ export function createLandedObserver({ repoRoot, baseRef }) {
         for (const r of j?.data?.deployRefused ?? []) {
           warn(`deploy-on-merge refused for target "${r?.targetId}": ${r?.reason}`);
         }
+      } else if (res.status === 408 || res.status === 429) {
+        // A TIMEOUT OR A RATE LIMIT IS "NOT NOW", NOT "NEVER". Both used to
+        // land in the drop below, so one 429 — a busy operator IP past the
+        // limiter — skipped the range for good: its trailers and receipt shas
+        // never closed their cards (in PR mode the observer is the ONLY road
+        // to Done) and deploy-on-merge for that tip was never queued. Keep the
+        // stored tip, exactly as a 5xx does; the next beat re-walks it.
       } else if (res.status >= 400 && res.status < 500) {
         // A persistent 4xx (deploy skew, a payload this server refuses) would
         // otherwise re-send the same poison range on every beat forever.
-        // Drop the range — the closes it carried re-run at the next REAL tip
-        // move only if their cards are still open, which is the idempotent
-        // half; the honest cost is stated out loud.
-        writeState({ ref, tip });
+        // Drop THIS BATCH — to `reportedTip`, the last commit it carried, never
+        // the full tip: a range past the cap has a remainder this batch never
+        // sent, and advancing to the tip discarded that too. The closes it
+        // carried re-run at the next REAL tip move only if their cards are
+        // still open, which is the idempotent half; the honest cost is stated
+        // out loud.
+        writeState({ ref, tip: reportedTip });
         warn(`base-landed report refused (${res.status}) — skipped ${commits.length} commit(s)`);
       }
     } catch {