flowviant 0.125.17 → 0.125.20

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';
@@ -32,7 +33,7 @@ function readRegular(path, max = ARTIFACT_BINARY_MODEL_MAX_BYTES) {
   try {
     const stat = fstatSync(fd);
     if (!stat.isFile()) throw new Error('Intermediate artifact is not a regular file.');
-    if (stat.size > max) throw new Error(`Intermediate artifact is ${stat.size} bytes; the per-file limit is ${max} bytes.`);
+    if (stat.size > max) throw new Error(`Intermediate artifact is ${stat.size} bytes; the per-file limit is ${max} bytes. Preserve these exact producer bytes and retry after a compatible update, or revise this producer explicitly.`);
     const bytes = Buffer.alloc(stat.size);
     let offset = 0;
     while (offset < bytes.length) {
@@ -115,7 +116,7 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
       try {
         if (!safeName(ref.name) || !/^[a-f0-9]{64}$/.test(ref.sha256) || ref.path !== copyPath(ref.sha256, ref.name))
           throw new Error('Invalid intermediate artifact version identity.');
-        if (!historical && state.pending?.taskId && state.pending.taskId === ref.taskId && state.pending.sources.some(source =>
+        if (!historical && state.pending && (state.pending.recovery === true || state.pending.taskId === ref.taskId) && state.pending.sources.some(source =>
           source.name === ref.name || source.name === ref.model?.page)) throw new Error('Producer handoff remains unfinished');
         let bytes;
         try { bytes = readIntermediateFile(wt, ref.path); }
@@ -144,12 +145,21 @@ 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 });
-    const changed = changedArtifacts(before, standing);
+    let 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.
-    const pending = state.pending?.taskId === taskId && taskId ? state.pending : null;
+    // 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.recovery === true && job.kind === 'human')) ? state.pending : null;
+    if (state.pending?.recovery && !pending)
+      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));
+    }
+    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 (!pending.recovery && (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)); }
@@ -157,7 +167,7 @@ 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.`);
-      changed.push(entry);
+      if (!changed.some(e => e.name === entry.name)) changed.push(entry);
     }
     if (taskKind === 'model' && !changed.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))) {
@@ -167,7 +177,7 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
     }
     const pages = taskKind === 'model' ? changed.filter(e => /\.html?$/i.test(e.name)) : [];
     const outputs = changed.filter(e => artifactTypeFor(e.name));
-    state.pending = { taskId, turnId, sources: outputs.map(e => ({ name: e.name, sha256: hash(readIntermediateFile(wt, `.flowviant/artifacts/${e.name}`, artifactMaxBytesFor(e.name))) })), exports: pending?.exports ?? [] };
+    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 = [];
     for (const page of pages) {
@@ -192,11 +202,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 }));
@@ -221,7 +232,33 @@ export function createIntermediateArtifacts({ wt, agentId, path, exportPage = ex
       save({ ...state, files: [...byName.values()], pending: null });
     } };
   };
-  return { inputs, prepare };
+  /** Offline recovery of an interrupted producer with no saved pending set.
+   * The operator supplies the original log/export binding, never a new model
+   * or a same-name Library lookup. This publishes no consumer receipt. */
+  const restorePending = ({ taskId, turnId, sources, exports }) => {
+    const id = /^[A-Za-z0-9_-]{1,80}$/;
+    if (!(taskId === null || id.test(taskId ?? '')) || !id.test(turnId ?? '') ||
+        !Array.isArray(sources) || !sources.length || sources.length > ARTIFACT_MAX_PER_AGENT ||
+        !Array.isArray(exports) || !exports.length ||
+        new Set(sources.map(s => s.name)).size !== sources.length)
+      throw new Error('Recovery needs the exact producer task, turn, source hashes and page-export bindings.');
+    const state = load();
+    if (state.pending && (state.pending.taskId !== taskId || state.pending.turnId !== turnId))
+      throw new Error('Another producer handoff is pending. Preserve its receipt before recovery.');
+    for (const ref of sources) {
+      if (!safeName(ref.name) || !artifactTypeFor(ref.name) || !/^[a-f0-9]{64}$/.test(ref.sha256 ?? '') ||
+          hash(readIntermediateFile(wt, `.flowviant/artifacts/${ref.name}`, artifactMaxBytesFor(ref.name))) !== ref.sha256)
+        throw new Error(`Recovery source ${ref.name} does not match its original producer hash. Restore the exact bytes before retrying.`);
+    }
+    if (!exports.every(ref => ref.name === ref.page?.replace(/\.html?$/i, '.glb') &&
+        /\.html?$/i.test(ref.page) && sources.some(s => s.name === ref.page && s.sha256 === ref.pageSha256) &&
+        sources.some(s => s.name === ref.name && s.sha256 === ref.sha256)) || !measuredModelExports(wt, exports))
+      throw new Error('Recovery page/export binding is missing, changed or unusable. Restore the original producer export evidence.');
+    save({ ...state, pending: { taskId, turnId, recovery: true, recoverySourceTurnId: turnId,
+      sources: sources.map(({ name, sha256 }) => ({ name, sha256 })),
+      exports: exports.map(({ page, pageSha256, name, sha256 }) => ({ page, pageSha256, name, sha256 })) } });
+  };
+  return { inputs, prepare, restorePending };
 }
 
 export function intermediateArtifactContext(files = []) {

package/bin/lib/knowledgeLibrary.mjs

@@ -41,6 +41,7 @@
  */
 
 import { safeFileName } from './safeFileName.mjs';
+import { ARTIFACT_BINARY_MODEL_MAX_BYTES } from './artifactPolicy.mjs';
 
 /** Relative to the checkout, under `.flowviant/` beside the turn uploads and
  *  the artifacts — see `FLOWVIANT_OWN_PATHS` for why that is NOT one exclude
@@ -140,7 +141,7 @@ export const INSTRUCTIONS_FILE = 'INSTRUCTIONS.md';
 export const KNOWLEDGE_FILE_MAX_BYTES = 10 * 1024 * 1024;
 export const KNOWLEDGE_BINARY_MODEL_MAX_BYTES = 20 * 1024 * 1024;
 export const knowledgeMaxFor = (name, base) => /\.(glb|bin)$/i.test(name)
-  ? Math.max(base, KNOWLEDGE_BINARY_MODEL_MAX_BYTES) : base;
+  ? Math.max(base, /^(models|designs)\//.test(name) ? ARTIFACT_BINARY_MODEL_MAX_BYTES : 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. */
 export const MAX_FILES = 64;

package/bin/lib/localCleanupReport.mjs

@@ -0,0 +1,34 @@
+/** Local diagnostics only: consume measured outcomes, never estimate disk use. */
+import { randomUUID } from 'node:crypto';
+import { retainTurnRecord } from './daemonLogging.mjs';
+import { encodeDetailRecord, decodeDetailRecord } from './daemonJournal.mjs';
+import { formatTurnRecord } from './turnRecord.mjs';
+
+export function reportLocalCleanup(entry, { retain = retainTurnRecord,
+  write = text => process.stderr.write(text) } = {}) {
+  if (!entry || entry.reason === 'already-evicted') return true;
+  const id = entry.id || randomUUID();
+  const bytes = entry.status === 'reclaimed' && Number.isFinite(entry.bytes) && entry.bytes >= 0 ? entry.bytes : null;
+  const text = JSON.stringify({ operation: entry.kind === 'artifact' ? 'local-cache-eviction' : 'managed-local-cleanup',
+    attemptId: id, status: entry.status, kind: entry.kind,
+    name: entry.name, path: entry.path, projectId: entry.projectId,
+    place: entry.place, placeDir: entry.placeDir, agentId: entry.agentId,
+    sessionId: entry.sessionId, localVersion: entry.localVersion,
+    reclaimedFiles: entry.status === 'reclaimed' ? 1 : 0,
+    reclaimedBytes: bytes, reason: entry.reason, error: entry.error,
+    incomplete: entry.incomplete === true,
+    retryAt: entry.status === 'failed' || entry.incomplete || entry.status === 'retained' ? entry.nextAt : undefined,
+    tries: entry.tries, resumedAttempt: entry.resumedAttempt,
+    previousCompletion: entry.previousCompletion,
+    cloudCopies: 'unchanged', repositoryFiles: 'unchanged' });
+  // Use the journal's own scrub/clip policy even when retention fails and the
+  // complete diagnostic must be shown live. No raw paths/errors reach output.
+  const record = decodeDetailRecord(encodeDetailRecord({ kind: 'cleanup',
+    name: 'Local cleanup', workId: entry.agentId || entry.sessionId || entry.place || '',
+    turnId: entry.turnId || `cleanup:${id}`, source: `cleanup:${id}`,
+    observedAt: entry.at ?? Date.now(), text }));
+  const retained = retain(record);
+  if (retained !== true || entry.status === 'failed' || entry.incomplete)
+    write(formatTurnRecord(record, { color: false }));
+  return retained === true;
+}

package/bin/lib/localCleanupState.mjs

@@ -0,0 +1,68 @@
+/** Private operational attempts, not a diagnostic log. Atomic and bounded;
+ * losing/corrupting state never grants permission to delete. */
+import { constants, openSync, closeSync, fstatSync, readFileSync, writeFileSync, fsyncSync, renameSync, rmSync, lstatSync, realpathSync, linkSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { processAlive, processStartTime, bootMark, sameBoot } from './procRegistry.mjs';
+
+export function cleanupState(path, identity) {
+  if (realpathSync(dirname(path)) !== resolve(dirname(path))) throw new Error('cleanup-state-parent-unsafe');
+  const read = file => {
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const st = fstatSync(fd);
+      if (!st.isFile() || st.size > 2 * 1024 * 1024) throw new Error('cleanup-state-unreadable');
+      return JSON.parse(readFileSync(fd, 'utf8'));
+    } finally { closeSync(fd); }
+  };
+  const load = () => {
+    let value;
+    try { value = read(path); }
+    catch (e) { if (e.code === 'ENOENT') return { version: 1, identity, cursor: 0, attempts: {}, results: [] }; throw e; }
+    if (value.version !== 1 || value.identity !== identity || !Number.isSafeInteger(value.cursor) || value.cursor < 0 ||
+        !value.attempts || typeof value.attempts !== 'object' || Array.isArray(value.attempts) || Object.keys(value.attempts).length > 2000 ||
+        !Array.isArray(value.results) || value.results.length > 128 || Object.values(value.attempts).some(a =>
+          !Number.isFinite(a.nextAt) || !Number.isSafeInteger(a.tries) || a.tries < 0)) throw new Error('cleanup-state-unreadable');
+    return value;
+  };
+  const save = value => {
+    const tmp = `${path}.${randomUUID()}.tmp`, bytes = JSON.stringify(value);
+    if (Buffer.byteLength(bytes) > 2 * 1024 * 1024) throw new Error('cleanup-state-budget-exhausted');
+    try {
+      const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+      try { writeFileSync(fd, bytes); 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 }); }
+  };
+  /** No age-only lock stealing: a live or unreadable holder keeps its claim. */
+  const claim = () => {
+    const lock = `${path}.lock`, token = randomUUID();
+    for (let i = 0; i < 2; i++) {
+      try {
+        const tmp = `${lock}.${token}.tmp`;
+        try {
+          const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+          try { writeFileSync(fd, JSON.stringify({ identity, token, pid: process.pid, start: processStartTime(process.pid), boot: bootMark() })); fsyncSync(fd); }
+          finally { closeSync(fd); }
+          linkSync(tmp, lock); // publish only complete ownership evidence
+        } finally { rmSync(tmp, { force: true }); }
+        return () => { try { if (read(lock).token === token) rmSync(lock); } catch { /* retain an unknown replacement */ } };
+      } catch (error) {
+        if (error.code !== 'EEXIST') return null;
+        try {
+          const stat = lstatSync(lock), holder = read(lock);
+          if (holder.identity !== identity || !Number.isInteger(holder.pid) || holder.pid <= 1) return null;
+          const alive = processAlive(holder.pid), start = processStartTime(holder.pid);
+          if (alive && (!holder.boot || sameBoot(holder.boot)) && (!holder.start || !start || start === holder.start)) return null;
+          const current = lstatSync(lock);
+          if (current.ino !== stat.ino || current.mtimeMs !== stat.mtimeMs) return null;
+          rmSync(lock);
+        } catch { return null; }
+      }
+    }
+    return null;
+  };
+  return { load, save, claim };
+}

package/bin/lib/logReplay.mjs

@@ -29,10 +29,16 @@ function openCursor(path) {
 
 export function createLogReader(path, { turnId = null } = {}) {
   let current = null, previousSeen = null, initialized = false, closed = false;
+  const cleanupIds = new Set();
   const line = (raw, batch) => {
     const row = decodeDetailRecord(raw);
     if (row === false) { batch.lines.push('[detail gap: an incomplete or unreadable retained record was skipped]'); return; }
     if (row) {
+      if (row.kind === 'cleanup' && row.source.startsWith('cleanup:')) {
+        if (cleanupIds.has(row.source)) return;
+        if (cleanupIds.size >= 8192) cleanupIds.delete(cleanupIds.values().next().value);
+        cleanupIds.add(row.source);
+      }
       if (turnId !== null && !matchesTurn(row.turnId, turnId)) return;
       batch.matched++;
       for (const text of formatTurnRecord(row, { color: false }).slice(0, -1).split('\n')) batch.lines.push(text);

package/bin/lib/managedLocalCleanup.mjs

@@ -0,0 +1,158 @@
+/** Inventory and release of turn-owned scratch/native originals. All mutations
+ * run under the caller's place writer lock. The artifact cache owns version,
+ * pin, recovery and unlink policy; this module supplies provenance and roots. */
+import { readdirSync, lstatSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createArtifactCache } from './artifactCache.mjs';
+import { realDirState } from './ownedDirs.mjs';
+
+const MAX_FILES = 512;
+const stamp = st => `${st.dev}:${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`;
+
+/** Unknown and linked entries are never visited. No fallback to a personal home. */
+function inventory(root) {
+  const files = new Map(); let visited = 0;
+  if (realDirState(root) === 'none') return files;
+  if (realDirState(root) !== 'dir' || realpathSync(root) !== resolve(root)) throw new Error('unsafe-managed-root');
+  const walk = (at, prefix, depth) => {
+    for (const name of readdirSync(at)) {
+      if (++visited > MAX_FILES) throw new Error('inventory-budget-exhausted');
+      if (name.startsWith('.')) continue;
+      const path = join(at, name), relative = prefix ? `${prefix}/${name}` : name;
+      const st = lstatSync(path);
+      if (st.isSymbolicLink()) continue;
+      if (st.isFile()) files.set(relative, stamp(st));
+      else if (st.isDirectory() && depth < 4) walk(path, relative, depth + 1);
+    }
+  };
+  walk(root, '', 0); return files;
+}
+
+export function createManagedLocalCleanup({ placeDir, projectId, agentId, path, codexHome = null, outputCache = null, getUses = () => [], unlink = null }) {
+  if (!projectId || !agentId || !path) throw new Error('ownership-unknown');
+  const privateDir = dirname(path);
+  // The kept home is derived by workAgentResume from this private git dir.
+  // Never accept arbitrary CODEX_HOME, downloads, or another repository root.
+  const expectedHome = join(privateDir, `flowviant-agent-codex-home-${agentId}`);
+  if (codexHome && resolve(codexHome) !== resolve(expectedHome)) throw new Error('unowned-native-home');
+  const roots = { scratch: join(placeDir, '.flowviant/tmp'),
+    ...(codexHome ? { 'native-image': join(codexHome, 'generated_images') } : {}) };
+  let turnId = null, before = null;
+  const changedBeforeTurn = {};
+  const stores = {};
+  for (const [kind, root] of Object.entries(roots)) {
+    stores[kind] = createArtifactCache({ placeDir, path: `${path}.${kind}`, scope: { projectId, agentId },
+      managedKind: kind, managedRoot: root, getUses: name => getUses({ kind, name }),
+      ...(unlink ? { unlink } : {}),
+      fetchVersion: async ref => {
+        const owned = stores[kind].records().find(f => f.name === ref.name && f.sha256 === ref.sha256);
+        const copy = owned?.preserved;
+        if (!outputCache || !copy) throw new Error('preserved-copy-unknown');
+        const recorded = outputCache.records().find(f => f.name === copy.name && f.localVersion === copy.localVersion && f.sha256 === ref.sha256 && f.remote?.id === ref.remote.id);
+        if (!recorded || recorded.state === 'discarded' || recorded.uses?.includes('pending-upload')) throw new Error('preserved-version-changed');
+        const local = outputCache.measure(copy.name);
+        if (local.sha256 !== ref.sha256) throw new Error('preserved-version-changed');
+        const bytes = await outputCache.verifyRemote({ ...recorded, remote: recorded.remote });
+        const after = outputCache.records().find(f => f.name === copy.name && f.localVersion === copy.localVersion && f.remote?.id === ref.remote.id);
+        if (!after || after.uses?.includes('pending-upload') || after.state !== 'local' || outputCache.measure(copy.name).signature !== local.signature) throw new Error('preserved-version-changed');
+        return bytes;
+      } });
+  }
+  const begin = id => {
+    if (!id) throw new Error('turn-unknown');
+    turnId = id;
+    before = Object.fromEntries(Object.entries(roots).map(([kind, root]) => {
+      try {
+        const measured = inventory(root), known = stores[kind].records().filter(f => measured.has(f.name));
+        if (known.length > 32) throw new Error('ownership-budget-exhausted');
+        changedBeforeTurn[kind] = new Set();
+        for (const ref of known) {
+          if (ref.signature !== measured.get(ref.name)) { changedBeforeTurn[kind].add(ref.name); continue; }
+          stores[kind].recordManaged({ name: ref.name, turnId });
+        }
+        return [kind, measured];
+      } catch { return [kind, null]; }
+    }));
+  };
+  const preservedCopy = (store, name) => {
+    if (!outputCache || !/\.(png|webp)$/i.test(name)) return null;
+    const measured = store.measure(name);
+    // Native originals can have different names. Only exact encoded bytes
+    // bind the copy, never a filename, pixel similarity or newest selection.
+    for (const ref of outputCache.records()) {
+      if (ref.state !== 'local' || ref.sha256 !== measured.sha256 || !ref.remote?.id || !/\.(png|webp)$/i.test(ref.name)) continue;
+      if (outputCache.measure(ref.name).sha256 === measured.sha256)
+        return { name: ref.name, localVersion: ref.localVersion, sha256: ref.sha256, remote: ref.remote };
+    }
+    return null;
+  };
+  const capture = () => {
+    const results = [];
+    if (!before) return [{ status: 'retained', reason: 'turn-ownership-unknown' }];
+    for (const [kind, root] of Object.entries(roots)) {
+      try {
+        if (!before[kind]) { results.push({ status: 'retained', kind, reason: 'initial-inventory-unknown' }); continue; }
+        const now = inventory(root), store = stores[kind], known = new Set(store.records().map(f => f.name));
+        let remaining = 32;
+        for (const [name] of now) {
+          if (changedBeforeTurn[kind]?.has(name)) { results.push({ status: 'retained', kind, name, reason: 'local-version-changed' }); continue; }
+          // A pre-existing untracked file remains the person's/unknown file,
+          // even if this turn rewrote it. Only newly created entries qualify.
+          if (before[kind].has(name) && !known.has(name)) { results.push({ status: 'retained', kind, name, reason: 'ownership-unknown' }); continue; }
+          if (remaining-- <= 0) { results.push({ status: 'retained', kind, name, reason: 'ownership-budget-exhausted' }); continue; }
+          try {
+            const preserved = kind === 'native-image' ? preservedCopy(store, name) : null;
+            store.recordManaged({ name, turnId, preserved });
+          } catch (error) { results.push({ status: 'retained', kind, name, reason: error.message }); }
+        }
+      } catch (error) { results.push({ status: 'retained', kind, reason: error.message }); }
+    }
+    return results;
+  };
+  /** Explicit current lifecycle evidence, not Done/upload completion. Callers
+   * retain revision/texture/producer/resume requirements until released. */
+  const release = ({ kind, name, localVersion, uses }) => {
+    const store = stores[kind]; if (!store) throw new Error('ownership-unknown');
+    const ref = store.records().find(f => f.name === name && f.localVersion === localVersion);
+    if (!ref) throw new Error('local-version-changed');
+    if (kind === 'native-image' && !ref.preserved) throw new Error('preserved-copy-unknown');
+    store.requirements({ name, localVersion, uses, ...(kind === 'native-image' ? {
+      bundle: { complete: true, files: [{ name, id: ref.remote.id, sha256: ref.sha256 }] },
+    } : {}) });
+  };
+  const completeTurn = ({ drained, handoffComplete, uploadsComplete }) => {
+    if (drained !== true || handoffComplete !== true || uploadsComplete !== true) return [];
+    const results = [];
+    try {
+      for (const ref of stores.scratch.records()) {
+        if (ref.turnId !== turnId || ref.state !== 'local') continue;
+        // Only the turn pin is released. Any explicit or unknown dependency
+        // survives completion; native originals retain their resume pin.
+        try { release({ kind: 'scratch', ...ref, uses: (ref.uses ?? ['requirements-unknown']).filter(u => u !== `turn:${turnId}`) }); }
+        catch (error) { results.push({ status: 'retained', kind: 'scratch', name: ref.name, reason: error.message }); }
+      }
+    } catch (error) { results.push({ status: 'retained', kind: 'scratch', reason: error.message }); }
+    return results;
+  };
+  const reclaim = async ({ drained, budget = 32 } = {}) => {
+    const results = [];
+    if (drained !== true) return [{ status: 'retained', reason: 'process-state-unknown-or-running' }];
+    for (const [kind, store] of Object.entries(stores)) {
+      if (before && !before[kind]) { results.push({ status: 'retained', kind, reason: 'initial-inventory-unknown' }); continue; }
+      let records;
+      try { records = store.records(); }
+      catch (error) { results.push({ status: 'retained', kind, reason: error.message }); continue; }
+      for (const ref of records) {
+        if (results.length >= budget) return results;
+        if (ref.state === 'discarded') continue;
+        const result = await store.evict(ref);
+        results.push({ ...result, kind, path: join(roots[kind], ref.name), projectId, agentId, placeDir });
+      }
+    }
+    return results;
+  };
+  const prepare = ref => stores[ref.kind]?.prepareEviction(ref) ?? { status: 'retained', reason: 'ownership-unknown' };
+  const reclaimOne = ref => stores[ref.kind]?.evict(ref) ?? { status: 'retained', reason: 'ownership-unknown' };
+  return { begin, capture, release, completeTurn, reclaim, prepare, reclaimOne,
+    records: () => Object.entries(stores).flatMap(([kind, store]) => store.records().map(ref => ({ ...ref, kind }))) };
+}

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/bin/lib/resultInputs.mjs

@@ -8,6 +8,8 @@ import { ensureRealSubdir } from './ownedDirs.mjs';
 import { excludeInWorktree } from './git.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { artifactMaxBytesFor } from './artifacts.mjs';
+import { RESULT_INPUT_MAX_FILES } from './artifactPolicy.mjs';
 
 const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const hex = (s) => typeof s === 'string' && /^[a-f0-9]{64}$/.test(s);
@@ -15,11 +17,11 @@ const safeName = (s) => typeof s === 'string' && s.length <= 500 &&
   !/[\\\x00-\x1f\x7f:]/.test(s) && s.split('/').every(p => p && p !== '.' && p !== '..');
 function inputPath(file) {
   if (!file || !/^result-[a-f0-9]{48}$/.test(file.contextId) || !hex(file.id) || !hex(file.sha256) || !safeName(file.name) ||
-    !Number.isSafeInteger(file.size) || file.size < 0 || file.size > 20 * 1024 * 1024) throw new Error('The selected result input identity was malformed.');
+    !Number.isSafeInteger(file.size) || file.size < 0 || file.size > Math.max(20 * 1024 * 1024, artifactMaxBytesFor(file.name))) throw new Error('The selected result input identity was malformed.');
   return `.flowviant/inputs/${file.contextId}/${file.name}`;
 }
 function inputList(inputs) {
-  if (!Array.isArray(inputs) || inputs.length > 128) throw new Error('The selected result inputs were malformed.');
+  if (!Array.isArray(inputs) || inputs.length > RESULT_INPUT_MAX_FILES) throw new Error('The selected result inputs were malformed.');
   return inputs;
 }
 

package/bin/lib/runtimeCodex.mjs

@@ -432,7 +432,7 @@ export function codexArtifactFence(cwd, { name, imageGeneration = false, what, c
     throw new Error(`${what} needs its worktree to fence — none reached codex's builder`);
   }
   const artifacts = join(cwd, ARTIFACT_DIR);
