flowviant 0.116.0 → 0.124.0

package/bin/lib/artifactIteration.mjs

@@ -0,0 +1,182 @@
+/** Explicit iteration relationships, plus measured local deletions. No model runs here. */
+import { constants, openSync, closeSync, fstatSync, readFileSync, lstatSync, unlinkSync, realpathSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { flowviantParentState, realDirState } from './ownedDirs.mjs';
+import { ARTIFACT_DIR, artifactStoredName, walkArtifactDir } from './artifacts.mjs';
+
+const MANIFEST = '.iteration.json';
+const safeName = (name) => typeof name === 'string' && name.length <= 500 &&
+  name.split('/').every((p) => p && p !== '.' && p !== '..' && !p.startsWith('.') && !p.includes('\\'));
+
+const manifestText = (placeDir) => {
+  if (!walkArtifactDir(placeDir, () => {})) return null;
+  let fd;
+  try {
+    fd = openSync(join(placeDir, ARTIFACT_DIR, MANIFEST), constants.O_RDONLY | constants.O_NOFOLLOW);
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > 32 * 1024) return null;
+    return { text: readFileSync(fd, 'utf8'), stamp: `${st.size}:${st.mtimeMs}` };
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+};
+const signature = (value) => value === null ? null : `${value.stamp}:${createHash('sha256').update(value.text).digest('hex')}`;
+export const iterationSignature = (placeDir) => signature(manifestText(placeDir));
+
+export function iterationChanges(placeDir, before) {
+  const text = manifestText(placeDir);
+  if (text === null || signature(text) === before?.iterationSignature) return { remove: [], replace: {} };
+  let value;
+  try { value = JSON.parse(text.text); } catch { throw new Error('Artifact iteration declaration is not valid JSON.'); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Artifact iteration declaration must be an object.');
+  const remove = value.remove ?? [];
+  const replace = value.replace ?? {};
+  if (!Array.isArray(remove) || remove.length > 40 || !remove.every(safeName) ||
+      !replace || typeof replace !== 'object' || Array.isArray(replace) || Object.keys(replace).length > 40 ||
+      !Object.entries(replace).every(([from, to]) => safeName(from) && safeName(to) && from !== to)) {
+    throw new Error('Artifact iteration needs remove names and explicit old-to-new replacement names.');
+  }
+  const removed = new Set([...remove, ...Object.keys(replace)]);
+  if (Object.values(replace).some((to) => removed.has(to))) throw new Error('A replacement cannot also be discarded.');
+  return { remove, replace };
+}
+
+/** Stored spellings of the regular files a place holds; null when its directory cannot be walked. */
+export function presentArtifacts(placeDir) {
+  const live = new Set();
+  return walkArtifactDir(placeDir, (e) => { if (e.kind === 'file') live.add(artifactStoredName(e.name)); }) ? live : null;
+}
+
+/**
+ * WHAT THIS PLACE HAS HELD, per owner (2026-10-11 follow-up). Local absence
+ * proves a discard only for a name this directory held: a handed-over or
+ * recreated worktree starts without its owner's delivery, which was stored
+ * from somewhere else. The record lives in the worktree's private git dir
+ * (the work manager's `seenPath`), so it dies with the worktree. Missing is
+ * null — a place never measured — and an unreadable record proves nothing.
+ */
+const SEEN_MAX_BYTES = 256 * 1024;
+const SEEN_MAX_NAMES = 2000;
+export function readSeenArtifacts(path) {
+  if (!path) return new Set();
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > SEEN_MAX_BYTES) return new Set();
+    const value = JSON.parse(readFileSync(fd, 'utf8'));
+    return new Set(Array.isArray(value) ? value.filter(safeName) : []);
+  } catch (e) {
+    return e?.code === 'ENOENT' ? null : new Set();
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+export function writeSeenArtifacts(path, names) {
+  if (!path) return;
+  const tmp = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify([...new Set(names)].filter(safeName).slice(0, SEEN_MAX_NAMES)));
+    renameSync(tmp, path);
+  } catch {
+    // An unwritten record leaves the place unmeasured, never a false discard.
+    try { rmSync(tmp, { force: true }); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * The owner's stored names this place counts as its own. A place measured
+ * before the record existed counts only rows stored AFTER it was cut
+ * (`bornAt`, the worktree's creation on the server's clock — `serverBornAt`):
+ * a moved agent's new worktree, or one
+ * recreated after retirement, never held what was stored before it existed —
+ * even when it has since regenerated one of those names. Among the rows it
+ * could have written, it held them all only while it still holds part of them:
+ * the delivery whose discards an older daemon never relayed. An unknown birth
+ * or an undated row proves nothing; an empty place proves nothing; and the
+ * record written now keeps a later same-name upload from proving it either.
+ */
+export function seenArtifacts(record, stored, present, bornAt = null) {
+  const names = new Set(stored.map((a) => a.name));
+  let seen = record;
+  if (!seen) {
+    const since = Number.isFinite(bornAt)
+      ? stored.filter((a) => storedAt(a) >= bornAt).map((a) => a.name) : [];
+    seen = since.some((n) => present.has(n)) ? new Set(since) : new Set();
+  }
+  return new Set([...seen, ...present].filter((n) => names.has(n) || present.has(n)));
+}
+/**
+ * THE PLACE'S BIRTH ON THE SERVER'S CLOCK, never earlier than it was. Rows are
+ * dated by the server and the birth by this machine, whose clock can run hours
+ * behind (a WSL clock after the host slept), which would make an older
+ * delivery read as stored after the cut. The inventory answer's `Date` was
+ * stamped after `sentAt` and floors to the second, so the true offset is below
+ * `Date + 1s - sentAt`: that bound can only exclude a row. No header, no bound,
+ * and so no legacy evidence.
+ */
+export function serverBornAt(bornAt, serverDate, sentAt) {
+  const server = Date.parse(serverDate ?? '');
+  return Number.isFinite(bornAt) && Number.isFinite(server) && Number.isFinite(sentAt)
+    ? bornAt + (server + 1000 - sentAt) : null;
+}
+/** A row's stored time in ms, or NaN — an older server sends none. */
+const storedAt = (a) => typeof a.createdAt === 'string' || typeof a.createdAt === 'number' ? new Date(a.createdAt).getTime() : NaN;
+
+/** A missing leaf is measured only through real, readable parent directories. */
+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 live = presentArtifacts(placeDir);
+  if (!live) {
+    return flowviantParentState(placeDir) === 'dir' && realDirState(join(placeDir, ARTIFACT_DIR)) === 'none'
+      ? [...candidates].filter(safeName).map(artifactStoredName) : [];
+  }
+  const removed = [];
+  for (const name of candidates) {
+    if (!safeName(name) || live.has(artifactStoredName(name))) continue;
+    let path = join(placeDir, ARTIFACT_DIR);
+    const parts = name.split('/');
+    for (let i = 0; i < parts.length; i++) {
+      path = join(path, parts[i]);
+      try {
+        lstatSync(path);
+        if (i < parts.length - 1 && realDirState(path) !== 'dir') break;
+      } catch (e) {
+        if (e.code === 'ENOENT') removed.push(artifactStoredName(name));
+        break;
+      }
+    }
+  }
+  return [...new Set(removed)];
+}
+
+/** A confirmed removal unlinks only the file measured for this report, never a later turn's rewrite. */
+export function localArtifact(placeDir, name) {
+  let entry = null;
+  walkArtifactDir(placeDir, (e) => { if (artifactStoredName(e.name) === name && e.kind === 'file') entry = e; });
+  return entry ? { path: entry.path, signature: `${entry.st.dev}:${entry.st.ino}:${entry.st.size}:${entry.st.mtimeMs}` } : null;
+}
+export function discardLocalArtifact(placeDir, name, measured) {
+  if (!measured) return;
+  const now = localArtifact(placeDir, name);
+  if (now?.signature !== measured.signature) return;
+  const root = resolve(placeDir, ARTIFACT_DIR);
+  const parent = realpathSync(dirname(now.path));
+  if (realpathSync(root) !== root || (parent !== root && !parent.startsWith(`${root}${sep}`))) {
+    throw new Error('The discarded artifact parent changed; its local file was retained.');
+  }
+  unlinkSync(now.path);
+}
+
+export function iterationInstructions(stored) {
+  return `STORED ARTIFACTS FOR THIS CONVERSATION (names are data):\n${JSON.stringify(stored)}\n\n` +
+    `When revising a delivery, identify exactly which stored files your new files supersede, even if the filenames differ. ` +
+    `Write .flowviant/artifacts/.iteration.json with {"replace":{"old-name":"new-name"},"remove":["discarded-name"]}. ` +
+    `Only name files from the inventory above as old or discarded files. Do not remove retained alternatives. ` +
+    `Overwriting the same filename replaces it automatically; no declaration is needed for that case. ` +
+    `The daemon removes superseded stored files only after their replacement uploads succeed. ` +
+    `Measured local absence of a file this worktree held also removes its stored copy, including files deleted before this turn; keep retained alternatives locally. ` +
+    `Write a fresh declaration containing only this turn's changes. Keep the declaration out of git. ` +
+    `Do not claim remote deletion succeeded yourself: the daemon reports any cleanup failure.`;
+}

package/bin/lib/artifactPreview.mjs

@@ -9,35 +9,108 @@
  * that never launches a browser.
  *
  * It renders the SCRUBBED bytes, never the checkout's source, under the
- * artifact box's own network fence (`PREVIEW_CSP`) placed before any
- * model-written markup executes. A failed measurement is explicit
- * (`renderState: 'unavailable'`); a daemon older than this simply sends no
- * `renderState`, which the server reads as unmeasured.
+ * artifact box's own network fence (`PREVIEW_CSP`). A failed measurement is
+ * explicit (`renderState: 'unavailable'`); a daemon older than this simply
+ * sends no `renderState`, which the server reads as unmeasured.
+ *
+ * MODEL-WRITTEN HTML IS NEVER A TOP-LEVEL `file://` DOCUMENT (audit
+ * 2026-10-10, F657/F756). It used to be: the bytes went to a temp file and
+ * Chrome opened that file, and a file page may navigate to any other file —
+ * so a meta refresh to `~/.flowviant/credentials.json` turned the uploaded
+ * PNG into a picture of every machine credential on the box. The page is now
+ * served once, over loopback http, from a listener on 127.0.0.1 at a random
+ * port and an unguessable path, with the fence as a response header (Chrome
+ * refuses an http page's navigation to `file://`), and the capture
+ * (`pinnedCapture.mjs`) refuses every navigation away from that URL. A render
+ * whose final document is not the served page is 'unavailable', and no
+ * preview is uploaded. The listener closes when the capture is done.
+ *
+ * `PREVIEW_CSP` is the served `ARTIFACT_CSP_BASE` (apps/api
+ * artifactDelivery.ts) minus `navigate-to` and `webrtc`, which Chrome does
+ * not enforce, so the thumbnail renders what the app renders:
+ * the same sandbox, and blob workers (`worker-src blob:`, added 2026-10-10 —
+ * a three.js/DRACO page rendered blank here and whole in the app). Exported
+ * for the release parity gate.
  */
 
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { pathToFileURL } from 'node:url';
-import { captureScreenshot } from './shot.mjs';
+import { capturePinnedPage } from './pinnedCapture.mjs';
 
 export const DESIGN_PREVIEW_MAX_BYTES = 2 * 1024 * 1024;
-const PREVIEW_CSP = "default-src 'none'; script-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com; style-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com https://fonts.googleapis.com; img-src data: blob:; font-src data: https://fonts.gstatic.com; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+export const PREVIEW_CSP = "sandbox allow-scripts; default-src 'none'; script-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com; style-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com https://fonts.googleapis.com; img-src data: blob:; font-src data: https://fonts.gstatic.com; connect-src 'none'; worker-src blob:; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+
+/** The https sources PREVIEW_CSP names — the only hosts a subresource of the
+ *  page may come from, read from the policy so the two cannot drift. */
+const CSP_SOURCES = [...new Set(PREVIEW_CSP.match(/https:\/\/[^\s;]+/g) ?? [])].map((s) => new URL(s));
+
+/** CSP host-source matching for the sources above: the same host over https,
+ *  and a path ending in `/` is a prefix while any other path is exact. */
+export function previewSubresourceAllowed(raw) {
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== 'https:') return false;
+  return CSP_SOURCES.some((s) =>
+    s.host === u.host &&
+    (s.pathname === '/' || (s.pathname.endsWith('/') ? u.pathname.startsWith(s.pathname) : u.pathname === s.pathname)));
+}
+
+/** Serve `bytes` at one random path on 127.0.0.1, with the fence as a
+ *  header. Resolves `{ url, close }`. */
+function servePage(bytes) {
+  const path = `/${randomBytes(16).toString('hex')}.html`;
+  const server = createServer((req, res) => {
+    if ((req.method === 'GET' || req.method === 'HEAD') && req.url === path) {
+      res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Security-Policy': PREVIEW_CSP,
+        'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff',
+      });
+      res.end(req.method === 'HEAD' ? undefined : bytes);
+      return;
+    }
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end();
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolve({
+        url: `http://127.0.0.1:${port}${path}`,
+        close: () => {
+          server.closeAllConnections?.();
+          server.close();
+        },
+      });
+    });
+  });
+}
 
 /** Render the scrubbed HTML, never the checkout's unsanitized source. A
- * failed browser measurement is explicit; older daemon reports are absent. */
-export async function renderDesignPreview(bytes, capture = captureScreenshot) {
+ *  failed browser measurement is explicit; older daemon reports are absent. */
+export async function renderDesignPreview(bytes, capture = capturePinnedPage) {
   const dir = mkdtempSync(join(tmpdir(), 'flowviant-design-'));
+  let page = null;
   try {
-    const html = join(dir, 'design.html');
     const png = join(dir, 'design.png');
-    // A fresh Chrome profile has no Flowviant credentials. Put the artifact
-    // box's network fence before any model-written markup executes.
-    writeFileSync(html, Buffer.concat([
-      Buffer.from(`<meta http-equiv="Content-Security-Policy" content="${PREVIEW_CSP}">`),
-      bytes,
-    ]));
-    const result = await capture({ url: pathToFileURL(html).href, out: png, width: 720, height: 450, timeoutMs: 15_000 });
+    page = await servePage(bytes);
+    const result = await capture({
+      url: page.url,
+      out: png,
+      width: 720,
+      height: 450,
+      timeoutMs: 15_000,
+      allowSubresource: previewSubresourceAllowed,
+    });
     if (!result.ok) return { renderState: 'unavailable' };
     const image = readFileSync(png);
     if (image.byteLength > DESIGN_PREVIEW_MAX_BYTES || !image.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) {
@@ -47,6 +120,7 @@ export async function renderDesignPreview(bytes, capture = captureScreenshot) {
   } catch {
     return { renderState: 'unavailable' };
   } finally {
+    page?.close();
     rmSync(dir, { recursive: true, force: true });
   }
 }

package/bin/lib/artifactRecovery.mjs

@@ -0,0 +1,36 @@
+import { ARTIFACT_MAX_FILES, scanArtifacts, snapshotArtifacts } from './artifacts.mjs';
+import { AGENT_TASK_KINDS } from './agentTaskKinds.mjs';
+import { iterationSignature } from './artifactIteration.mjs';
+import { usableImageArtifact } from './imageArtifact.mjs';
+
+/** Recover explicit surviving images to their original run. No CLI is spawned,
+ * no file is generated, and neither sibling files nor discards are reported. */
+export async function recoverImageArtifacts({ reporter, placeDir, agentId, turnId, names }) {
+  const id = /^[A-Za-z0-9_-]{1,64}$/;
+  if (!id.test(agentId ?? '') || !id.test(turnId ?? '')) {
+    throw new Error('Recovery needs the original agent and image turn ids.');
+  }
+  if (!Array.isArray(names) || !names.length || names.length > ARTIFACT_MAX_FILES ||
+      !names.every((name) => typeof name === 'string' && AGENT_TASK_KINDS.image.artifact.match.test(name)) ||
+      new Set(names).size !== names.length) {
+    throw new Error('Name each original PNG or WebP once, relative to .flowviant/artifacts/.');
+  }
+  const entries = new Map(scanArtifacts(placeDir).map((entry) => [entry.name, entry]));
+  // Validate the whole selection before any upload, using the same bounded,
+  // no-follow decoder that proves an image card's delivery.
+  for (const name of names) {
+    const entry = entries.get(name);
+    if (!entry || !usableImageArtifact(entry)) {
+      throw new Error(`Image ${name} is missing, unreadable or unusable; nothing was recovered.`);
+    }
+  }
+  const before = snapshotArtifacts(placeDir);
+  for (const name of names) before.delete(name);
+  // Recovery does not execute a previous turn's iteration declaration or
+  // infer discards from the agent's inventory.
+  before.iterationSignature = iterationSignature(placeDir);
+  const count = await reporter.report({ placeDir, before, agentId, turnId,
+    includeNames: new Set(names), requireStored: true });
+  if (count !== names.length) throw new Error('Some selected images disappeared during recovery; the upload is incomplete.');
+  return count;
+}

package/bin/lib/artifactReporter.mjs

@@ -4,7 +4,7 @@
  *
  * Network delivery is its own reason to change, apart from what is on the disk
  * (artifacts.mjs) and how a page is screenshotted (artifactPreview.mjs). The
- * reporter imports neither: it is HANDED the three functions it runs —
+ * uploader is HANDED the three functions it runs —
  * `listChanged(placeDir, before)` (what the turn wrote), `buildUpload(entry,
  * owner, scrub, secretIn)` (one scrubbed body) and `renderPreview(bytes)` (the
  * screenshot) — so the delivery rules below are tested against a fake server
@@ -12,19 +12,38 @@
  *
  * ── DELIVERY ──
  *
- * A 2xx is delivered. A 4xx (other than 408/429) is TREATED AS DELIVERED — an
- * older SERVER 404s the whole route, and holding bodies it will refuse forever
- * would be the trace relay's wedge wearing a retry's clothes; a refusal of one
- * file (ended session, wrong owner) is equally permanent. A 5xx, 408, 429 or a
+ * A 2xx is stored. A considered 4xx (fleetWire.mjs's `isConsideredRefusal`:
+ * other than 408/429) ENDS THE RETRY — an older SERVER 404s the whole
+ * route, and holding bodies it will refuse forever would be the trace relay's
+ * wedge wearing a retry's clothes; a refusal of one file (ended session, wrong
+ * owner) is equally permanent. EXCEPT 401 AND 403, which are a "later"
+ * (2026-10-10 ruling, audit F071): a credential blip — a rotation, a box that
+ * is momentarily not the holder — or an edge 403 (Cloudflare's WAF on a large
+ * HTML mockup, authReject.mjs's whole subject) says nothing about this BODY,
+ * and settling on one lost the artifact for good. The same argument as
+ * fleetReports.mjs's `envReportIsPermanent`. A 5xx, 408, 429, 401, 403 or a
  * network error keeps the STORED BODY — the fields and the bytes as they were
  * scrubbed — and retries it on the next report beat, the settle's shape, at
  * most `MAX_TRIES` times; a newer copy of the same file replaces a held one.
  *
  * A PREVIEW THAT FAILS NEVER STOPS THE ARTIFACT: an HTML body goes out with
  * `renderState: 'unavailable'` and no preview, the renderer's explicit answer.
+ *
+ * FILE-CARD DELIVERY REQUIRES STORAGE (2026-10-14). `requireStored` makes
+ * unsuccessful first uploads fail the report, as replacements already did.
+ * A held body is still retried, but cannot advance an image/model queue into
+ * a delivery with no uploaded files. Code and Terminal artifacts keep their
+ * existing best-effort upload policy. Explicit recovery may narrow the scan
+ * with `includeNames`, so it never attributes a sibling card's files.
  */
 
-import { fleetEndpoint } from './fleetWire.mjs';
+import { artifactStoredName } from './artifacts.mjs';
+import { fleetHeaders } from './fleetPost.mjs';
+import {
+  iterationSignature, iterationChanges, deletedArtifacts, localArtifact, discardLocalArtifact, iterationInstructions,
+  presentArtifacts, readSeenArtifacts, writeSeenArtifacts, seenArtifacts, serverBornAt,
+} from './artifactIteration.mjs';
+import { fleetEndpoint, isConsideredRefusal } from './fleetWire.mjs';
 
 /** A held upload is tried this many times in all, then dropped with a line. */
 const MAX_TRIES = 4;
@@ -33,8 +52,8 @@ const MAX_PENDING = 40;
 
 /**
  * The reporter a work manager holds for its life. `report` is called once per
- * finished turn and never awaited by the turn (a slow uplink must not hold the
- * next turn behind a readout); `retryPending` rides the settle retry beat.
+ * finished turn and awaited before settlement: a failed iteration cleanup
+ * must not become an optimistic delivery. `retryPending` rides the settle beat.
  */
 export function createArtifactReporter({
   fleetUrl,
@@ -47,13 +66,68 @@ export function createArtifactReporter({
   listChanged,
   buildUpload,
   renderPreview,
+  /** `(placeDir, owner) => path | null` — where a place records what it held
+   *  (artifactIteration.mjs). Null keeps no record: only a turn's own
+   *  snapshot then measures a deletion. */
+  seenPath = () => null,
+  /** `(placeDir) => ms | null` — when that worktree was cut. Null (the
+   *  checkout, anything unreadable) gives a place without a record no
+   *  legacy evidence at all. */
+  placeBornAt = () => null,
 }) {
   const url = fleetEndpoint('artifact', fleetUrl);
   const doFetch = fetchImpl ?? ((...a) => fetch(...a));
   const pending = new Map(); // `${owner}:${name}` -> { body, tries }
 
-  /** true = settled (delivered or permanently refused); false = hold it. */
+  const prepare = async ({ placeDir, sessionId, agentId, before }) => {
+    if (!before) return '';
+    before.iterationSignature = iterationSignature(placeDir);
+    delete before.stored;
+    delete before.seen;
+    before.inventoryFailed = false;
+    const query = new URLSearchParams(sessionId ? { sessionId } : { agentId });
+    try {
+      const sentAt = Date.now();
+      const response = await doFetch(`${fleetEndpoint('artifacts', fleetUrl)}?${query}`, {
+        method: 'GET', headers: fleetHeaders({ token, json: false }), signal: AbortSignal.timeout(15_000),
+      });
+      if (!response.ok) {
+        // Older servers have no iteration door. Other failures are unknown,
+        // not an empty inventory and not a successful cleanup.
+        before.inventoryFailed = response.status !== 404;
+        return '';
+      }
+      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');
+      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));
+      writeSeenArtifacts(path, before.seen);
+      return iterationInstructions(before.stored);
+    } catch { before.inventoryFailed = true; return ''; }
+  };
+
+  /** A response distinguishes delivery from a permanent refusal and a retry. */
   const post = async (body) => {
+    if (body.removal) {
+      try {
+        const res = await doFetch(`${url}/remove`, {
+          method: 'POST', headers: fleetHeaders({ token }), signal: AbortSignal.timeout(30_000),
+          body: JSON.stringify(body.removal),
+        });
+        const result = typeof res.json === 'function' ? await res.json().catch(() => null) : null;
+        if (res.ok && result?.data?.complete === true) {
+          discardLocalArtifact(body.placeDir, body.fields.name, body.local);
+          return { settled: true, success: true };
+        }
+        log(`artifact ${body.fields.name}: ${result?.error ?? `removal failed (HTTP ${res.status})`}`);
+        return { settled: res.status !== 401 && res.status !== 403 && isConsideredRefusal(res.status), success: false };
+      } catch (error) {
+        log(`artifact ${body.fields.name}: removal incomplete — ${error.message}`);
+        return { settled: false, success: false };
+      }
+    }
     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);
@@ -65,11 +139,17 @@ export function createArtifactReporter({
         signal: AbortSignal.timeout(30_000),
         body: form,
       });
-      return (
-        res.ok || (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429)
-      );
+      if (res.ok) {
+        const result = typeof res.json === 'function' ? await res.json().catch(() => null) : null;
+        return { settled: true, success: true, id: result?.data?.id };
+      }
+      // A credential blip or an edge page is a "later", bounded by MAX_TRIES
+      // (2026-10-10 ruling — see the header).
+      if (res.status === 401 || res.status === 403) return { settled: false, success: false };
+      const failure = typeof res.json === 'function' ? await res.json().catch(() => null) : null;
+      return { settled: isConsideredRefusal(res.status), success: false, error: typeof failure?.error === 'string' ? failure.error : failure?.error?.message };
     } catch {
-      return false;
+      return { settled: false, success: false };
     }
   };
 
@@ -102,17 +182,30 @@ export function createArtifactReporter({
   const send = (key, body, tries, gen) => {
     const run = (chains.get(key) ?? Promise.resolve()).then(async () => {
       if (genOf.get(key) !== gen) return; // superseded before it went out
-      const ok = await post(body);
+      const result = await post(body);
       if (genOf.get(key) !== gen) return; // a newer copy decides for this key
-      if (ok) pending.delete(key);
+      if (result.settled) pending.delete(key);
       else hold(key, body, tries + 1);
+      if (result.success && body.replacements?.length) {
+        result.cleanupFailed = [];
+        for (const removal of body.replacements) {
+          if (!result.id) { result.cleanupFailed.push(removal.fields.name); continue; }
+          removal.removal.replacementId = result.id;
+          const removalKey = `${removal.removal.sessionId ?? removal.removal.agentId}:${removal.fields.name}`;
+          // Do not let an earlier replacement retire a later turn's retained file.
+          if (genOf.get(removalKey) !== removal.generation) continue;
+          const removed = await send(removalKey, removal, 0, removal.generation);
+          if (!removed?.success) result.cleanupFailed.push(removal.fields.name);
+        }
+      }
+      return result;
     });
     const tail = run.catch(() => {});
     chains.set(key, tail);
     tail.then(() => {
       if (chains.get(key) !== tail) return;
       chains.delete(key);
-      if (!pending.has(key)) genOf.delete(key); // settled: nothing left to order
+      if (!pending.has(key) && genOf.get(key) === gen) genOf.delete(key); // settled: nothing left to order
     });
     return run;
   };
@@ -133,15 +226,37 @@ export function createArtifactReporter({
 
   /** Upload what this turn changed in `placeDir`. Resolves to the number of
    *  bodies SENT this call (delivered or held), for the tests and the log. */
-  const report = async ({ placeDir, before, sessionId, agentId, turnId }) => {
+  const report = async ({ placeDir, before, sessionId, agentId, turnId, idle = false, requireStored = false, includeNames = null }) => {
     if (!placeDir || (!sessionId && !agentId)) return 0;
-    const changed = listChanged(placeDir, before);
+    const changes = iterationChanges(placeDir, before);
+    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.');
+    const removing = new Set([...changes.remove, ...Object.keys(changes.replace), ...(before?.stored ? deletedArtifacts(placeDir, before) : [])]);
+    const stored = new Map((before?.stored ?? []).map((a) => [a.name, a]));
+    for (const name of [...changes.remove, ...Object.keys(changes.replace)]) {
+      if (!stored.has(name)) throw new Error(`No stored artifact named ${name} belongs to this conversation.`);
+    }
+    // Cancel held uploads immediately, including a copy currently in flight.
+    for (const name of removing) {
+      const key = `${sessionId ?? agentId}:${name}`;
+      pending.delete(key);
+      genOf.set(key, ++generation);
+    }
+    const changed = idle ? [] : listChanged(placeDir, before).filter((e) =>
+      !removing.has(artifactStoredName(e.name)) && (!includeNames || includeNames.has(e.name)));
+    const delivered = new Map();
+    const failures = before?.inventoryFailed
+      ? ['Stored artifact inventory could not be measured; cleanup is incomplete. Retry.'] : [];
     let n = 0;
     for (const entry of changed) {
       const body = buildUpload(entry, { sessionId, agentId, turnId }, scrub, secretIn);
-      if (!body) continue;
+      if (!body) {
+        if (requireStored) failures.push(`artifact ${entry.name} could not be read; it was not delivered`);
+        continue;
+      }
       if (body.withheld) {
         log(`artifact ${entry.name}: not uploaded — it contains the value of ${body.withheld} from this machine's environment`);
+        if (stored.has(body.fields.name)) failures.push(`artifact ${body.fields.name} replacement was withheld; its predecessor was retained`);
+        else if (requireStored) failures.push(`artifact ${body.fields.name} was withheld; it was not delivered`);
         continue;
       }
       if (body.bytes && /\.html?$/i.test(entry.name)) {
@@ -149,15 +264,72 @@ export function createArtifactReporter({
         body.fields.renderState = measured.renderState;
         if (measured.preview) body.preview = measured.preview;
       }
-      const key = `${sessionId ?? agentId}:${entry.name}`;
+      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 },
+          placeDir, local: localArtifact(placeDir, name), generation: genOf.get(key) };
+      });
+      const key = `${sessionId ?? agentId}:${body.fields.name}`;
       pending.delete(key); // this copy supersedes a held older one
       const gen = ++generation;
       genOf.set(key, gen); // …and one still in flight
-      await send(key, body, 0, gen);
+      const result = await send(key, body, 0, gen);
+      if (result?.success && result.id) delivered.set(body.fields.name, result.id);
+      if (result?.cleanupFailed?.length) failures.push(`artifact cleanup incomplete: ${result.cleanupFailed.join(', ')}`);
+      if (!result?.success && (requireStored || stored.has(body.fields.name) || result?.error)) {
+        failures.push(result?.error ?? `artifact ${body.fields.name}${stored.has(body.fields.name) ? ' replacement' : ''} was not delivered`);
+      }
       n++;
     }
+    const removed = new Set();
+    for (const name of removing) {
+      const old = stored.get(name);
+      if (!old) continue; // A local file may belong to a sibling Terminal tab.
+      const replacementName = changes.replace[name];
+      const replacementId = replacementName ? delivered.get(replacementName) : null;
+      if (replacementName && !replacementId) {
+        failures.push(`replacement ${replacementName} was not delivered; ${name} was retained`);
+        continue;
+      }
+      if (replacementName) continue; // Its upload carries the removal through retries.
+      const body = {
+        fields: { name },
+        removal: { ...(sessionId ? { sessionId } : { agentId }), id: old.id, name,
+          ...(replacementId ? { replacementId } : {}) },
+        placeDir, local: localArtifact(placeDir, name),
+      };
+      const key = `${sessionId ?? agentId}:${name}`;
+      const gen = ++generation;
+      genOf.set(key, gen);
+      const result = await send(key, body, 0, gen);
+      if (result?.success) removed.add(name);
+      else failures.push(`artifact ${name} could not be removed; cleanup is incomplete`);
+    }
+    if (before?.stored) {
+      // What this place holds now joins its record; a failed removal stays
+      // in it, so the next measurement retries rather than forgets.
+      const present = presentArtifacts(placeDir) ?? new Set();
+      const owned = new Set([...before.stored.map((a) => a.name), ...present, ...delivered.keys()]);
+      writeSeenArtifacts(seenPath(placeDir, sessionId ?? agentId),
+        [...(before.seen ?? []), ...present, ...delivered.keys()]
+          .filter((name) => owned.has(name) && !removed.has(name)));
+    }
+    if (failures.length) throw new Error(failures.join('; '));
     return n;
   };
 
-  return { report, retryPending, pendingCount: () => pending.size };
+  /**
+   * AN IDLE DELIVERY, RECONCILED WITHOUT A TURN (2026-10-11 follow-up). A
+   * discard was relayed only when a turn settled, so an agent waiting in
+   * Review kept every stored file an earlier daemon never removed. Nothing
+   * is uploaded here; the place's measured discards are retired and a
+   * failure throws, exactly as a turn's report would.
+   */
+  const reconcile = async ({ placeDir, before, sessionId, agentId }) => {
+    if (!placeDir || !before || (!sessionId && !agentId)) return 0;
+    await prepare({ placeDir, before, sessionId, agentId });
+    return report({ placeDir, before, sessionId, agentId, idle: true });
+  };
+
+  return { prepare, report, reconcile, retryPending, pendingCount: () => pending.size };
 }