flowviant 0.97.0 → 0.100.0

package/bin/lib/hooks/readGuard.mjs

@@ -38,6 +38,12 @@
  *    into a flag), a newline. A read-only turn runs ONE plain command; every
  *    one of these is a second command or a redirect wearing the first one's
  *    permission.
+ *  · shell syntax that REWRITES A WORD after this guard read it — braces,
+ *    parentheses and glob characters (`{ } ( ) * ? [`). `--outp{u,u}t=x` is
+ *    `--output=x` by the time git sees it, and the substring tests below can
+ *    only judge the word as written. (Quoted or not: the normalisation above
+ *    has already dropped the quotes, so a quoted `*` is refused too — the
+ *    over-refusal the paragraph above accepts.)
  *  · the git arguments above, as substrings (so `--config` covers
  *    `--config-env`, `--output` covers `--output-directory`), plus a bare `-c`
  *    token and any token beginning `-O`.
@@ -75,6 +81,24 @@ const SHELL = [
   ['$', 'an expansion'],
   ['\n', 'a second line'],
   ['\r', 'a second line'],
+  // SHELL SYNTAX THE SUBSTRING TESTS BELOW DO NOT MODEL (2026-09-24, the
+  // audit). The shell rewrites a word AFTER this guard has read it, so a banned
+  // flag can be ASSEMBLED past a substring check: `--outp{u,u}t=x` and
+  // `-{c,c}` brace-expand into `--output=x` and `-c`, and `git log -1
+  // --outp{u,u}t=pwned.txt` wrote the file with this guard returning null
+  // (measured, git 2.55). Globs do the same with a planted file name —
+  // `-?` expands to a file called `-c` — and zsh adds glob QUALIFIERS
+  // (`*(e:…:)`, which evaluate code). None of them is something a single
+  // plain read needs, so the guard refuses the syntax rather than trying to
+  // expand it the way some shell would: over-refusal is the safe direction,
+  // and the Glob tool is the tool-shaped way to match names.
+  ['{', 'brace expansion'],
+  ['}', 'brace expansion'],
+  ['(', 'a subshell or glob qualifier'],
+  [')', 'a subshell or glob qualifier'],
+  ['*', 'a glob'],
+  ['?', 'a glob'],
+  ['[', 'a glob'],
 ];
 
 /**

package/bin/lib/instance.mjs

@@ -97,7 +97,7 @@ import {
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
-import { VERSION } from './config.mjs';
+import { VERSION, PROCESS_STARTED_AT } from './config.mjs';
 
 /** Deliberately a HASH: a credential must never become a filename. */
 export function instanceLockPath(fleetToken) {
@@ -139,11 +139,56 @@ function readHolder(path) {
   }
 }
 