-  // THE TURN'S OWN SCRATCH (artifacts.mjs `ensureFenceScratch`, made empty by
+  // THE TURN'S OWN SCRATCH (artifacts.mjs `ensureFenceScratch`, made by
   // the lane before spawn): `/tmp` is read-only in here, and a here-document
   // needs a temp file — measured, a `cat > page.html <<EOF` failed "can't
   // create temp file for here document: read-only file system" and the turn

package/bin/lib/work.mjs

@@ -1,3 +1,4 @@
+import { reportLocalCleanup } from './localCleanupReport.mjs';
 /**
  * Work sessions — the Workbench tabs and the agent lanes, daemon side: THE
  * MANAGER that builds every lane and hands each one exactly what it uses.
@@ -27,6 +28,7 @@
  * whole — `workBusy` and the returned surface. A pure rule or constant
  * (REPO_PLACE, the resume-id guards, brainFor, the turn lock) is IMPORTED by
  * every lane that reads it, never carried through here.
+ *   workLocalCleanup.mjs   released managed session and agent cleanup
  *   workPlaces.mjs         where a session works, its worktree, its markers
  *   workSessionGroups.mjs  which process groups each tab started
  *   workChildren.mjs       the live CLI children, teardown, the admission
@@ -60,6 +62,10 @@
  *   repositoryPlaces + agentRepositories: multi-repo places; the live brief: workAgentBrief, workAgentBriefRunner)
  */
 
+import { dirname, join } from 'node:path';
+import { placeTurnLockedByLivePid } from './turnLock.mjs';
+import { createWorkLocalCleanup } from './workLocalCleanup.mjs';
+import { createManagedLocalCleanup } from './managedLocalCleanup.mjs';
 import { trackedRepositorySetup } from './repositorySetup.mjs';
 import { createRepositoryPlaces } from './repositoryPlaces.mjs';
 import { createAgentRepositories } from './agentRepositories.mjs';
@@ -91,7 +97,7 @@ import { createWorkSessionRuntime } from './workSessionRuntime.mjs';
 import { createAdoptCarry } from './workAdoptCarry.mjs';
 import { createWorkSessionTurns } from './workSessionTurns.mjs';
 import { createWorkRetire } from './workRetire.mjs';
-import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT, PROJECT_ID } from './config.mjs';
 import { gitNet as gitNetIn, excludeInWorktree } from './git.mjs';
 import { createProjectLandedObserver } from './projectLanded.mjs';
 import { createPlaceLock } from './placeLock.mjs';
@@ -110,6 +116,7 @@ export function createWorkManager({
   getBaseRef,
   getMcpUrl,
   getLeaseTtl, exportModel,
+  getCleanupPermission = () => false,
   /** "The repo picture changed — look again." See the caller in fleet.mjs. */
   onRepoChanged = () => {},
   /**
@@ -156,6 +163,7 @@ export function createWorkManager({
    */
   const artifacts = createArtifactReporter({
     fleetUrl: FLEET_URL,
+    projectIdentity: () => PROJECT_ID,
     token: FLEET_TOKEN,
     userAgent: USER_AGENT,
     scrub: envScrub,
@@ -211,7 +219,7 @@ export function createWorkManager({
 
   const { placeOf, notePlace, learnPlaces, placeDir, branchAt, placeWtFor, sessionMetaPath, worktreeBornAt } =
     createWorkPlaces({ repoRoot, baseDir, baseRef, onRepoChanged });
-  const { sessionGroups, noteSessionGroup, pruneSessionGroups, sessionProcesses } =
+  const { sessionGroups, noteSessionGroup, pruneSessionGroups, sessionProcesses, cleanupProcessesIdle } =
     createWorkSessionGroups({ repoRoot });
   const { workChildren, groupKillChildren, shutdownWork, liveTurnCount, liveTurns, admit } =
     createWorkChildren({ extraLiveTurns });
@@ -226,6 +234,39 @@ export function createWorkManager({
     getArtifactsAccepted,
     log: (line) => warn(line),
   });
+  const { reconcileLocalCleanup, cleanupBusy } = createWorkLocalCleanup({
+    placeLocks, inPlace, permission: getCleanupPermission,
+    onResult: reportLocalCleanup, onIncomplete: reportLocalCleanup,
+    eligible: place => {
+      if (shipping.size || cleanupProcessesIdle(place) !== true) return false;
+      const wt = placeDir(place), lock = wt && sessionMetaPath(wt, 'flowviant-turn.lock');
+      return Boolean(lock) && !placeTurnLockedByLivePid(lock);
+    },
+    targetsFor: place => {
+      if (!PROJECT_ID) return [];
+      const agentId = place.slice(2), siblings = repositoryPlaces?.entries(place);
+      const roots = siblings?.length ? siblings.filter(r => r.writable).map(r => r.wt) : [placeDir(place)];
+      return roots.flatMap(wt => {
+        const statePath = wt && sessionMetaPath(wt, 'flowviant-local-cleanup', agentId);
+        if (!statePath) return [];
+        return [{ placeDir: wt, agentId, projectId: PROJECT_ID, statePath,
+          operations: ({ guard, recoveryMemo, preparedOnly }) => {
+            const output = artifacts.cacheFor({ placeDir: wt, agentId, cleanupGuard: guard, recoveryMemo, preparedOnly });
+            if (!output) return [];
+            const managed = createManagedLocalCleanup({ placeDir: wt, projectId: PROJECT_ID, agentId,
+              path: sessionMetaPath(wt, 'flowviant-managed-local', agentId),
+              codexHome: join(dirname(statePath), `flowviant-agent-codex-home-${agentId}`),
+              outputCache: output, getUses: () => guard() ? [] : ['lifecycle-unknown-or-active'],
+            });
+            return [...output.records().map(ref => ({ ref: { ...ref, kind: 'artifact' },
+              prepare: () => output.prepareEviction(ref), run: () => output.evict(ref) })),
+            ...managed.records().map(ref => ({ ref,
+              prepare: () => managed.prepare(ref), run: () => managed.reclaimOne(ref) }))];
+          } }];
+      });
+    },
+    log: line => warn(line),
+  });
   const { reportSessionWorktree, reportPlaceWorktrees, burstListeners, reportWorktrees } =
     createWorkPlaceReports({
       repositoryPlaces,
@@ -455,7 +496,7 @@ export function createWorkManager({
     workChildren.size > 0 ||
     workAnswering.size > 0 ||
     pendingWorkReports.size > 0 ||
-    pendingShipReports.size > 0;
+    pendingShipReports.size > 0 || cleanupBusy();
 
   return {
     flushWorkReports,
@@ -473,6 +514,7 @@ export function createWorkManager({
     retireWorkSessions,
     reportWorktrees,
     reconcileIdleArtifacts,
+    reconcileLocalCleanup,
     shutdownWork,
     workBusy,
     runningAgentCount: () => agentTurns.size,

package/bin/lib/workAgentPlans.mjs

@@ -1,3 +1,4 @@
+import { fetchResultInputs } from './resultInputs.mjs';
 import { planWork, reportPlanOutcome } from './workActivity.mjs';
 /** Agent plan claims, read-only planning turns, and proposal reports. */
 import { PLAN_RECOVERY_SYSTEM, parsePlanDiagnosis, watchPlanAttempt } from './workPlanRecovery.mjs';
@@ -287,6 +288,7 @@ export function createWorkAgentPlans({
          */
         const liveAgents = (Array.isArray(job.liveAgents) ? job.liveAgents : []).map(a =>
           liveAgentContext(a, measureAgentFootprint({ placeId: a?.placeId, baseDir, baseRef })));
+        await fetchResultInputs(repoRoot, job.resultInputs);
         const knowledgeDir = knowledgeDirFor(repoRoot);
         discovery.toolLog.baseline = measureRepositoryBaseline({ cwd: repoRoot, baseRef, knowledgeDir });
         discovery.toolLog.captureBaseline = repositoryBaselineOf(job.captureBaseline);
@@ -351,6 +353,7 @@ export function createWorkAgentPlans({
           });
         };
         let context = AGENT_PLAN_KICKOFF({ tasks, liveAgents, agentCap: Number.isInteger(job.agentCap) && job.agentCap > 0 ? job.agentCap : 3 });
+        if (job.resultContext) context += '\n\n' + job.resultContext;
         if (job.recovery?.start) context += '\nSTART REPAIR: This is a supporting diagnosis for an already approved Start. Return exactly ONE group with the same ordered taskIds, attachment target (or absence) and CLI. Preserve the approval; do not start an unapproved sibling. Diagnose admission/pickup errors and repair planning evidence/context. Ask only a genuine person-only question in the diagnostic JSON. Approval and source revision (data): ' + JSON.stringify(job.recovery.start);
         const system = withProjectContext(SYSTEM_PLAN, { knowledgeDir }) + '\n\n' + discoveryGuide(rt, 'planning') + '\n\n' + REPOSITORY_BASELINE_PARAGRAPH(discovery.toolLog.baseline, discovery.toolLog.captureBaseline, discovery.toolLog.reconciliation);
         if (job.recovery) {