flowviant 0.125.17 → 0.125.18

package/README.md

@@ -318,6 +318,15 @@ 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 artifact handoff revisions (0.125.18)
+
+A failed handoff's retry drops every pending source the agent's
+`.flowviant/artifacts/.iteration.json` discards or replaces, instead of
+demanding the discarded file at its old bytes on every resume. A producer's
+required set is checked against the server's per-agent storage of 400 files
+(`ARTIFACT_MAX_PER_AGENT`) rather than a Terminal tab's 40. Both are daemon-side
+only; the API needs no floor. Published-latest remains unchanged until release.
+
 ### Staged agent queue context (0.125.17)
 
 The daemon now includes the API's versioned `queueContext` in task, human and

package/bin/lib/artifactIteration.mjs

@@ -23,6 +23,24 @@ const manifestText = (placeDir) => {
 const signature = (value) => value === null ? null : `${value.stamp}:${createHash('sha256').update(value.text).digest('hex')}`;
 export const iterationSignature = (placeDir) => signature(manifestText(placeDir));
 
+/**
+ * Every name the standing declaration discards or replaces, whenever it was
+ * written. A failed handoff's retry reads this (2026-10-23): the agent revised
+ * its outputs in a turn that did not deliver, and the retry kept demanding the
+ * discarded files at their old bytes on every resume. Unreadable or malformed
+ * is no discard; the reporter refuses a malformed declaration on its own.
+ */
+export function declaredDiscards(placeDir) {
+  const text = manifestText(placeDir);
+  if (text === null) return new Set();
+  try {
+    const value = JSON.parse(text.text);
+    const remove = Array.isArray(value?.remove) ? value.remove : [];
+    const replace = value?.replace && typeof value.replace === 'object' && !Array.isArray(value.replace) ? Object.keys(value.replace) : [];
+    return new Set([...remove, ...replace].filter(safeName));
+  } catch { return new Set(); }
+}
+
 export function iterationChanges(placeDir, before) {
   const text = manifestText(placeDir);
   if (text === null || signature(text) === before?.iterationSignature) return { remove: [], replace: {} };

package/bin/lib/artifactPolicy.mjs

@@ -16,8 +16,10 @@ export const ARTIFACT_MAX_BYTES = 2097152;
 /** Binary model buffers (the extensions below). */
 export const ARTIFACT_BINARY_MODEL_MAX_BYTES = 20971520;
 export const ARTIFACT_BINARY_MODEL_EXTS = ['glb', 'bin', 'png', 'webp'];
-/** Per session and per agent — the server keeps as many per owner. */
+/** 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;
 
 /** Extension → the one mime the server serves it under; `text` is scrubbed. */
 export const ARTIFACT_TYPES = {

package/bin/lib/intermediateArtifacts.mjs

@@ -4,8 +4,9 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readSync, renameSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { ARTIFACT_MAX_DEPTH, artifactTypeFor, artifactMaxBytesFor, changedArtifacts, scanArtifacts } from './artifacts.mjs';
-import { ARTIFACT_BINARY_MODEL_MAX_BYTES, ARTIFACT_MAX_PER_OWNER } from './artifactPolicy.mjs';
+import { ARTIFACT_MAX_DEPTH, artifactStoredName, artifactTypeFor, artifactMaxBytesFor, changedArtifacts, scanArtifacts } from './artifacts.mjs';
+import { ARTIFACT_BINARY_MODEL_MAX_BYTES, ARTIFACT_MAX_PER_AGENT } from './artifactPolicy.mjs';
+import { declaredDiscards } from './artifactIteration.mjs';
 import { ensureRealSubdir, realDirState } from './ownedDirs.mjs';
 import { scrub, secretIn } from './uplinkScrub.mjs';
 import { exportModelPage } from './modelExport.mjs';
@@ -147,9 +148,12 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
     const changed = changedArtifacts(before, standing);
     // 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
+    // explicit revision and leaves the retry set.
     const pending = state.pending?.taskId === taskId && taskId ? state.pending : null;
+    const discarded = pending ? declaredDiscards(wt) : new Set();
     if (pending) for (const ref of pending.sources) {
-      if (changed.some(e => e.name === ref.name)) continue;
+      if (changed.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)); }
@@ -192,11 +196,12 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
     state.pending.sources = outputs.map(e => ({ name: e.name,
       sha256: hash(readIntermediateFile(wt, `.flowviant/artifacts/${e.name}`, artifactMaxBytesFor(e.name))) }));
     save(state);
-    // The server retains 40 artifacts per owner. Discovery crowding is not a
-    // storage limit, but uploading a larger required set would prune one of
-    // this very handoff's files and then falsely claim complete delivery.
-    if (outputs.length > ARTIFACT_MAX_PER_OWNER)
-      throw new Error(`This producer requires ${outputs.length} output files including model exports; artifact storage retains at most ${ARTIFACT_MAX_PER_OWNER} files per agent. Narrow this producer's output set before retrying; its handoff is unfinished.`);
+    // The server retains ARTIFACT_MAX_PER_AGENT artifacts per agent. Discovery
+    // crowding is not a storage limit, but uploading a larger required set
+    // 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.`);
     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 }));