+/** Read-only desktop measurement. No lock is unknown because an unguarded or
+ * older daemon may still run; a stale lock with a dead pid measures empty. */
+export function daemonRunningFor(fleetToken) {
+  const path = instanceLockPath(fleetToken);
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); }
+  catch { return null; }
+  let holder;
+  try { holder = JSON.parse(raw); } catch { return null; }
+  if (!Number.isInteger(holder?.pid) || holder.pid <= 0) return null;
+  if (!alive(holder.pid)) return false;
+  return stillTheHolder(holder);
+}
+
+/**
+ * argv[1] AS IT WAS TYPED, when that differs from the resolved form.
+ *
+ * Node resolves `process.argv[1]` to an absolute path, while `/proc/<pid>/cmdline`
+ * and `ps` show the argv the process was actually given. A daemon started as
+ * `node bin/cli.mjs` (a dev checkout, `npm start`, a Docker CMD with a WORKDIR)
+ * therefore recorded `/abs/bin/cli.mjs` and was matched against `node
+ * bin/cli.mjs`, judged stale WHILE ALIVE — a second start ran beside it and
+ * `flowviant stop` signalled nothing. The raw token is recorded beside `entry`
+ * so both spellings identify the process. Linux only: `ps` joins argv with
+ * spaces, so no token can be recovered from it reliably, and there the absolute
+ * form plus the start-time check stand as before.
+ */
+function rawEntry() {
+  if (platform() !== 'linux') return null;
+  try {
+    const tokens = readFileSync('/proc/self/cmdline', 'utf8').split('\0');
+    const raw = tokens[1 + process.execArgv.length];
+    return raw && raw !== process.argv[1] ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 const record = (repoRoot) =>
   JSON.stringify({
     pid: process.pid,
     repoRoot,
-    startedAt: new Date().toISOString(),
+    // THE PROCESS'S START, not the moment the lock was written. The start path
+    // can wait on a person at the picker or the binding confirm for as long as
+    // they take (there is no answer time limit), and a lock line written three
+    // minutes after the process began put a LIVE daemon outside the 120s window
+    // startedAroundLockWrite brackets — so a second start cleared its "stale"
+    // lock and ran beside it, and stop and disconnect skipped it. The window now
+    // measures clock granularity only, whatever a prompt cost.
+    startedAt: PROCESS_STARTED_AT,
     // The script we were started from, and what we are. A takeover matches the
     // live command line against `entry` before signalling anything — a lock
     // records a PID, and a crashed daemon's PID can be reused by anything.
@@ -151,9 +196,68 @@ const record = (repoRoot) =>
     // matched on the holder's process START TIME instead; stillTheHolder says
     // why that is the weaker of the two claims and still strong enough.
     entry: process.argv[1] || '',
+    ...(rawEntry() ? { entryRaw: rawEntry() } : {}),
     version: VERSION,
   });
 
+/** Up to this many parents are walked looking for the daemon we re-exec'd from.
+ *  `npx -y flowviant@latest` puts `npm exec` (and a `sh -c`) between the old
+ *  daemon and the new one; eight is several times that chain. */
+const ANCESTOR_DEPTH = 8;
+
+/** The parent pid of `pid`, or null where it cannot be read. */
+function parentOf(pid) {
+  try {
+    if (platform() === 'linux') {
+      const raw = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const close = raw.lastIndexOf(')');
+      if (close < 0) return null;
+      const ppid = Number.parseInt(raw.slice(close + 1).trim().split(/\s+/)[1], 10);
+      return Number.isInteger(ppid) && ppid > 0 ? ppid : null;
+    }
+    if (platform() === 'darwin') {
+      const out = execFileSync('ps', ['-o', 'ppid=', '-p', String(pid)], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 3000,
+      });
+      const ppid = Number.parseInt(out.trim(), 10);
+      return Number.isInteger(ppid) && ppid > 0 ? ppid : null;
+    }
+  } catch {
+    /* unreadable — ancestry unknown */
+  }
+  return null;
+}
+
+/**
+ * IS THIS HOLDER THE DAEMON THAT RE-EXEC'D US? — the self-update case.
+ *
+ * The direct parent is the global-install path: update.mjs spawns
+ * `process.execPath` itself, so the successor's ppid IS the holder. Under npx
+ * — the documented launch — the successor is spawned by `npm exec`, which the
+ * old daemon spawned, so the holder is a GRANDPARENT and a ppid check read it
+ * as a rival: the new daemon SIGTERMed its own proxy, the foreground process
+ * exited 143 while the successor ran on detached (or, with --no-takeover, both
+ * exited and the machine went dark after every update). So update.mjs names
+ * the pid it re-exec'd from, and that pid is adopted only when it really is an
+ * ANCESTOR of this process: the env var alone is inherited by anything the
+ * daemon spawns and proves nothing on its own. Ancestry that cannot be read
+ * adopts nothing — the pre-existing takeover rules then apply.
+ */
+function isOurReexecParent(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (pid === process.ppid) return true;
+  if (process.env.FLOWVIANT_REEXEC_FROM !== String(pid)) return false;
+  let p = process.ppid;
+  for (let i = 0; i < ANCESTOR_DEPTH && p && p > 1; i++) {
+    const up = parentOf(p);
+    if (up === pid) return true;
+    p = up;
+  }
+  return false;
+}
+
 /** Same directory, whatever it is spelled as — symlinks and trailing slashes
  *  included. A repo compared by string would let `/repo` and `/repo/` past. */
 function samePath(a, b) {
@@ -208,7 +312,7 @@ export function daemonInSameRepo(repoRoot, ownPath) {
     if (path === ownPath) continue; // our own credential — the lock above owns that question
     const holder = readHolder(path);
     if (!holder || !alive(holder.pid)) continue;
-    if (holder.pid === process.ppid) continue; // ourselves mid self-update re-exec
+    if (isOurReexecParent(holder.pid)) continue; // ourselves mid self-update re-exec
     if (samePath(holder.repoRoot, repoRoot)) {
       NEIGHBOUR_PATHS.set(holder, path);
       return holder;
@@ -226,7 +330,10 @@ export function daemonInSameRepo(repoRoot, ownPath) {
  *  around 41s. 120s is ~3x that worst path and ~4000x the typical one, and it is
  *  still short enough that pid reuse cannot reach into it: reuse means cycling
  *  the entire pid space (4194304 by default), which no machine does inside two
- *  minutes. */
+ *  minutes. (Since the lock records the PROCESS start rather than the moment it
+ *  was written, a lock from this version sits a few milliseconds from its
+ *  process whatever the start path cost; the window's width is for locks older
+ *  daemons wrote, which still stamp the write.) */
 const TAKEOVER_START_WINDOW_MS = 120_000;
 
 /** ...and how far the OTHER way, which is a unit problem rather than a real
@@ -421,15 +528,20 @@ function stillTheHolder(holder) {
   // alive, so it takes the same road as a missing one.
   if (!want) return startedAroundLockWrite(holder);
   let cmdline;
+  let tokens;
   try {
-    cmdline =
-      platform() === 'linux'
-        ? readFileSync(`/proc/${holder.pid}/cmdline`, 'utf8').replace(/\0/g, ' ')
-        : execFileSync('ps', ['-o', 'command=', '-p', String(holder.pid)], {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-            timeout: 3000,
-          });
+    if (platform() === 'linux') {
+      const raw = readFileSync(`/proc/${holder.pid}/cmdline`, 'utf8');
+      tokens = raw.split('\0');
+      cmdline = raw.replace(/\0/g, ' ');
+    } else {
+      cmdline = execFileSync('ps', ['-o', 'command=', '-p', String(holder.pid)], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 3000,
+      });
+      tokens = cmdline.trim().split(/\s+/);
+    }
   } catch {
     // NOT `false`. takeOverFrom already returned early if the pid were gone, so
     // reaching here means the process is alive and we could not READ it —
@@ -437,7 +549,10 @@ function stillTheHolder(holder) {
     // here is what made the refusal claim the pid belonged to somebody else.
     return null;
   }
-  if (!cmdline.includes(want)) return false;
+  // The typed spelling is matched as a whole TOKEN, never a substring: a
+  // relative `bin/cli.mjs` is a fragment of countless command lines.
+  const raw = typeof holder.entryRaw === 'string' && holder.entryRaw ? holder.entryRaw : null;
+  if (!cmdline.includes(want) && !(raw && tokens.includes(raw))) return false;
   // AN ENTRY MATCH ALONE IS NOT IDENTITY. Every daemon on the box shares one
   // entry path under a global install, so "cmdline contains this cli.mjs"
   // proves "is SOME flowviant daemon", not "is the daemon that wrote THIS
@@ -711,7 +826,7 @@ export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
       // ownership-checked, so it will not delete the lock it handed over.
       // (`flowviant login` also proxies a child, but that parent never reached
       // the daemon and holds nothing — the child simply acquires.)
-      if (holder.pid === process.ppid) {
+      if (isOurReexecParent(holder.pid)) {
         try {
           writeFileSync(path, record(repoRoot));
         } catch {

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),
     });