flowviant 0.125.18 → 0.125.21

package/README.md

@@ -188,7 +188,17 @@ From **0.86.0**, a project whose owner turns on **Publish agent branches** has e
 
 You run your dev server yourself, in the session's own worktree, exactly as you would in any terminal. The daemon NOTICES the listening port; ask for a share in the app and it puts a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) quick tunnel in front of it (auto-fetched if missing, pinned and checksummed), behind the daemon's own gate. Viewers reach the share through Flowviant's relay at `<name>.flowviant.dev`, never the tunnel's own address, and the gate admits only the share's password or a short-lived grant signed with the share's key. Flowviant stores that key and the password with the share, and its relay mints grants for signed-in project members — or for anyone with the link, if the share's owner opens it to everyone. Since 0.72.0 the gate also lets the Workbench embed the share in a frame: it rewrites the response's frame policy to permit exactly the app's origin, and a framed sign-in gets a partitioned cookie so it works where third-party cookies are blocked.
 
-The daemon never executes anything the repository declares. An earlier version read a `.flowviant/preview.json` from the branch and spawned the command it named — that start path was removed in 0.53.0 and is not coming back; see the header of `bin/lib/preview.mjs` for exactly what it did, so nobody rebuilds it.
+Sharing never starts a repository command. An earlier version read a `.flowviant/preview.json` from the branch and spawned the command it named — that sharing start path was removed in 0.53.0; see the header of `bin/lib/preview.mjs`.
+
+## Local UI self-review in code agents
+
+During a code build, the same agent can run a bounded local Chromium review before delivery. Its turn supplies the exact helper command and JSON-plan format. The agent chooses the repository-supported preview argv and dedicated port, names its script/configuration basis, and describes disposable fixtures. The runner starts that command inside the worktree with an isolated home and no inherited SDK credentials, measures its listener and process group, then checks HTTP readiness. It does not install a browser or dependencies, share a preview, or open a public tunnel.
+
+Each plan contains local routes and ordered CSS-selector actions (`click`, `fill`, `submit`, `waitFor`, `assertText`, `assertUrl`). Chromium uses fresh contexts for 1440×900 desktop and 390×844 mobile captures. Click/submit mean DOM activation; assertions establish the resulting state. A preview-only proxy and request fence block other destinations, popups, downloads, frames, workers and sockets. Apps requiring those capabilities must report the affected checks skipped or use a disposable fixture that works within this boundary. Repository code still executes as the user's UID; the runner is not a sandbox for a malicious backend or a substitute for choosing safe fixtures.
+
+On Claude Code and Codex build turns, `card_ui_review.inspect_screenshot` can supply an exact captured PNG as native image input. The agent must actually inspect the images and report what it saw, or report the runtime's image-input failure. A screenshot or image-input receipt alone never counts as a visual verdict. Other build CLIs can use their existing image tools if available and must name unavailable capabilities honestly.
+
+The agent can fix in-scope findings and rerun up to three attempts per turn, each capped at two minutes including startup. Every attempt stops its owned browser and preview, including on cancellation; teardown also tracks their process groups. Reports and screenshots use `.flowviant/artifacts/`, and the existing delivery Verification retains routes, viewports, actions/outcomes, scrubbed diagnostics and source identity. Tracked/nonignored file bytes and HEAD are remeasured at delivery; later changes mark evidence stale. Ignored build/runtime files are outside that source measurement. The project check, fresh read-only pre-review, human approval and merge remain separate.
 
 ## Modes
 

package/bin/cli.mjs

@@ -85,6 +85,19 @@ if (process.argv[2] === '__capture-mcp') {
   process.exit(process.exitCode ?? 0);
 }
 
