flowviant 0.125.24 → 0.125.26

package/README.md

@@ -328,7 +328,19 @@ pinned because [npm 12 removed shrinkwrap support](https://github.com/npm/cli/bl
 and omits it from tarballs; npm 12 consumers also ignore that lockfile.
 No sibling repository or separate app deploy key is required.
 
-### Staged agent worktree startup and restart protection (0.125.24)
+### UI review evidence retention (0.125.26)
+
+Review reports and screenshots stay attached to their run without filling the
+same-agent producer receipt. Legacy receipts migrate on retry without deleting
+evidence. Identical captures within one review share a file and retain their
+scenario, viewport, phase and hash references. Producer receipts use the shared
+agent storage limit and report cumulative overflow before upload.
+
+0.125.26 includes the npm dependency shrinkwrap with the pinned npm 11
+publisher. The earlier 0.125.25 npm package contains the same runtime fix but
+was published by npm 12 without that lockfile.
+
+### Agent worktree startup and restart protection (0.125.24)
 
 Card launches verify their exact Git worktree and repository before starting,
 including after tool preparation. Fresh empty leftover directories are
@@ -338,7 +350,9 @@ retirement and manual fast-forwarding honor live CLI PID/start-time receipts
 across daemon restarts. Existing begun work still needs its worktree, surviving
 branch or published recovery copy; restarting the daemon alone does not reset
 a stuck board agent. No new wire floor or database migration is required.
-This version is staged, not published or installed.
+Published on npm and the standalone download channel on 2026-10-26. Running
+daemons receive the version signal from the app and update when idle, unless
+automatic updates are disabled.
 
 ### Staged artifact handoff revisions (0.125.18)
 

package/bin/lib/artifactReporter.mjs

@@ -297,7 +297,7 @@ export function createArtifactReporter({
 
   /** Upload what this turn changed in `placeDir`. Resolves to the number of
    *  bodies SENT this call (delivered or held), for the tests and the log. */
-  const report = async ({ placeDir, before, sessionId, agentId, turnId, idle = false, requireStored = false, includeNames = null, requiredOutputs = null, referenceCapture = false }) => {
+  const report = async ({ placeDir, before, sessionId, agentId, turnId, idle = false, requireStored = false, includeNames = null, requiredOutputs = null, evidenceNames = [], referenceCapture = false }) => {
     if (!placeDir || (!sessionId && !agentId)) return 0;
     const changes = iterationChanges(placeDir, before);
     const protectedNames = imageRevisionProtection(before?.stored, before?.imageRevision);
@@ -334,9 +334,13 @@ export function createArtifactReporter({
     // discovery window. Re-walk safely, then verify the built bytes against
     // the prepared version before sending anything to storage.
     const discovered = idle ? [] : listChanged(placeDir, before);
-    const entries = required.size
-      ? [...scanArtifacts(placeDir, { all: true, includeNames: new Set(required.keys()) }),
-        ...discovered.filter(e => !artifactTypeFor(e.name))] // unsupported files still report by name
+    // Verification evidence is explicitly selected too, but never becomes a
+    // required producer input. Multiple review attempts can exceed the normal
+    // discovery window; retain their reports and captures on the same turn.
+    const selected = new Set([...required.keys(), ...evidenceNames]);
+    const entries = selected.size
+      ? [...scanArtifacts(placeDir, { all: true, includeNames: selected }),
+        ...discovered.filter(e => !selected.has(e.name) && (!required.size || !artifactTypeFor(e.name)))]
       : discovered;
     const changed = idle ? [] : entries.filter((e) =>
       !removing.has(artifactStoredName(e.name)) && (!includeNames || includeNames.has(e.name)));

package/bin/lib/intermediateArtifacts.mjs

@@ -11,6 +11,7 @@ import { ensureRealSubdir, realDirState } from './ownedDirs.mjs';
 import { scrub, secretIn } from './uplinkScrub.mjs';
 import { exportModelPage } from './modelExport.mjs';
 import { usableModelGlb } from './modelExportProtocol.mjs';
+import { uiReviewEvidenceNames } from './uiReviewArtifacts.mjs';
 
 const hash = bytes => createHash('sha256').update(bytes).digest('hex');
 const safeName = name => typeof name === 'string' && name.length <= 400 &&
@@ -18,6 +19,8 @@ const safeName = name => typeof name === 'string' && name.length <= 400 &&
 const copyPath = (sha256, name) => `.flowviant/artifacts/.handoff/${sha256}/${name}`;
 const taskOf = job => job.task?.id ?? job.repositoryTaskId ?? null;
 
+export class IntermediateArtifactCapacityError extends Error {}
+
 export function readIntermediateFile(wt, relative, max = ARTIFACT_BINARY_MODEL_MAX_BYTES) {
   if (!safeName(relative) || !relative.startsWith('.flowviant/artifacts/')) throw new Error('Unsafe intermediate artifact path.');
   const parts = dirname(relative).split('/');
@@ -99,9 +102,22 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
     let state;
     try { state = JSON.parse(readFileSync(path, 'utf8')); }
     catch (error) { if (error.code === 'ENOENT') return { version: 1, agentId, files: [], pending: null }; throw new Error('The intermediate artifact receipt could not be read. Restore it before retrying.'); }
-    if (state.version !== 1 || state.agentId !== agentId || !Array.isArray(state.files) || state.files.length > 160 ||
+    if (state.version !== 1 || state.agentId !== agentId || !Array.isArray(state.files) || state.files.length > ARTIFACT_MAX_PER_AGENT ||
         state.files.some(f => !safeName(f.name) || f.path !== copyPath(f.sha256, f.name) || !/^[a-f0-9]{64}$/.test(f.sha256)))
       throw new Error('The intermediate artifact receipt has invalid identity or paths.');
+    // Older daemons put verification reports and captures in this producer
+    // receipt. Migrate the references, never delete the original evidence.
+    const evidence = uiReviewEvidenceNames(state.files, ref => {
+      let bytes;
+      try { bytes = readIntermediateFile(wt, ref.path, artifactMaxBytesFor(ref.name)); }
+      catch (error) {
+        if (error.code !== 'ENOENT' || realDirState(privateFiles) !== 'dir') throw error;
+        bytes = readRegular(join(privateFiles, ref.sha256), artifactMaxBytesFor(ref.name));
+      }
+      if (hash(bytes) !== ref.sha256) throw new Error('Review receipt hash mismatch');
+      return bytes;
+    });
+    state.files = state.files.filter(ref => !evidence.has(ref.name));
     return state;
   };
   const save = state => {
@@ -145,7 +161,12 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
     const state = load(), taskId = taskOf(job);
     const identity = { agentId, taskId, turnId, taskKind };
     const standing = scanArtifacts(wt, { all: true });
-    let changed = changedArtifacts(before, standing);
+    const evidence = uiReviewEvidenceNames(standing, entry => readIntermediateFile(wt, `.flowviant/artifacts/${entry.name}`, artifactMaxBytesFor(entry.name)));
+    const changed = changedArtifacts(before, standing);
+    const evidenceNames = [...new Set([...changed.map(entry => entry.name), ...(state.pending?.sources ?? []).map(ref => ref.name)].filter(name => evidence.has(name)))];
+    let producerChanges = changed.filter(entry => !evidence.has(entry.name));
+    if (state.pending && !state.pending.recovery)
+      state.pending.sources = state.pending.sources.filter(ref => !evidence.has(ref.name));
     // Failed export/storage retries are tied to a card and exact source hash.
     // A changed page is a new version; it never reuses a previous GLB receipt.
     // A source the agent's iteration declaration discards or replaces is the
@@ -155,11 +176,11 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
       throw new Error('An exact producer recovery is pending. Retry that producer before starting different work.');
     if (pending?.recovery) {
       identity.recoveredFromTurnId = pending.recoverySourceTurnId ?? pending.turnId;
-      changed = changed.filter(e => pending.sources.some(s => s.name === e.name));
+      producerChanges = producerChanges.filter(e => pending.sources.some(s => s.name === e.name));
     }
     const discarded = pending ? declaredDiscards(wt) : new Set();
     if (pending) for (const ref of pending.sources) {
-      if (!pending.recovery && (changed.some(e => e.name === ref.name) || discarded.has(artifactStoredName(ref.name)))) continue;
+      if (!pending.recovery && (producerChanges.some(e => e.name === ref.name) || discarded.has(artifactStoredName(ref.name)))) continue;
       const entry = standing.find(e => e.name === ref.name);
       let bytes;
       try { bytes = readIntermediateFile(wt, `.flowviant/artifacts/${ref.name}`, artifactMaxBytesFor(ref.name)); }
@@ -167,16 +188,16 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
       if (hash(bytes) !== ref.sha256)
         throw new Error(`Required intermediate output ${ref.name} is missing or changed since the failed handoff. Restore it or revise the producer explicitly, then retry.`);
       if (!entry) throw new Error(`Required intermediate output ${ref.name} is outside the safe artifact walk (non-hidden paths with at most ${ARTIFACT_MAX_DEPTH} directories). Move it to a supported artifact path and retry this producer.`);
-      if (!changed.some(e => e.name === entry.name)) changed.push(entry);
+      if (!producerChanges.some(e => e.name === entry.name)) producerChanges.push(entry);
     }
-    if (taskKind === 'model' && !changed.some(e => /\.html?$/i.test(e.name)) && (job.kind !== 'task' || job.redo === true) && taskId) {
+    if (taskKind === 'model' && !producerChanges.some(e => /\.html?$/i.test(e.name)) && (job.kind !== 'task' || job.redo === true) && taskId) {
       for (const ref of state.files.filter(f => f.taskId === taskId && f.taskKind === 'model' && /\.html?$/i.test(f.name))) {
         const entry = standing.find(e => e.name === ref.name);
-        if (entry) changed.push(entry);
+        if (entry) producerChanges.push(entry);
       }
     }
-    const pages = taskKind === 'model' ? changed.filter(e => /\.html?$/i.test(e.name)) : [];
-    const outputs = changed.filter(e => artifactTypeFor(e.name));
+    const pages = taskKind === 'model' ? producerChanges.filter(e => /\.html?$/i.test(e.name)) : [];
+    const outputs = producerChanges.filter(e => artifactTypeFor(e.name));
     state.pending = { taskId, turnId, ...(pending?.recovery ? { recovery: true, recoverySourceTurnId: identity.recoveredFromTurnId } : {}), sources: outputs.map(e => ({ name: e.name, sha256: hash(readIntermediateFile(wt, `.flowviant/artifacts/${e.name}`, artifactMaxBytesFor(e.name))) })), exports: pending?.exports ?? [] };
     save(state);
     const exports = [];
@@ -207,7 +228,12 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
     // would prune one of this very handoff's files and then falsely claim
     // complete delivery.
     if (outputs.length > ARTIFACT_MAX_PER_AGENT)
-      throw new Error(`This producer requires ${outputs.length} output files including model exports; artifact storage retains at most ${ARTIFACT_MAX_PER_AGENT} files per agent. Narrow this producer's output set before retrying; its handoff is unfinished.`);
+      throw new IntermediateArtifactCapacityError(`This producer requires ${outputs.length} output files including model exports; artifact storage retains at most ${ARTIFACT_MAX_PER_AGENT} files per agent. Narrow this producer's output set before retrying; its handoff is unfinished.`);
+    const retainedNames = new Set(state.files.map(ref => ref.name));
+    const newNames = outputs.filter(entry => !retainedNames.has(entry.name));
+    const total = retainedNames.size + newNames.length;
+    if (total > ARTIFACT_MAX_PER_AGENT)
+      throw new IntermediateArtifactCapacityError(`The intermediate artifact receipt has ${retainedNames.size} retained producer files plus ${newNames.length} new files (${total} total); artifact storage retains at most ${ARTIFACT_MAX_PER_AGENT} files per agent. Narrow the producer outputs before retrying; its handoff is unfinished.`);
     const textures = [...state.files.flatMap(f => [...(/\.png$/i.test(f.name) ? [f] : []), ...(f.model?.textureInputs ?? [])]),
       ...outputs.filter(e => /\.png$/i.test(e.name)).map(e => snapshot(wt, e, identity, retain))]
       .map(({ name, path, sha256, taskId, turnId, agentId, taskKind }) => ({ name, path, sha256, taskId, turnId, agentId, taskKind }));
@@ -225,10 +251,9 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
     // Retry all prepared files even if their mtime did not change this turn.
     const uploadBefore = Object.assign(new Map(before), before);
     for (const ref of files) uploadBefore.delete(ref.name);
-    return { modelExports: exports, requiredOutputs: files.map(({ name, sha256 }) => ({ name, sha256 })), uploadBefore, commit: () => {
+    return { modelExports: exports, requiredOutputs: files.map(({ name, sha256 }) => ({ name, sha256 })), evidenceNames, uploadBefore, commit: () => {
       const byName = new Map(state.files.map(f => [f.name, f]));
       for (const ref of files) byName.set(ref.name, ref);
-      if (byName.size > 160) throw new Error('The intermediate artifact receipt exceeds 160 files. Narrow the outputs before retrying.');
       save({ ...state, files: [...byName.values()], pending: null });
     } };
   };

package/bin/lib/uiReview.mjs

@@ -157,7 +157,7 @@ export async function createUiReview({ wt, signal, capture = captureLocalReview,
     const stop = () => runController.abort();
     controller.signal.addEventListener('abort', stop, { once: true });
     const timer = setTimeout(stop, timeoutMs);
-    const record = { status: 'unavailable', before: reviewSourceState(wt), basis: reviewDiagnostic(input.basis), fixture: reviewDiagnostic(input.fixture.description),
+    const record = { purpose: 'ui-review', status: 'unavailable', before: reviewSourceState(wt), basis: reviewDiagnostic(input.basis), fixture: reviewDiagnostic(input.fixture.description),
       requestedScenarios: input.scenarios.map(s => ({ name: reviewDiagnostic(s.name), path: reviewDiagnostic(s.path), actions: s.actions.map(a => ({ type: a.type, ...(a.selector ? { selector: reviewDiagnostic(a.selector) } : {}) })) })),
       scenarios: [], consoleErrors: [], failedRequests: [] };
     let child, proxy, scratch, artifactDir, untrack;

package/bin/lib/uiReviewArtifacts.mjs

@@ -0,0 +1,30 @@
+/** Identify only files explicitly owned by a measured UI-review report.
+ * Legacy reports predate the purpose marker. A folder prefix alone never
+ * exempts producer data from handoff; unknown/unreadable reports exempt none.
+ * read receives the entry so callers can use immutable receipt bytes. */
+export function uiReviewEvidenceNames(entries, read) {
+  const evidence = new Set();
+  const byName = new Map(entries.map(entry => [entry.name, entry]));
+  for (const entry of entries) {
+    if (!/^ui-review-[a-f0-9]{8}-[a-f0-9]{3}\/report\.json$/.test(entry.name)) continue;
+    try {
+      const report = JSON.parse(read(entry));
+      const folder = entry.name.slice(0, -'/report.json'.length);
+      if (report.folder !== `.flowviant/artifacts/${folder}` ||
+          report.artifact !== `${report.folder}/report.json` ||
+          !report.before || !report.after || !Array.isArray(report.requestedScenarios) || !Array.isArray(report.scenarios) ||
+          (report.purpose !== undefined && report.purpose !== 'ui-review') ||
+          (report.screenshots !== undefined && !Array.isArray(report.screenshots))) continue;
+      const screenshots = report.screenshots ?? [];
+      if (screenshots.some(name => typeof name !== 'string' || !/^(desktop|mobile)-\d+-(initial|final|failure)\.png$/.test(name))) continue;
+      evidence.add(entry.name);
+      for (const name of screenshots) evidence.add(`${folder}/${name}`);
+      const delivery = byName.get(`${folder}/delivery-state.json`);
+      if (delivery) {
+        const state = JSON.parse(read(delivery));
+        if (state.finalState && typeof state.latestMatches === 'boolean' && Array.isArray(state.imageInputs)) evidence.add(delivery.name);
+      }
+    } catch { /* Unknown evidence remains an ordinary producer output. */ }
+  }
+  return evidence;
+}

package/bin/lib/uiReviewBrowser.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir, platform } from 'node:os';
@@ -39,6 +40,7 @@ export const LOCAL_REVIEW_BOOTSTRAP = `for (const name of ['RTCPeerConnection',
 export async function captureLocalReview({ origin, scenarios, artifactDir, signal,
   browser = resolveBrowser(), spawnImpl = spawn, timeoutMs = UI_REVIEW_TIMEOUT_MS, onChild = () => () => {} }) {
   const result = { status: 'unavailable', scenarios: [], consoleErrors: [], failedRequests: [], screenshots: [] };
+  const capturesByHash = new Map();
   if (!browser) return { ...result, reason: 'No Chrome/Chromium/Edge found; no browser checks ran.' };
   if (browser.viaWindows) return { ...result, reason: 'WSL Windows interop cannot carry the scoped DevTools pipe.' };
   if (signal?.aborted) return { ...result, reason: 'Review was cancelled before launch.' };
@@ -158,9 +160,19 @@ export async function captureLocalReview({ origin, scenarios, artifactDir, signa
             const shot = await send('Page.captureScreenshot', { format: 'png' });
             const bytes = Buffer.from(shot.data ?? '', 'base64');
             if (!bytes.length || bytes.length > 2 * 1024 * 1024) throw new Error('Screenshot was empty or exceeded the retained artifact size.');
-            const name = `${viewport.name}-${index + 1}-${phase}.png`;
-            writeFileSync(join(artifactDir, name), bytes, { flag: 'wx' });
-            row.screenshots.push(name); result.screenshots.push(name);
+            const sha256 = createHash('sha256').update(bytes).digest('hex');
+            let name = capturesByHash.get(sha256);
+            if (!name) {
+              name = `${viewport.name}-${index + 1}-${phase}.png`;
+              writeFileSync(join(artifactDir, name), bytes, { flag: 'wx' });
+              capturesByHash.set(sha256, name);
+              result.screenshots.push(name);
+            }
+            // Each capture keeps its viewport/scenario/phase even when its
+            // exact pixels already have a retained file in this review run.
+            row.captures ??= [];
+            row.captures.push({ phase, name, sha256 });
+            if (!row.screenshots.includes(name)) row.screenshots.push(name);
           };
           captureFailure = () => screenshot('failure');
           await screenshot('initial');

package/bin/lib/workAgentTurnExecution.mjs

@@ -67,7 +67,7 @@ import { ORCHESTRATED_POSTURES, orchestratesPosture } from './orchestratorPrompt
 import { knownCodexModels } from './runtimeOfferings.mjs';
 import { codexSubagentsSafe } from './runtimeCodex.mjs';
 import { measuredRuntimeVersion } from './runtimeDetection.mjs';
-import { createIntermediateArtifacts } from './intermediateArtifacts.mjs';
+import { createIntermediateArtifacts, IntermediateArtifactCapacityError } from './intermediateArtifacts.mjs';
 import { createUiReview } from './uiReview.mjs';
 import { createVideoRender } from './videoRender.mjs';
 import { withUiReview, appendUiReviewEvidence } from './uiReviewTurn.mjs';
@@ -827,6 +827,9 @@ export function createAgentTurnExecution({
         try { intermediateDelivery = await intermediate.prepare({ job, turnId, taskKind, before: artifactsBefore, signal: setupController.signal }); }
         catch (error) {
           if (run.interrupted) throw error;
+          // A measured storage overflow must stop before sending a subset
+          // that could evict this producer's already retained inputs.
+          if (error instanceof IntermediateArtifactCapacityError) throw error;
           // The failed page still has its preview/files for repair. Reporting
           // those bytes cannot turn a failed export into a delivered card.
           try { await artifacts.report({ placeDir: wt, before: artifactsBefore, agentId, turnId, requireStored: kind.artifact != null }); }
@@ -835,7 +838,7 @@ export function createAgentTurnExecution({
         }
       }
       await artifacts.report({ placeDir: wt, before: intermediateDelivery?.uploadBefore ?? artifactsBefore, agentId, turnId,
-        requireStored: kind.artifact != null, requiredOutputs: intermediateDelivery?.requiredOutputs });
+        requireStored: kind.artifact != null, requiredOutputs: intermediateDelivery?.requiredOutputs, evidenceNames: intermediateDelivery?.evidenceNames });
     }
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.24",
+  "version": "0.125.26",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {