flowviant 0.125.18 → 0.125.20

package/bin/lib/intermediateArtifacts.mjs

@@ -33,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) {
@@ -116,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); }
@@ -145,15 +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.
     // 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 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) || discarded.has(artifactStoredName(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)); }
@@ -161,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))) {
@@ -171,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) {
@@ -226,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/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) {

package/bin/lib/workAgentPrecheck.mjs

@@ -12,10 +12,12 @@ import { gitOrNull } from './git.mjs';
 import { parsePrecheck } from './agentPlan.mjs';
 import { readStash } from './agentCards.mjs';
 import { c, note } from './ui.mjs';
-import { runTurn } from './runTurn.mjs';
+import { runTurn as defaultRunTurn } from './runTurn.mjs';
 import { SYSTEM_PRECHECK, AGENT_PRECHECK_KICKOFF } from './prompts.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
-import { pickRuntimeFor } from './runtimeDetection.mjs';
+import { detectRuntimes as defaultDetectRuntimes } from './runtimeDetection.mjs';
+import { canRun, runtimeById } from './runtimes.mjs';
+import { brainFor } from './workBrain.mjs';
 import { runCappedTurn } from './workCappedTurn.mjs';
 import { taskIdsFromMessage } from './worktreeDiff.mjs';
 import { limitLine } from './cliLimit.mjs';
@@ -23,12 +25,12 @@ import { fleetEndpoint, isConsideredRefusal } from './fleetWire.mjs';
 import { postFleetJson } from './fleetPost.mjs';
 import { agentBrowserHome } from './noWindowEnv.mjs';
 
-export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workChildren }) {
+export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workChildren, runTurn = defaultRunTurn, detectRuntimes = defaultDetectRuntimes }) {
   const AGENT_PRECHECK_URL = fleetEndpoint('agent-precheck', FLEET_URL);
 
   // ── THE AI PRE-REVIEW ──────────────────────────────────────────────────────
   //
-  // A FRESH Claude reads the branch before the human does. The owner asked for
+  // A fresh conversation reads the branch before the human does. The owner asked for
   // it in these words: "before having the user manually check, can we have the
   // daemon … spawn an agent to review the work so basically we get an ai to look
   // at the review before a human looks at it for a double check."
@@ -135,15 +137,14 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
     return { text, taskIds: [...taskIds] };
   };
 
-  const runPrecheck = async (agentId, wt, agentName, repository) => {
-    /**
-     * WHICH CLI READS. `pickRuntimeFor('consult')` — the same picker the scratch
-     * planner uses, and for the same reason: this prompt was written against
-     * Claude, and a machine with no read-only-capable runtime simply does not
-     * produce a precheck. Nothing is posted and nothing is said on the row.
-     */
-    const rt = pickRuntimeFor('consult');
-    if (!rt) return;
+  const runPrecheck = async (agentId, wt, agentName, repository, source) => {
+    // A fresh read-only conversation, on this agent's CLI/model/effort.
+    // Missing provenance or a missing CLI skips this optional reading; it
+    // never licenses a machine-wide provider substitution.
+    if (!source) return;
+    const rt = source.runtime || 'claude';
+    if (!canRun(runtimeById(rt), 'consult') || !detectRuntimes().some(row => row.id === rt && row.installed)) return;
+    const brain = brainFor(source, rt);
     /**
      * THE PRESSURE GUARD, at the spawn, exactly as every other unattended lane
      * asks it. `churn` and never `interactive`: nobody is watching this, and a
@@ -232,6 +233,7 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
           profile: 'consult',
           cwd: wt,
           runtime: rt,
+          ...brain,
           // The agent's own browser profile, in the worktree this reader stands
           // in; no display either way (noWindowEnv.mjs, 2026-09-29).
           browserHome: agentBrowserHome(sessionMetaPath, wt, agentId),
@@ -242,8 +244,7 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
           work: { kind: 'pre-review', id: agentId, name: agentName },
           // The CLI's own count for this reading. Set, never accumulated: one
           // turn is one `result` event, and the adding-up is the server's.
-          // Tagged with the CLI, so a Claude pre-review of a Codex agent is
-          // charged as Claude's and not folded into the agent's own figure.
+          // Tagged with the same CLI as the associated agent.
           onUsage: (u) => {
             usage = { ...u, runtime: rt };
           },