+if (process.argv[2] === '__reference-mcp') {
+  await (await import('./lib/publicReferenceTool.mjs')).referenceToolMain();
+  // A screenshot can exceed the pipe buffer. EOF on the client's input must
+  // not truncate a completed result while stdout is still draining.
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
+if (['__ui-review', '__ui-review-mcp'].includes(process.argv[2])) {
+  await (await import('./lib/uiReview.mjs')).uiReviewMain(process.argv[2] === '__ui-review-mcp');
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__orchestrator-mcp') {
   await (await import('./lib/orchestratorClient.mjs')).orchestratorMcpMain();
   process.exit(process.exitCode ?? 0);

package/bin/lib/artifactCache.mjs

@@ -0,0 +1,336 @@
+/** Versioned local cache ownership. Call mutations under the place writer lock.
+ * No age, Library membership, or successful upload proves a file disposable.
+ * The lifecycle owner must supply a complete, version-bound use/bundle release. */
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, openSync, closeSync, fsyncSync, fstatSync, readFileSync, writeFileSync, renameSync, unlinkSync, linkSync, rmSync, lstatSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { ensureRealSubdir, realDirState } from './ownedDirs.mjs';
+
+const hash = b => createHash('sha256').update(b).digest('hex');
+const safe = n => typeof n === 'string' && n.length <= 500 && !/[\\\x00-\x1f\x7f]/.test(n) && n.split('/').every(p => p && p !== '.' && p !== '..' && !p.startsWith('.'));
+const sha = s => /^[a-f0-9]{64}$/.test(s ?? '');
+const stamp = s => `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`;
+const MAX = 32 * 1024 * 1024;
+
+export function createArtifactCache({ placeDir, path, scope, fetchVersion, getDiscards = () => new Set(), getUses = () => [], managedKind = null, managedRoot = null, unlink = unlinkSync }) {
+  if (managedKind && !['scratch', 'native-image'].includes(managedKind)) throw new Error('unknown-managed-kind');
+  const root = managedKind ? resolve(managedRoot) : resolve(placeDir, '.flowviant/artifacts');
+  const relative = name => managedKind ? name : `.flowviant/artifacts/${name}`;
+  const pathFor = name => join(root, name);
+  const identity = JSON.stringify({ ...scope, placeDir: resolve(placeDir), ...(managedKind ? { managedKind, root } : {}) });
+  const load = () => {
+    if (!path) throw new Error('ownership-unavailable');
+    let fd;
+    try {
+      fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const st = fstatSync(fd);
+      if (!st.isFile() || st.size > 2 * 1024 * 1024) throw new Error('ownership-unreadable');
+      const state = JSON.parse(readFileSync(fd, 'utf8'));
+      if (state.version !== 1 || state.identity !== identity || !Array.isArray(state.files) || state.files.length > 2000 || state.files.some(f =>
+        !safe(f.name) || f.relativePath !== relative(f.name) || !sha(f.sha256) || typeof f.localVersion !== 'string' || !['local', 'evicting', 'evicted', 'restoring', 'discarded'].includes(f.state))) throw new Error('ownership-unreadable');
+      return state;
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        try { lstatSync(`${path}.guard`); }
+        catch (guardError) {
+          if (guardError.code === 'ENOENT') return { version: 1, identity, files: [] };
+          throw guardError;
+        }
+        throw new Error('ownership-ledger-missing');
+      }
+      throw e;
+    }
+    finally { if (fd !== undefined) closeSync(fd); }
+  };
+  const save = state => {
+    if (!path || realDirState(dirname(path)) !== 'dir') throw new Error('ownership-unavailable');
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    try {
+      // The independent guard distinguishes a legacy unmeasured place from
+      // loss of a ledger that may contain eviction receipts. Persist it first.
+      let guard;
+      try {
+        guard = openSync(`${path}.guard`, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+        writeFileSync(guard, identity); fsyncSync(guard);
+      } catch (e) { if (e.code !== 'EEXIST') throw e; }
+      finally { if (guard !== undefined) closeSync(guard); }
+      const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+      try { writeFileSync(fd, JSON.stringify(state)); fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(tmp, path);
+      const parent = openSync(dirname(path), constants.O_RDONLY | constants.O_NOFOLLOW);
+      try { fsyncSync(parent); } finally { closeSync(parent); }
+    }
+    finally { rmSync(tmp, { force: true }); }
+  };
+  const measure = name => {
+    if (!safe(name)) throw new Error('unsafe-path');
+    // A registered managed root must be physical, not an alias into a shared
+    // home or source tree. Every descendant parent is checked separately.
+    if (realpathSync(root) !== root) throw new Error('unsafe-parent');
+    let parent = root;
+    for (const part of (dirname(name) === '.' ? [] : dirname(name).split('/'))) {
+      parent = join(parent, part);
+      const kind = realDirState(parent);
+      if (kind !== 'dir') throw Object.assign(new Error('unsafe-parent'), { code: kind === 'none' ? 'ENOENT' : 'UNSAFE' });
+    }
+    let fd;
+    try {
+      fd = openSync(pathFor(name), constants.O_RDONLY | constants.O_NOFOLLOW);
+      const st = fstatSync(fd);
+      if (!st.isFile() || st.size > MAX) throw new Error('unsafe-file');
+      const bytes = readFileSync(fd);
+      if (stamp(fstatSync(fd)) !== stamp(st) || bytes.length !== st.size) throw new Error('local-version-changed');
+      return { bytes, sha256: hash(bytes), signature: stamp(st), size: st.size };
+    } finally { if (fd !== undefined) closeSync(fd); }
+  };
+  /** Only a measured local version paired with the exact successful upload. */
+  const record = ({ name, remote, uses = null }) => {
+    const local = measure(name);
+    if (!remote?.id || remote.sha256 !== local.sha256) throw new Error('remote-version-unverified');
+    const state = load(), old = state.files.find(f => f.name === name);
+    if (old?.state !== 'discarded' && old?.signature === local.signature && old.sha256 === local.sha256 && old.remote?.id === remote.id && !old.uses?.includes('pending-upload')) return old;
+    const ref = { name, relativePath: relative(name), sha256: local.sha256, bytes: local.size,
+      signature: local.signature, localVersion: randomUUID(), remote: { id: remote.id, sha256: remote.sha256 },
+      uses, bundle: null, state: 'local' };
+    state.files = [...state.files.filter(f => f.name !== name), ref]; save(state); return ref;
+  };
+  /** A queued upload is owned but unrecoverable until its exact remote id
+   * arrives. A crash loses no use pin and grants no eviction permission. */
+  const trackUpload = name => {
+    const local = measure(name), state = load(), old = state.files.find(f => f.name === name);
+    const same = old && old.state !== 'discarded' && old.signature === local.signature && old.sha256 === local.sha256;
+    const ref = { name, relativePath: relative(name), sha256: local.sha256, bytes: local.size,
+      signature: local.signature, localVersion: same ? old.localVersion : randomUUID(), remote: same ? old.remote : null,
+      uses: [...new Set([...(same && Array.isArray(old.uses) ? old.uses : ['requirements-unknown']), 'pending-upload'])],
+      bundle: null, state: 'local' };
+    state.files = [...state.files.filter(f => f.name !== name), ref]; save(state); return ref;
+  };
+  const recordManaged = ({ name, turnId, preserved = null }) => {
+    if (!managedKind || !turnId) throw new Error('ownership-unknown');
+    const local = measure(name), state = load();
+    const old = state.files.find(f => f.name === name);
+    if (old && old.state !== 'discarded' && old.signature === local.signature && old.sha256 === local.sha256) {
+      if (old.turnId !== turnId) {
+        old.uses = [...new Set([...(old.uses ?? ['requirements-unknown']), `turn:${turnId}`,
+          ...(managedKind === 'native-image' ? ['resume-inputs-unknown'] : [])])];
+        old.turnId = turnId; old.state = 'local';
+      }
+      if (preserved && preserved.sha256 === local.sha256) { old.preserved = preserved; old.remote = preserved.remote; }
+      save(state); return old;
+    }
+    if (preserved && preserved.sha256 !== local.sha256) throw new Error('preserved-copy-unknown');
+    const ref = { name, relativePath: relative(name), kind: managedKind, turnId,
+      sha256: local.sha256, bytes: local.size, signature: local.signature,
+      localVersion: randomUUID(), remote: preserved?.remote ?? null, preserved,
+      uses: [`turn:${turnId}`, ...(managedKind === 'native-image' ? ['resume-inputs-unknown'] : /\.(png|webp|glb|gltf|bin|obj|mtl|html?|json)$/i.test(name) ? ['required-inputs-unknown'] : [])],
+      bundle: null, state: 'local' };
+    state.files = [...state.files.filter(f => f.name !== name), ref]; save(state); return ref;
+  };
+  /** Evidence is version-bound. Null uses/bundle means unknown, never released.
+   * Include review/revision, pending uploads, producer/consumer and resume pins.
+   * Bundle lists exact versions of every viewer, model and original resource. */
+  const requirements = ({ name, localVersion, uses, bundle }) => {
+    const state = load(), ref = state.files.find(f => f.name === name && f.localVersion === localVersion);
+    if (!ref || ref.state !== 'local') throw new Error('local-version-changed');
+    if (managedKind === 'scratch') {
+      if (!Array.isArray(uses) || !uses.every(u => typeof u === 'string')) throw new Error('requirements-unknown');
+      ref.uses = uses; save(state); return;
+    }
+    if (!Array.isArray(uses) || !uses.every(u => typeof u === 'string') || !bundle?.complete || !Array.isArray(bundle.files) || !bundle.files.length || bundle.files.length > 256 || new Set(bundle.files.map(f => f.name)).size !== bundle.files.length ||
+        !bundle.files.every(f => safe(f.name) && sha(f.sha256) && typeof f.id === 'string') ||
+        !bundle.files.some(f => f.name === name && f.id === ref.remote?.id && f.sha256 === ref.sha256)) throw new Error('requirements-unknown');
+    ref.uses = uses; ref.bundle = bundle; save(state);
+  };
+  const verified = async ref => {
+    if (!fetchVersion) throw new Error('recovery-unavailable');
+    const bytes = Buffer.from(await fetchVersion(ref));
+    if (bytes.length > MAX || hash(bytes) !== ref.sha256) throw new Error('remote-version-mismatch');
+    return bytes;
+  };
+  const eligibility = ref => {
+    if (!ref || ref.state === 'discarded') return 'ownership-unknown';
+    if (!Array.isArray(ref.uses) || (managedKind !== 'scratch' && !ref.bundle?.complete)) return 'requirements-unknown';
+    if (ref.uses.length) return 'active-use';
+    return null;
+  };
+  const bundleEligibility = (state, ref) => {
+    if (managedKind === 'scratch') return null;
+    for (const file of ref.bundle?.files ?? []) {
+      const member = state.files.find(f => f.name === file.name && f.sha256 === file.sha256 && f.remote?.id === file.id);
+      const reason = eligibility(member);
+      if (reason || getUses(file.name).length) return reason ?? 'active-use';
+    }
+    return null;
+  };
+  /** Non-mutating remote phase, safe outside the place writer lock. The
+   * caller may memoize these exact bytes for a brief locked eviction phase. */
+  const prepareEviction = async ({ name, localVersion }) => {
+    try {
+      const state = load(), ref = state.files.find(f => f.name === name && f.localVersion === localVersion);
+      if (ref?.state === 'evicted') return { status: 'ready', name }; // bookkeeping only; no new deletion
+      const reason = eligibility(ref);
+      if (reason || getUses(name).length || getDiscards().has(name)) return { status: 'retained', name, reason: reason ?? 'active-use' };
+      const bundleReason = bundleEligibility(state, ref);
+      if (bundleReason) return { status: 'retained', name, reason: bundleReason };
+      let bytes = 0;
+      for (const file of ref.bundle?.files ?? []) {
+        bytes += (await verified({ ...file, remote: { id: file.id, sha256: file.sha256 } })).length;
+        if (bytes > 80 * 1024 * 1024) throw new Error('bundle-too-large');
+      }
+      return { status: 'ready', name };
+    } catch (error) { return { status: 'retained', name, reason: error.message }; }
+  };
+  const evict = async ({ name, localVersion }) => {
+    let reclaimed = null;
+    try {
+      let state = load(), ref = state.files.find(f => f.name === name && f.localVersion === localVersion);
+      if (getDiscards().has(name)) return { status: 'retained', name, reason: 'explicit-discard' };
+      if (getUses(name).length) return { status: 'retained', name, reason: 'active-use' };
+      const reason = eligibility(ref); if (reason) return { status: 'retained', name, reason };
+      const bundleReason = bundleEligibility(state, ref);
+      if (bundleReason) return { status: 'retained', name, reason: bundleReason };
+      if (!ref.remote && managedKind !== 'scratch') return { status: 'retained', name, reason: 'pending-upload' };
+      if (ref.state === 'restoring') return { status: 'retained', name, reason: 'restoration-pending' };
+      if (ref.state === 'evicted') {
+        try {
+          measure(name);
+          // A newly present file is a new local use/version, even at the same
+          // bytes. Retire the old eviction meaning under the writer lock.
+          ref.state = 'discarded'; save(state);
+          return { status: 'retained', name, reason: 'local-version-changed', bytes: 0 };
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+          return { status: 'retained', name, reason: 'already-evicted', bytes: 0 };
+        }
+      }
+      // Verify the entire exact bundle before deleting even one member.
+      let bundleBytes = 0;
+      for (const file of ref.bundle?.files ?? []) {
+        if (getUses(file.name).length) return { status: 'retained', name, reason: 'active-use' };
+        bundleBytes += (await verified({ ...file, remote: { id: file.id, sha256: file.sha256 } })).length;
+        if (bundleBytes > 80 * 1024 * 1024) throw new Error('bundle-too-large');
+      }
+      // Network waits may have admitted a rewrite, pin or explicit discard.
+      state = load(); const current = state.files.find(f => f.name === name);
+      if (getDiscards().has(name)) return { status: 'retained', name, reason: 'explicit-discard' };
+      if (!current || current.localVersion !== localVersion || eligibility(current) || bundleEligibility(state, current) || JSON.stringify(current.bundle) !== JSON.stringify(ref.bundle))
+        return { status: 'retained', name, reason: 'requirements-changed' };
+      let local;
+      try { local = measure(name); }
+      catch (error) {
+        if (error.code !== 'ENOENT' || current.state !== 'evicting') throw error;
+        // A crash may have happened after unlink but before receipt/result.
+        // Never infer reclaimed bytes from absence, and never replay discard.
+        current.state = 'evicted'; save(state);
+        return { status: 'retained', name, bytes: 0, reason: 'interrupted-unlink-unmeasured', localVersion };
+      }
+      if (local.signature !== current.signature || local.sha256 !== current.sha256) return { status: 'retained', name, reason: 'local-version-changed' };
+      // Persist BEFORE unlink: a restart at either boundary must not report a
+      // cloud discard. Identity checks still distinguish a later rewrite.
+      current.state = 'evicting'; save(state);
+      const check = measure(name);
+      if (check.signature !== local.signature || check.sha256 !== local.sha256) return { status: 'retained', name, reason: 'local-version-changed' };
+      try { unlink(pathFor(name)); }
+      catch (error) { return { status: 'failed', name, localVersion, bytes: 0, reason: 'unlink-failed', error: error.message }; }
+      reclaimed = { status: 'reclaimed', name, bytes: local.size, localVersion };
+      current.state = 'evicted'; save(state);
+      return { status: 'reclaimed', name, bytes: local.size, localVersion };
+    } catch (error) { return reclaimed ? { ...reclaimed, incomplete: true, reason: error.message } : { status: 'retained', name, reason: error.message }; }
+  };
+  const discard = (name, remoteId = null) => {
+    const state = load(), ref = state.files.find(f => f.name === name);
+    if (ref && (!remoteId || ref.remote?.id === remoteId)) { ref.state = 'discarded'; save(state); }
+  };
+  /** Missing previously evicted files are not discards, even if the current
+   * inventory changed: this place never measured holding that newer remote.
+   * Existing changed files invalidate the receipt before a later deletion. */
+  const absences = (stored, discards = new Set()) => {
+    const state = load(), names = new Set(); let changed = false;
+    for (const ref of state.files) {
+      if (discards.has(ref.name) || ref.state === 'discarded') continue;
+      try {
+        const local = measure(ref.name);
+        if (local.sha256 !== ref.sha256 || (ref.state !== 'restoring' && local.signature !== ref.signature)) { ref.state = 'discarded'; changed = true; }
+      } catch (e) {
+        if (e.code === 'ENOENT' && ['evicting', 'evicted', 'restoring'].includes(ref.state)) names.add(ref.name);
+      }
+    }
+    if (changed) save(state);
+    return names;
+  };
+  /** Restore full bundles before the next consumer. Never overwrite a rewrite.
+   * All remote bytes are verified first; partial writes remain retryable. */
+  const restore = async (discards = new Set()) => {
+    if (managedKind) throw new Error('managed-source-is-not-an-output-cache');
+    const state = load(), restored = [];
+    for (const original of state.files) {
+      const ref = load().files.find(f => f.name === original.name);
+      if (!ref || !['evicting', 'evicted', 'restoring'].includes(ref.state) || discards.has(ref.name)) continue;
+      try {
+        const local = measure(ref.name);
+        // A later rewrite belongs to the writer; invalidate the old receipt.
+        if (local.sha256 !== ref.sha256 || (ref.state !== 'restoring' && local.signature !== ref.signature)) {
+          const latest = load(), current = latest.files.find(f => f.name === ref.name);
+          if (current?.localVersion === ref.localVersion) { current.state = 'discarded'; save(latest); }
+          continue;
+        }
+      } catch (e) { if (e.code !== 'ENOENT') throw e; }
+      const bundle = ref.bundle?.files;
+      if (!bundle?.length) throw new Error('bundle-unknown');
+      if (bundle.some(f => discards.has(f.name))) throw new Error('bundle-explicitly-discarded');
+      const files = []; let total = 0;
+      for (const file of bundle) {
+        const bytes = await verified({ ...file, remote: { id: file.id, sha256: file.sha256 } });
+        total += bytes.length;
+        if (total > 80 * 1024 * 1024) throw new Error('bundle-too-large');
+        files.push({ ...file, bytes });
+      }
+      const writeState = load(), writing = writeState.files.find(f => f.name === ref.name);
+      if (files.some(f => getDiscards().has(f.name)) || writing?.state === 'discarded') throw new Error('bundle-explicitly-discarded');
+      if (writing?.localVersion !== ref.localVersion) throw new Error('local-version-changed');
+      for (const file of files) {
+        const member = writeState.files.find(f => f.name === file.name);
+        try {
+          const local = measure(file.name);
+          if (local.sha256 !== file.sha256 || (member && member.state !== 'restoring' && member.signature !== local.signature)) throw new Error('local-version-changed');
+        } catch (e) { if (e.code !== 'ENOENT') throw e; }
+      }
+      // A separate intent distinguishes our partially restored bytes from a
+      // later same-content rewrite of an ordinary evicted version.
+      for (const file of files) {
+        const member = writeState.files.find(f => f.name === file.name);
+        if (member && ['evicting', 'evicted'].includes(member.state) && member.sha256 === file.sha256 && member.remote?.id === file.id) member.state = 'restoring';
+      }
+      save(writeState);
+      for (const file of files) {
+        const recorded = load().files.find(f => f.name === file.name);
+        if (recorded && (recorded.state === 'discarded' || recorded.sha256 !== file.sha256 || recorded.remote?.id !== file.id)) throw new Error('local-version-changed');
+        // A newer local version is never replaced with the old producer.
+        try { if (measure(file.name).sha256 !== file.sha256) throw new Error('local-version-changed'); continue; }
+        catch (e) { if (e.code !== 'ENOENT') throw e; }
+        const relative = `.flowviant/artifacts/${file.name}`;
+        if (!ensureRealSubdir(placeDir, dirname(relative))) throw new Error('unsafe-parent');
+        const target = join(placeDir, relative), tmp = `${target}.${randomUUID()}.tmp`;
+        try {
+          const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+          try { writeFileSync(fd, file.bytes); fsyncSync(fd); } finally { closeSync(fd); }
+          // link is exclusive: a racing writer wins; rename would overwrite it.
+          linkSync(tmp, target);
+          const parent = openSync(dirname(target), constants.O_RDONLY | constants.O_NOFOLLOW);
+          try { fsyncSync(parent); } finally { closeSync(parent); }
+        } finally { rmSync(tmp, { force: true }); }
+        restored.push(file.name);
+      }
+      // Keep the durable eviction meaning until the full bundle is restored.
+      const latest = load(), current = latest.files.find(f => f.name === ref.name);
+      if (current?.localVersion !== ref.localVersion || current.state === 'discarded') throw new Error('requirements-changed');
+      for (const file of files) {
+        const owned = latest.files.find(f => f.name === file.name && f.remote?.id === file.id && f.sha256 === file.sha256);
+        if (owned && owned.state !== 'discarded') { owned.state = 'local'; owned.signature = measure(file.name).signature; owned.uses = null; }
+      }
+      save(latest);
+    }
+    return restored;
+  };
+  return { record, recordManaged, verifyRemote: verified, prepareEviction, trackUpload, requirements, evict, restore, discard, absences, records: () => load().files, measure };
+}

package/bin/lib/artifactContracts.mjs

@@ -158,7 +158,54 @@ export const LOOK_HEADLESS = `${NO_WINDOW} To look at your page, screenshot it
  * so it posts to `parent` with `'*'`; the app accepts only its own frame's
  * messages. A page with no handshake (every 0.105.0 bundle) is still viewed;
  * it is just never offered a Download .glb.
+ *
+ * THE MANIFEST AND THE POSTER (2026-10-25, the owner's `Output Viewer Frame`;
+ * decision record `2026-10-25-flowviant-draws-standard-outputs`). Flowviant
+ * draws the exported GLB in its own viewer, and every control over it, so the
+ * page becomes a full-bleed canvas and its folder gains `view.json`, the
+ * manifest the web reads when present (packages/shared/src/modelViewer.ts —
+ * its literal here is `MODEL_VIEW_MANIFEST`, held to that schema by
+ * agentTaskKinds.test.mjs). It uploads on the general rule — an allowlisted
+ * type the turn changed is prepared and sent (intermediateArtifacts.mjs) — so
+ * only these words had been keeping it out. It proves no delivery: the page
+ * and its measured export still do.
+ *
+ * THE POSTER IS THE DAEMON'S RENDER OF THE PAGE (0.125.21). These words first
+ * asked the agent to screenshot its own `poster.png`, the still a list or a
+ * nested kit shows without loading a GLB; but a Claude model card cannot run
+ * Chrome under its fenced shell, and the daemon already renders every HTML
+ * artifact it uploads (artifactPreview.mjs `renderDesignPreview`), which the
+ * server stores as that artifact's preview. So the page's default view IS the
+ * poster, and the contract asks for that view instead: the whole model,
+ * full-bleed, nothing over it, standing within the render's few seconds.
+ * "poster" stays optional in the shape: a poster.png an agent already has
+ * still ships on the same general rule.
  */
+export const MODEL_VIEW_MANIFEST = `{
+  "kind": "map",
+  "title": "Street and metro map",
+  "entry": "street-metro-map/index.glb",
+  "poster": "street-metro-map/poster.png",
+  "view": {
+    "units": { "metre": 1, "unit": "m" },
+    "upAxis": "Y",
+    "front": "+Z",
+    "defaultView": "overview",
+    "views": [
+      { "id": "overview", "label": "Overview", "group": "overview", "direction": "iso" },
+      { "id": "plan", "label": "Plan", "group": "overview", "direction": "top" },
+      { "id": "konbini", "label": "Konbini", "group": "spot", "area": "Shops", "direction": "front", "part": "konbini" },
+      { "id": "north-platform", "label": "North platform", "group": "spot", "area": "Station",
+        "camera": { "position": [42, 6, -18], "target": [42, 1, -4] } }
+    ],
+    "layers": [
+      { "id": "konbini", "label": "Konbini", "part": "konbini" },
+      { "id": "station-platforms", "label": "Station platforms", "part": "station-platforms" }
+    ]
+  },
+  "parts": ["konbini", "station-platforms"]
+}`;
+
 export const SYSTEM_AGENT_MODEL = `You are the human's own Claude, working one 3D MODEL card in a git worktree of
 their repository. Nobody is watching this run. You have the repo and the tools
 TOOLS ON THIS CARD names below — no board, no chat.
@@ -177,8 +224,9 @@ WHAT TO DO:
 
 2. Write ONE viewer, .flowviant/artifacts/<kebab-name>/index.html — a short
    kebab-case name for what it is (for example
-   .flowviant/artifacts/reading-chair/index.html). Keep the viewer self-contained;
-   do not add scripts or notes in its folder. Flowviant materializes index.glb
+   .flowviant/artifacts/reading-chair/index.html). Keep the viewer self-contained:
+   beside it, its folder holds only the view.json below (and a poster.png, if
+   you already have one), never scripts or notes. Flowviant materializes index.glb
    beside this exact page before completing the card, through the handler below.
    Keep original generated texture PNGs elsewhere under .flowviant/artifacts/;
    preserve their bytes and material mapping. The page BUILDS
@@ -186,6 +234,9 @@ WHAT TO DO:
    - three.js as ES modules from cdn.jsdelivr.net/npm, through an import map
      for "three" and "three/addons/"; orbit controls, lights and a neutral
      ground. Nothing else loads from the network, and nothing can be sent.
+   - the page is the scene and nothing else: a full-bleed canvas, with no
+     title, panel, legend, button or text over the model. Flowviant draws
+     every control.
    - the model is ONE THREE.Group named for what it is, built from three.js
      geometry (lathe, extrude, tube, box and the rest, one mesh per part),
      with MeshStandardMaterial only. Colour, roughness and metalness are
@@ -228,6 +279,40 @@ WHAT TO DO:
 
    ${LOOK_HEADLESS}
 
+   THE PAGE'S DEFAULT VIEW IS THE POSTER FLOWVIANT SHOWS. Flowviant renders
+   this page itself when it uploads it, and that still is the model's picture
+   wherever the model is listed. So the page opens on the default view below:
+   the whole model, fitted full-bleed to the frame, with nothing over it — no
+   loading text, label or overlay — standing within a few seconds of load.
+   Take no poster yourself; a poster.png you already have may sit in the
+   folder, named in "poster" below.
+
+   Then write <kebab-name>/view.json — how Flowviant's viewer frames the
+   model, exactly in this shape (a map's, with every field):
+
+${MODEL_VIEW_MANIFEST.replace(/^/gm, '     ')}
+
+   "kind" is "model" for one object, "map" for a scene that places several
+   kits. "entry" is a path under .flowviant/artifacts/: this folder's
+   index.glb. "poster" is optional: name this folder's poster.png only when
+   the folder holds one; otherwise leave the field out. Declare "units"
+   once, as the size of the scene's unit in metres —
+   { "stud": 0.28, "unit": "m" } for a scene built in studs — and never
+   write units or any other text into the scene; Flowviant draws the scale
+   bar. "upAxis" is "Y" (three.js is Y-up); "front" is the side the model
+   faces: "+X", "-X", "+Z" or "-Z". "views": up to three "overview" views,
+   "defaultView" naming one; a map adds named "spot" views, each grouped
+   under its "area". A view looks from a "direction" ("iso", "top",
+   "front", "side" or "back") fitted to the whole scene or to one "part", or
+   from a "camera" position and target in scene units. "layers", for a map:
+   one per kit, its "part" the kit's scene node name exactly. "parts": every
+   node you name in code (.name, which GLTFExporter keeps); each "part"
+   above is one of them, spelled the same. A single model has no spots and
+   no layers: Flowviant gives it Display and Turntable. A label or area is a
+   few words, 40 characters at most; at most 40 views, 60 layers and 200
+   parts — a manifest past any limit is not read. The page's opening view
+   is the one "defaultView" names, so the poster and the viewer agree.
+
 ${ARTIFACT_CONTRACT_TAIL({
   ask: `If you cannot model it without a DECISION only a person can make — which of
    two directions, what size or style, which asset it stands beside — STOP AND

package/bin/lib/artifactIteration.mjs

@@ -1,4 +1,5 @@
 /** Explicit iteration relationships, plus measured local deletions. No model runs here. */
+import { REFERENCE_CAPTURE_FILE } from './referenceCaptureProtocol.mjs';
 import { constants, openSync, closeSync, fstatSync, readFileSync, lstatSync, unlinkSync, realpathSync, writeFileSync, renameSync, rmSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -117,7 +118,7 @@ export function seenArtifacts(record, stored, present, bornAt = null) {
   let seen = record;
   if (!seen) {
     const since = Number.isFinite(bornAt)
-      ? stored.filter((a) => storedAt(a) >= bornAt).map((a) => a.name) : [];
+      ? stored.filter((a) => storedAt(a) >= bornAt && !REFERENCE_CAPTURE_FILE.test(a.name)).map((a) => a.name) : [];
     seen = since.some((n) => present.has(n)) ? new Set(since) : new Set();
   }
   return new Set([...seen, ...present].filter((n) => names.has(n) || present.has(n)));
@@ -144,7 +145,7 @@ export function deletedArtifacts(placeDir, before) {
   // Only names this place held are candidates: this turn's snapshot and the
   // place's record (`before.seen`). Normalize live names before probing: a
   // draft+1.md is stored as draft_1.md and is not an absent retained file.
-  const candidates = new Set([...(before?.keys() ?? []), ...(before?.seen ?? [])]);
+  const candidates = new Set([...(before?.keys() ?? []), ...(before?.seen ?? [])].filter(name => !before?.evicted?.has(artifactStoredName(name))));
   const live = presentArtifacts(placeDir);
   if (!live) {
     return flowviantParentState(placeDir) === 'dir' && realDirState(join(placeDir, ARTIFACT_DIR)) === 'none'

package/bin/lib/artifactPolicy.mjs

@@ -13,13 +13,17 @@ export const ARTIFACT_POLICY_SOURCE = 'packages/shared/src/schemas/artifact.sche
 
 /** Per text file and ordinary binary artifact. */
 export const ARTIFACT_MAX_BYTES = 2097152;
+/** Above this size, upload binary bytes as a stream rather than multipart. */
+export const ARTIFACT_MULTIPART_MAX_BYTES = 20971520;
 /** Binary model buffers (the extensions below). */
-export const ARTIFACT_BINARY_MODEL_MAX_BYTES = 20971520;
+export const ARTIFACT_BINARY_MODEL_MAX_BYTES = 33554432;
 export const ARTIFACT_BINARY_MODEL_EXTS = ['glb', 'bin', 'png', 'webp'];
 /** Per Terminal session, and the per-turn discovery window. */
 export const ARTIFACT_MAX_PER_OWNER = 40;
 /** Per agent — the server keeps as many for one agent. */
 export const ARTIFACT_MAX_PER_AGENT = 400;
+/** Selected result inputs, including exact embedded model textures. */
+export const RESULT_INPUT_MAX_FILES = 256;
 
 /** Extension → the one mime the server serves it under; `text` is scrubbed. */
 export const ARTIFACT_TYPES = {