package/bin/lib/orchestratorPrompt.mjs

@@ -22,6 +22,19 @@ export const orchestratesPosture = (posture) => Object.hasOwn(ORCHESTRATED_POSTU
  */
 const SPLIT = `SPLIT INDEPENDENT WORK INTO NATIVE SUBAGENTS WITHOUT BEING ASKED. Before your first edit, list the card's parts in a short update. When two or more parts can proceed without waiting on each other, spawn one native in-process subagent for each independent part but one, and do that one yourself meanwhile. This holds however small the parts are; the person does not have to request it, and this contract is the authorization. Independent parts look like: several selected findings, separate files or areas (server and daemon, API and UI), tests written beside the code they cover, independent questions to investigate. A part that needs another part's result runs after that prerequisite, by you or by a child you start then. Stay solo only when the card has no independent parts, and if you keep an independent part yourself, say why in your update. Give each child a concrete title, prompt and kind (Backend/UI/Tests/Research…). Do not create extra branches or Flowviant agents. Use a native agent type that can call card_orchestrator MCP (Claude general-purpose); keep the work yourself if none can. Never give a child isolation or a different cwd: children share this card's worktree on this machine. After spawning, use describe_agent to report the kind and title you chose when its native role is generic.`;
 
+/**
+ * WRITE THE SHARED CODE FIRST (2026-10-22). Parts that depend on each other
+ * only through code they all use — a schema, a wire field, a signature — fell
+ * under "runs after that prerequisite" and ran in sequence, or a child started
+ * from a prose description of code a sibling had not written yet. Once the
+ * orchestrator commits that shared code, the parts no longer wait on each
+ * other: Next-Concept Modeling's coarse-to-fine move, where each finer level is
+ * filled in parallel from the coarser levels already decoded, never from a
+ * plan of them. A child asks rather than edits it, because its siblings build
+ * on it. Code cards only: a research child writes nothing.
+ */
+const SHARED_FIRST = `WRITE THE CODE THE PARTS SHARE BEFORE YOU SPLIT THEM. Parts often depend on each other only through code they all use: a type or schema, a migration, a wire field, a function or route signature, a component's props. When you list the card's parts, name that shared code too. Write it yourself first — the declarations, with stub bodies where an implementation belongs to a part — and commit it as its own commit before you spawn any child. The parts that waited only on it are now independent: split them as above. Name the shared files in each child's prompt so it builds on the committed code, not on a description of it, and tell it not to change them: a child that finds the shared code wrong or missing asks you with agent_question, and you change it yourself and tell every child building on it. Keep this step to what two or more parts actually use; a part's own internals stay with that part. When the parts share no code, skip it.`;
+
 const RESEARCH = `THIS IS A RESEARCH CARD, SO EVERY CHILD ONLY READS. A child works inside this card's research fence: the same read fence, web policy and working directory as you. It writes no file, edits nothing and commits nothing, and the gate refuses a child's write. Give each child one question or one set of sources, and ask it to return its findings with their sources (links or repository paths) and what it could not verify. You alone deliver the card: merge the children's findings, resolve or state their conflicts, write any requested document yourself, and keep the research contract's own stops, including an investigation's numbered-findings question and its wait for the person's selection.`;
 
 /** Each CLI's own spelling of a child's model and effort, as measured
@@ -118,7 +131,7 @@ export function orchestratorContract({ posture = 'build', taskType = null, runti
   return `CARD ORCHESTRATOR — this applies to this card's one CLI and worktree.
 You are the model the person chose and remain responsible for the card and its final JSON.
 When an agent queue snapshot is supplied, use it across resumed and fresh turns. Execute only the active card. A person's instruction keeps its stated scope across later cards; its recorded card is provenance, not an implicit target. Give each child a focused assignment with relevant prior findings, decisions and exact prerequisite references. Upcoming work never expands a child's assignment or the active card's product/write contract.
-${SPLIT}${taskType === 'tests' ? `\n${TESTS_SCOPE} Give every child this Tests scope explicitly.` : ''}${reads ? `\n${RESEARCH}` : ''}
+${SPLIT}${reads ? '' : `\n${SHARED_FIRST}`}${taskType === 'tests' ? `\n${TESTS_SCOPE} Give every child this Tests scope explicitly.` : ''}${reads ? `\n${RESEARCH}` : ''}
 ${childBrain({ runtime, model, effort })}
 
 The daemon gates every native spawn against this project's Turns at once pool, shared with its other turns. Claude children run in the background so you remain available for messages and their questions; Codex spawns are already asynchronous. A refused spawn with a waiting id has not started. Keep working yourself; do not wait for it. When notified of a free slot, retry its native spawn (the same or a reworded prompt) or its native follow-up; the slot is held for about a minute, then offered again later. Never bypass this gate with another CLI process. The orchestrator itself also holds a slot. If no slot becomes available, finish the work yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.17",
+  "version": "0.125.18",
   "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": {