flowviant 0.125.18 → 0.125.20

package/bin/lib/artifactCache.mjs

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

package/bin/lib/artifactIteration.mjs

@@ -144,7 +144,7 @@ export function deletedArtifacts(placeDir, before) {
   // Only names this place held are candidates: this turn's snapshot and the
   // place's record (`before.seen`). Normalize live names before probing: a
   // draft+1.md is stored as draft_1.md and is not an absent retained file.
-  const candidates = new Set([...(before?.keys() ?? []), ...(before?.seen ?? [])]);
+  const candidates = new Set([...(before?.keys() ?? []), ...(before?.seen ?? [])].filter(name => !before?.evicted?.has(artifactStoredName(name))));
   const live = presentArtifacts(placeDir);
   if (!live) {
     return flowviantParentState(placeDir) === 'dir' && realDirState(join(placeDir, ARTIFACT_DIR)) === 'none'

package/bin/lib/artifactPolicy.mjs

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

package/bin/lib/artifactReporter.mjs

@@ -37,10 +37,12 @@
  * with `includeNames`, so it never attributes a sibling card's files.
  */
 
+import { createArtifactCache } from './artifactCache.mjs';
 import { artifactStoredName, artifactTypeFor, scanArtifacts } from './artifacts.mjs';
+import { ARTIFACT_MULTIPART_MAX_BYTES } from './artifactPolicy.mjs';
 import { fleetHeaders } from './fleetPost.mjs';
 import {
-  imageRevisionProtection, iterationSignature, iterationChanges, deletedArtifacts, localArtifact, discardLocalArtifact, iterationInstructions,
+  declaredDiscards, imageRevisionProtection, iterationSignature, iterationChanges, deletedArtifacts, localArtifact, discardLocalArtifact, iterationInstructions,
   presentArtifacts, readSeenArtifacts, writeSeenArtifacts, seenArtifacts, serverBornAt,
 } from './artifactIteration.mjs';
 import { fleetEndpoint, isConsideredRefusal } from './fleetWire.mjs';
@@ -74,17 +76,64 @@ export function createArtifactReporter({
    *  checkout, anything unreadable) gives a place without a record no
    *  legacy evidence at all. */
   placeBornAt = () => null,
+  projectIdentity = fleetUrl,
 }) {
   const url = fleetEndpoint('artifact', fleetUrl);
   const doFetch = fetchImpl ?? ((...a) => fetch(...a));
   const pending = new Map(); // `${owner}:${name}` -> { body, tries }
 
-  const prepare = async ({ placeDir, sessionId, agentId, before }) => {
+  const cacheFor = ({ placeDir, sessionId, agentId, cleanupGuard = null, recoveryMemo = null, preparedOnly = () => false }) => {
+    const privatePath = seenPath(placeDir, sessionId ?? agentId);
+    const project = typeof projectIdentity === 'function' ? projectIdentity() : projectIdentity;
+    if (!privatePath || !project) return null;
+    return createArtifactCache({ placeDir, path: `${privatePath}.cache`,
+      getDiscards: () => declaredDiscards(placeDir),
+      getUses: name => (cleanupGuard && cleanupGuard() !== true) || pending.has(`${sessionId ?? agentId}:${name}`) || chains.has(`${sessionId ?? agentId}:${name}`) ? ['pending-upload-or-removal'] : [],
+      scope: { projectId: project, ...(sessionId ? { sessionId } : { agentId }) },
+      fetchVersion: async ref => {
+        const key = `${ref.remote.id}:${ref.sha256}`, cached = recoveryMemo?.get(key);
+        if (cached && Date.now() >= cached.at && Date.now() - cached.at < 5_000) return cached.bytes;
+        if (preparedOnly()) throw new Error('recovery-verification-expired');
+        const query = new URLSearchParams({ ...(sessionId ? { sessionId } : { agentId }), sha256: ref.sha256 });
+        const response = await doFetch(`${url}/${encodeURIComponent(ref.remote.id)}/recover?${query}`, {
+          method: 'GET', headers: fleetHeaders({ token, json: false }), signal: AbortSignal.timeout(cleanupGuard ? 5_000 : 30_000),
+        });
+        if (!response.ok) throw new Error(`recovery-unavailable-http-${response.status}`);
+        // Bound even an incompatible server's response before buffering it.
+        const reader = response.body?.getReader();
+        if (!reader) throw new Error('recovery-unreadable');
+        const chunks = []; let size = 0;
+        try {
+          for (;;) {
+            const { done, value } = await reader.read(); if (done) break;
+            size += value.length;
+            if (size > 32 * 1024 * 1024) throw new Error('recovery-too-large');
+            chunks.push(Buffer.from(value));
+          }
+        } finally { await reader.cancel().catch(() => {}); }
+        const bytes = Buffer.concat(chunks);
+        recoveryMemo?.set(key, { bytes, at: Date.now() });
+        return bytes;
+      } });
+  };
+
+  const prepare = async ({ placeDir, sessionId, agentId, before, idle = false }) => {
     if (!before) return '';
     before.iterationSignature = iterationSignature(placeDir);
     delete before.stored;
     delete before.seen;
     before.inventoryFailed = false;
+    const cache = cacheFor({ placeDir, sessionId, agentId });
+    if (cache && !idle) {
+      // Consumer preparation is outside inventory's best-effort catch: exact
+      // recovery failure must stop this turn from consuming missing inputs.
+      const restored = await cache.restore(declaredDiscards(placeDir));
+      const snapshot = scanArtifacts(placeDir, { all: true });
+      for (const name of restored) {
+        const entry = snapshot.find(e => e.name === name);
+        if (entry) before.set(name, `${entry.size}:${entry.mtimeMs}`);
+      }
+    }
     const query = new URLSearchParams(sessionId ? { sessionId } : { agentId });
     try {
       const sentAt = Date.now();
@@ -100,6 +149,11 @@ export function createArtifactReporter({
       const result = await response.json();
       if (!Array.isArray(result.data)) { before.inventoryFailed = true; return ''; }
       before.stored = result.data.filter((a) => a && typeof a.id === 'string' && typeof a.name === 'string');
+      if (cache) for (const remote of before.stored) {
+        if (!/^[a-f0-9]{64}$/.test(remote.sha256 ?? '')) continue;
+        try { cache.record({ name: remote.name, remote }); }
+        catch { /* Unknown, missing or scrubbed local bytes are never owned. */ }
+      }
       const path = seenPath(placeDir, sessionId ?? agentId);
       before.seen = seenArtifacts(readSeenArtifacts(path), before.stored, presentArtifacts(placeDir) ?? new Set(),
         serverBornAt(placeBornAt(placeDir), response.headers?.get?.('date'), sentAt));
@@ -130,14 +184,22 @@ export function createArtifactReporter({
     }
     const form = new FormData();
     for (const [k, v] of Object.entries(body.fields)) form.set(k, v);
-    if (body.bytes) form.set('file', new Blob([body.bytes]), body.fields.name);
+    const streamed = body.bytes?.length > ARTIFACT_MULTIPART_MAX_BYTES;
+    if (body.bytes && !streamed) form.set('file', new Blob([body.bytes]), body.fields.name);
     if (body.preview) form.set('preview', new Blob([body.preview], { type: 'image/png' }), 'preview.png');
     try {
       const res = await doFetch(url, {
         method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent },
+        headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent,
+          ...(streamed ? {
+            'Content-Type': 'application/octet-stream',
+            'Content-Length': String(body.bytes.length),
+            'X-Flowviant-Artifact': JSON.stringify(body.fields),
+            'X-Content-Sha256': body.fields.sha256,
+          } : {}),
+        },
         signal: AbortSignal.timeout(30_000),
-        body: form,
+        body: streamed ? body.bytes : form,
       });
       if (res.ok) {
         const result = typeof res.json === 'function' ? await res.json().catch(() => null) : null;
@@ -186,6 +248,15 @@ export function createArtifactReporter({
       if (genOf.get(key) !== gen) return; // a newer copy decides for this key
       if (result.settled) pending.delete(key);
       else hold(key, body, tries + 1);
+      if (result.success && body.cacheInfo && result.id && body.bytes) {
+        try { cacheFor(body.cacheInfo)?.record({ name: body.fields.name,
+          remote: { id: result.id, sha256: body.fields.sha256 } }); }
+        catch (error) { log(`artifact ${body.fields.name}: local cache retained — ${error.message}`); }
+      }
+      if (result.success && body.removal) {
+        try { cacheFor(body.cacheInfo ?? { placeDir: body.placeDir, ...body.removal })?.discard(body.fields.name, body.removal.id); }
+        catch (error) { log(`artifact ${body.fields.name}: cache discard bookkeeping incomplete — ${error.message}`); }
+      }
       if (result.success && body.replacements?.length) {
         result.cleanupFailed = [];
         for (const removal of body.replacements) {
@@ -239,6 +310,14 @@ export function createArtifactReporter({
       for (const name of [...changes.remove, ...Object.keys(changes.replace)]) if (protectedNames.has(name)) throw new Error(`Image revision retained ${name}; its discard or replacement was not authorized.`);
     }
     if (!before?.stored && (changes.remove.length || Object.keys(changes.replace).length)) throw new Error('Stored artifact inventory could not be measured; removal was not attempted.');
+    // An unreadable eviction ledger is unknown evidence, never a discard.
+    const cache = cacheFor({ placeDir, sessionId, agentId });
+    // A standing replacement is not an unconditional remove: after restart
+    // its predecessor stays cached until this report has delivery evidence.
+    const standing = iterationChanges(placeDir, null);
+    const explicitAbsences = new Set([...standing.remove, ...Object.keys(changes.replace)]);
+    try { if (before) before.evicted = cache?.absences(before?.stored ?? [], explicitAbsences) ?? new Set(); }
+    catch { if (before) before.evicted = new Set((before?.stored ?? []).map(a => a.name)); }
     const removing = new Set([...changes.remove, ...Object.keys(changes.replace), ...(before?.stored ? deletedArtifacts(placeDir, before).filter(name => !protectedNames.has(name)) : [])]);
     const stored = new Map((before?.stored ?? []).map((a) => [a.name, a]));
     for (const name of [...changes.remove, ...Object.keys(changes.replace)]) {
@@ -292,6 +371,9 @@ export function createArtifactReporter({
         body.fields.renderState = measured.renderState;
         if (measured.preview) body.preview = measured.preview;
       }
+      body.cacheInfo = { placeDir, sessionId, agentId };
+      try { cache?.trackUpload(body.fields.name); }
+      catch (error) { log(`artifact ${body.fields.name}: ownership unavailable — ${error.message}`); }
       body.replacements = Object.entries(changes.replace).filter(([, to]) => to === body.fields.name).map(([name]) => {
         const key = `${sessionId ?? agentId}:${name}`;
         return { fields: { name }, removal: { ...(sessionId ? { sessionId } : { agentId }), id: stored.get(name).id, name },
@@ -377,9 +459,9 @@ export function createArtifactReporter({
    */
   const reconcile = async ({ placeDir, before, sessionId, agentId }) => {
     if (!placeDir || !before || (!sessionId && !agentId)) return 0;
-    await prepare({ placeDir, before, sessionId, agentId });
+    await prepare({ placeDir, before, sessionId, agentId, idle: true });
     return report({ placeDir, before, sessionId, agentId, idle: true });
   };
 
-  return { prepare, report, reconcile, retryPending, pendingCount: () => pending.size };
+  return { prepare, report, reconcile, cacheFor, retryPending, pendingCount: () => pending.size };
 }

package/bin/lib/artifacts.mjs

@@ -74,7 +74,7 @@
  * that cannot show an artifact must not have the CLI told it will.
  */
 
-import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, rmSync } from 'node:fs';
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { cutKeepingExtension } from './safeFileName.mjs';
@@ -138,7 +138,7 @@ export function ensureArtifactDir(placeDir) {
  * points both variables at it (runtimeCodex.mjs `codexDesignFence`), so the
  * shell works like a shell; nothing here is uploaded, committed or read back.
  *
- * Made EMPTY before each turn (a previous turn's scratch is nobody's), and
+ * Created before each turn without erasing unrecorded or still-required files, and
  * only as a real directory under a real `.flowviant` — the artifacts
  * directory's rule, for its reason: a fence grant on a path through a
  * committed symlink is a write grant on its target. False creates nothing
@@ -149,9 +149,8 @@ export function ensureFenceScratch(placeDir) {
   const dir = join(placeDir, FENCE_TMP_DIR);
   if (flowviantParentState(placeDir) !== 'dir' || realDirState(dir) === 'other') return false;
   try {
-    // A real directory (checked above): its contents go, never through a link.
-    if (realDirState(dir) === 'dir') rmSync(dir, { recursive: true, force: true });
-    mkdirSync(dir);
+    // Reclamation requires a versioned ownership record and released uses.
+    if (realDirState(dir) === 'none') mkdirSync(dir);
   } catch {
     return false;
   }

package/bin/lib/fleet.mjs

@@ -278,6 +278,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     retireWorkSessions,
     reportWorktrees,
     reconcileIdleArtifacts,
+    reconcileLocalCleanup,
     shutdownWork,
     settleAgentTurns,
     workBusy,
@@ -291,6 +292,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     getBaseRef,
     getMcpUrl: () => mcpUrl,
     getLeaseTtl: () => leaseTtlSeconds,
+    getCleanupPermission: () => holderState === 'mine' && !standingDown() && !readMaintenance(),
     /**
      * The cartographer is a CLI turn too, and it is the one this manager cannot
      * see — it lives in the wiki runner (wikiRunner.mjs), not in
@@ -649,6 +651,13 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // once per process, beside no turn (workArtifactReconcile.mjs). After the
     // turn intake above, so a card about to run in a place is not raced.
     void reconcileIdleArtifacts(roster.activeWorkSessions)?.catch(() => {});
+    // First authoritative serving roster triggers startup recovery; later
+    // idle beats are bounded internally. Refresh evidence on every roster so
+    // an in-flight remote check cannot outlive ownership or a peer lease.
+    void reconcileLocalCleanup({ activeIds: roster.activeWorkSessions,
+      heldElsewhere: roster.sessionsHeldElsewhere, serving: holderState === 'mine',
+      draining: standingDown() || Boolean(readMaintenance()),
+    });
     // Terminal-session presence, throttled + dedup'd inside; never awaited —
     // the daemon's own worktrees are carved out (a session the daemon spawned
     // is already a tab, not something to offer adopting).