flowviant 0.102.2 → 0.104.0

package/bin/lib/admission.mjs

@@ -80,7 +80,23 @@
  */
 
 import { MAX_CONCURRENT, MAX_CONCURRENT_FROM_ENV } from './config.mjs';
-import { pressureVerdict } from './resources.mjs';
+import { measurePressure } from './resources.mjs';
+import { pressureVerdict, readPressureThresholds } from './pressurePolicy.mjs';
+
+/**
+ * THE PRESSURE HALF OF AN ADMISSION, AS THE DAEMON ASKS IT: this box's
+ * (briefly cached) measurement, judged against the thresholds the environment
+ * states AT THIS CALL. Both are read per decision — an operator who exports
+ * `FLOWVIANT_MIN_FREE_MB` into a running daemon's environment is heard on the
+ * next spawn. Injectable only so that promise can be pinned; `createAdmission`
+ * passes nothing. A guard switched off measures nothing (no `vm_stat` spawn
+ * per decision on macOS), as before the split.
+ */
+export function livePressureVerdict(level, { measure = measurePressure, env = process.env } = {}) {
+  const thresholds = readPressureThresholds(env);
+  if (thresholds.off) return null;
+  return pressureVerdict(level, measure(), thresholds);
+}
 
 /**
  * ── THE CEILING HAS THREE POSSIBLE AUTHORS (2026-09-17) ──
@@ -127,7 +143,7 @@ export function pickMaxTurns({ env = null, server = null, derived = 1 } = {}) {
  * A module holder rather than a value threaded through `createWorkManager`,
  * because the reader and the writer are two files apart and one poll apart: the
  * POLL learns it (fleet.mjs) and every ADMISSION reads it, including the ones
- * work.mjs takes in lanes fleet.mjs never sees. The alternative — passing it
+ * the work manager takes in lanes fleet.mjs never sees (workChildren.mjs builds it). The alternative — passing it
  * down — would mean the number that bound a spawn was whatever was current when
  * the manager was CONSTRUCTED, which is exactly the frozen-at-startup bug
  * `getBaseRef` and `getLeaseTtl` are getters to avoid.
@@ -171,7 +187,7 @@ export function createAdmission({
    *  A number is still accepted, and every test here passes one — the whole
    *  point of injecting it. */
   maxConcurrent = effectiveMaxTurns,
-  verdict = pressureVerdict,
+  verdict = livePressureVerdict,
 } = {}) {
   /** Slots taken by a decision whose process does not exist yet. A Set of
    *  tokens rather than a counter: a double release then costs nothing, which

package/bin/lib/agentPlan.mjs

@@ -27,7 +27,7 @@
 
 // THE UPLINK SCRUBBER, as the DEFAULT for the two readers whose every string
 // goes to the server (2026-09-24, the audit). See `parseTurnResult`.
-import { scrub as envScrub } from './env.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
 
 /** The biggest a single proposal may be. Bounds on a machine, not a policy:
  *  the server caps these again at its own boundary. */
@@ -277,7 +277,7 @@ function uniqueTempIds(list) {
  * summary and the wire, and a cap must never run ahead of it. So this is the
  * same absurdity bound `summary` takes one line up (8000): enough that nothing
  * a model writes reaches the caller unbounded, far enough above the 1000 the
- * wire cuts to that the scrub always sees whole values. `work.mjs` scrubs and
+ * wire cuts to that the scrub always sees whole values. `workAgentTurns.mjs` scrubs and
  * THEN cuts to 1000, and the server clamps again because the wire never trusts
  * a machine to have clamped.
  */

package/bin/lib/agentTaskKinds.mjs

@@ -0,0 +1,93 @@
+/**
+ * A CARD'S KIND — the daemon's one table of what each kind IS (0.97.0):
+ * `code` (the default), `design` and `research`. Every reader of a kind goes
+ * through this module: the prompts that print it and pick a contract
+ * (prompts.mjs, which keeps the strings), the agent lane that picks a posture,
+ * refuses a runtime (workAgentTurnExecution.mjs) and checks the artifact
+ * (workAgentTurnOutcome.mjs), and the turn runner that fences the non-code
+ * postures (runTurn.mjs and claudePosture.mjs, via turnProfile.mjs).
+ *
+ * Split out (SOLID F041) because the kind was branched on at five sites — the
+ * vocabulary twice in prompts.mjs, the posture and the artifact rule in the
+ * agent lane, the posture names again in claude.mjs — so a fourth kind was a
+ * coordinated edit whose missed site ran a card under the wrong posture. Now a
+ * kind is one entry here, and `agentTaskKinds.test.mjs` proves every entry has
+ * a contract, a posture a runtime can declare, and (for a non-code kind) the
+ * artifact that proves it delivered.
+ *
+ * Pure data and pure functions: no imports, no environment, no I/O — prompts
+ * imports it, and prompts is strings.
+ */
+
+/**
+ * The kinds. Per kind:
+ *  - `posture`: the turn profile the card runs under (turnProfile.mjs);
+ *  - `artifact`: null for code (it delivers commits), else what proves a
+ *    delivery — `match` over the artifact file name and the `missing`
+ *    sentence a turn settles `nothing` with when none was written;
+ *  - `offRuntime(rt)`: the sentence when the chosen CLI cannot run the posture.
+ */
+export const AGENT_TASK_KINDS = Object.freeze({
+  code: Object.freeze({
+    posture: 'build',
+    artifact: null,
+    offRuntime: (rt) => `this machine cannot run ${rt}`,
+  }),
+  design: Object.freeze({
+    posture: 'design',
+    artifact: Object.freeze({
+      match: /\.html?$/i,
+      missing: 'the turn ended without writing a mockup under .flowviant/artifacts/',
+    }),
+    offRuntime: () => 'design and research cards run on Claude on this machine',
+  }),
+  research: Object.freeze({
+    posture: 'research',
+    artifact: Object.freeze({
+      match: /\.md$/i,
+      missing: 'the turn ended without writing a write-up under .flowviant/artifacts/',
+    }),
+    offRuntime: () => 'design and research cards run on Claude on this machine',
+  }),
+});
+
+const known = (v) => typeof v === 'string' && Object.hasOwn(AGENT_TASK_KINDS, v);
+
+/**
+ * A CARD'S KIND, READ THE ONE WAY THE DAEMON READS IT.
+ *
+ * The server sends the key only for non-code kinds, so ABSENT IS CODE, and an
+ * unknown string (a newer server, a typo) degrades to code: the one kind that
+ * changes nothing about how a card is PRINTED. Every printing reader — the
+ * contract selector, the kickoff, the spec — goes through this, so no two of
+ * them can disagree about what an odd value means.
+ */
+export const agentTaskKindOf = (v) => (known(v) ? v : 'code');
+
+/**
+ * …EXCEPT WHERE A TURN IS ABOUT TO SPAWN (2026-09-23). "Unknown degrades to
+ * code" is right for every reader that only PRINTS the kind, and wrong for the
+ * one that picks a POSTURE: code is the build turn, permissions skipped, so a
+ * kind a newer server invented for a card that must not touch the code (a
+ * fourth kind, a typo, `Design`) would have run as exactly the turn it exists
+ * to prevent. The agent lane asks this first and refuses in words, relaying
+ * the word it was handed. Absent, null and empty stay code — that is how a
+ * code card arrives.
+ *
+ * @returns {string|null} the unrecognised value, or null when the kind is one
+ *   this daemon runs.
+ */
+export const unknownAgentTaskKind = (v) =>
+  v === undefined || v === null || v === '' || known(v)
+    ? null
+    : String(v).replace(/[\u0000-\u001f\u007f]/g, '').slice(0, 40);
+
+/** The table entry for a kind value, read the printing way (unknown → code). */
+export const agentTaskKind = (v) => AGENT_TASK_KINDS[agentTaskKindOf(v)];
+
+/** The postures only a card's kind selects (every kind's but code's). */
+export const KIND_POSTURES = Object.freeze(
+  Object.values(AGENT_TASK_KINDS)
+    .map((k) => k.posture)
+    .filter((p) => p !== 'build')
+);

package/bin/lib/agySessions.mjs

@@ -0,0 +1,158 @@
+/**
+ * ANTIGRAVITY (agy) SESSION PRESENCE (split out of localSessions.mjs
+ * 2026-09-26, SOLID F062). agy's SQLite store, its cwd cache and its
+ * process-name liveness change for reasons of their own, apart from Claude's
+ * transcript format (claudeSessions.mjs); the shared fence and report cap are
+ * the coordinator's (localSessions.mjs).
+ *
+ * NOTHING in this file throws.
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { procPids, scanProcs } from './procScan.mjs';
+
+// agy's store is nothing like Claude's: one SQLite db per conversation at
+// ~/.gemini/antigravity-cli/conversations/<uuid>.db (global, not cwd-keyed),
+// no per-pid liveness registry that survives contact (the presence/*.lock
+// files sit untouched by real runs — measured), and the only cwd mapping is
+// cache/last_conversations.json: {cwd → the LAST conversation run there}.
+// So the honest agy report is a SUBSET — the last conversation per directory
+// inside this repo — and that is exactly the one `agy --continue` would give
+// the person at that keyboard, i.e. the one worth offering to adopt.
+
+const AGY_DIR = () => join(homedir(), '.gemini', 'antigravity-cli');
+const AGY_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Newest write to the conversation's store — the wal carries recent turns,
+ *  so its mtime (not the db's) is the real "last active" (measured: a resume
+ *  touched db+wal, and never the presence lock). 0 = no such conversation. */
+function agyLastWriteMs(id) {
+  if (!AGY_UUID_RE.test(id)) return 0;
+  let newest = 0;
+  for (const suffix of ['.db', '.db-wal']) {
+    try {
+      const t = statSync(join(AGY_DIR(), 'conversations', `${id}${suffix}`)).mtimeMs;
+      if (t > newest) newest = t;
+    } catch {
+      /* absent half is fine — the db alone still answers */
+    }
+  }
+  return newest;
+}
+
+/** Any agy process on the machine right now? /proc comm scan — cheap at the
+ *  60s cadence, and the only liveness signal agy leaves (locks are inert).
+ *  Tri-state on purpose: true (an agy process exists), false (scanned /proc
+ *  and found none), null (no /proc to scan — macOS — so the question is
+ *  UNANSWERABLE here, which is a different fact from "no", and the adoption
+ *  path below treats it differently: unknowable refuses, absent permits). */
+function agyProcessAlive() {
+  if (!existsSync('/proc')) {
+    // No /proc (macOS): ask pgrep the same question. A MEASURED "none" here
+    // matters — answering null instead made every agy conversation on such a
+    // machine read live forever, which both invented a state ("live" when the
+    // truth was "unmeasured") and permanently killed agy adoption there.
+    try {
+      execFileSync('pgrep', ['-x', 'agy'], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 5_000,
+      });
+      return true; // exit 0 — at least one agy process
+    } catch (e) {
+      if (e?.status === 1) return false; // pgrep ran and found none
+      return null; // pgrep itself unavailable/errored — genuinely unknowable
+    }
+  }
+  // The /proc walk is procScan's (every pid looked at; a bound of ONE row,
+  // because the first agy answers the question).
+  const pids = procPids();
+  if (pids === null) return null; // /proc exists but won't read — still unknowable
+  const isAgy = (name) => {
+    try {
+      return readFileSync(`/proc/${name}/comm`, 'utf8').trim() === 'agy' ? true : null;
+    } catch {
+      return null; // raced exit — keep scanning
+    }
+  };
+  return scanProcs(pids, isAgy, 1).rows.length > 0;
+}
+
+/**
+ * Is this agy conversation being driven RIGHT NOW? agy cannot answer
+ * per-conversation, so this is the conservative composite: an agy process
+ * exists AND this conversation's store was written in the last 10 minutes.
+ * Adoption is a MOVE for agy (no fork exists — measured, "trajectory not
+ * found" on a renamed copy), so refusing a maybe-live conversation for a few
+ * minutes costs a retry; adopting an actually-live one puts two drivers on
+ * one store.
+ */
+const AGY_LIVE_WINDOW_MS = 10 * 60 * 1000;
+export function isAgyConversationLive(id, { processAlive = agyProcessAlive } = {}) {
+  try {
+    const up = processAlive();
+    // Unknowable is NOT "ended". Without /proc the process half of the
+    // composite cannot be measured, and calling that "no process" would make
+    // every agy conversation on such a machine adoptable — the move-adoption
+    // then puts a second driver on a store someone may still be writing.
+    // "Live" here means "refuse adoption", and refusing what we cannot verify
+    // is the same conservatism as the composite itself.
+    if (up === null) return true;
+    if (!up) return false;
+    const t = agyLastWriteMs(id);
+    return t > 0 && Date.now() - t < AGY_LIVE_WINDOW_MS;
+  } catch {
+    return false;
+  }
+}
+
+/** The repo's agy conversations, via the cwd registry — see the section
+ *  comment for why this is deliberately a subset. The coordinator hands over
+ *  the fence (`ours`, `mine`) and the ended-session `cutoff`; `processAlive`
+ *  measures liveness (true / false / null = unknowable), asked once and only
+ *  when there is a registry to read. */
+export function scanAgyConversations({ ours, mine, cutoff, processAlive = agyProcessAlive }) {
+  const out = [];
+  try {
+    const raw = readFileSync(join(AGY_DIR(), 'cache', 'last_conversations.json'), 'utf8');
+    const map = JSON.parse(raw);
+    if (!map || typeof map !== 'object') return out;
+    const processUp = processAlive();
+    for (const [cwd, id] of Object.entries(map)) {
+      if (typeof id !== 'string' || !AGY_UUID_RE.test(id)) continue;
+      // The operator's own agy TAB, whose conversation is registered against
+      // the checkout exactly as a terminal one would be.
+      if (mine.has(id)) continue;
+      let real;
+      try {
+        real = realpathSync(cwd);
+      } catch {
+        continue; // the directory is gone — nothing to point a tab at
+      }
+      if (!ours(real)) continue;
+      const lastMs = agyLastWriteMs(id);
+      if (!lastMs || lastMs < cutoff) continue;
+      out.push({
+        id,
+        cwd: real,
+        // Mirrors isAgyConversationLive exactly, unknowable (null) included:
+        // the report must never offer as adoptable a conversation the adopt
+        // path will then refuse — an offer wired to a refusal is the dead
+        // control this product keeps deleting.
+        live: processUp === null ? true : processUp && Date.now() - lastMs < AGY_LIVE_WINDOW_MS,
+        lastActiveAt: new Date(lastMs).toISOString(),
+        runtime: 'antigravity',
+      });
+    }
+    out.sort(
+      (a, b) =>
+        (b.lastActiveAt < a.lastActiveAt ? -1 : b.lastActiveAt > a.lastActiveAt ? 1 : 0) ||
+        (a.id < b.id ? -1 : 1)
+    );
+  } catch {
+    /* no agy on this machine, or an unreadable registry — nothing to report */
+  }
+  return out;
+}

package/bin/lib/artifactPolicy.mjs

@@ -0,0 +1,44 @@
+/**
+ * THE ARTIFACT POLICY — GENERATED, DO NOT EDIT BY HAND.
+ *
+ * Rendered from the server's packages/shared/src/schemas/artifact.schema.ts
+ * by flowviant's packages/shared/src/schemas/daemonArtifactPolicy.ts
+ * (`bun scripts/write-daemon-artifact-policy.ts` in the app repo). The server
+ * is the release source; its parity test fails until this file matches it.
+ * artifacts.mjs reads the allowlist and the caps from here, and the server
+ * still verifies every upload on its own.
+ */
+
+export const ARTIFACT_POLICY_SOURCE = 'packages/shared/src/schemas/artifact.schema.ts';
+
+/** Per text file and ordinary binary artifact. */
+export const ARTIFACT_MAX_BYTES = 2097152;
+/** Binary model buffers (the extensions below). */
+export const ARTIFACT_BINARY_MODEL_MAX_BYTES = 20971520;
+export const ARTIFACT_BINARY_MODEL_EXTS = ['glb', 'bin'];
+/** Per session and per agent — the server keeps as many per owner. */
+export const ARTIFACT_MAX_PER_OWNER = 40;
+
+/** Extension → the one mime the server serves it under; `text` is scrubbed. */
+export const ARTIFACT_TYPES = {
+  html: { mime: 'text/html', text: true },
+  htm: { mime: 'text/html', text: true },
+  md: { mime: 'text/markdown', text: true },
+  svg: { mime: 'image/svg+xml', text: true },
+  png: { mime: 'image/png', text: false },
+  jpg: { mime: 'image/jpeg', text: false },
+  jpeg: { mime: 'image/jpeg', text: false },
+  gif: { mime: 'image/gif', text: false },
+  webp: { mime: 'image/webp', text: false },
+  json: { mime: 'application/json', text: true },
+  csv: { mime: 'text/csv', text: true },
+  txt: { mime: 'text/plain', text: true },
+  docx: { mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', text: false },
+  pptx: { mime: 'application/vnd.openxmlformats-officedocument.presentationml.presentation', text: false },
+  xlsx: { mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', text: false },
+  pdf: { mime: 'application/pdf', text: false },
+  gltf: { mime: 'model/gltf+json', text: true },
+  obj: { mime: 'model/obj', text: true },
+  glb: { mime: 'model/gltf-binary', text: false },
+  bin: { mime: 'application/octet-stream', text: false },
+};

package/bin/lib/artifactPreview.mjs

@@ -0,0 +1,52 @@
+/**
+ * THE DESIGN PREVIEW — a screenshot of an HTML artifact, taken in a browser
+ * (2026-09-26, split out of artifacts.mjs — SOLID F051).
+ *
+ * Browser rendering is its own reason to change: a Chrome flag, a CSP tweak or
+ * a viewport size has nothing to do with how the artifact directory is scanned
+ * or how an upload is retried. The reporter (`artifactReporter.mjs`) is handed
+ * this function rather than importing it, so a test can stand in a renderer
+ * 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.
+ */
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { captureScreenshot } from './shot.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'";
+
+/** 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) {
+  const dir = mkdtempSync(join(tmpdir(), 'flowviant-design-'));
+  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 });
+    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]))) {
+      return { renderState: 'unavailable' };
+    }
+    return { renderState: 'rendered', preview: image };
+  } catch {
+    return { renderState: 'unavailable' };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/bin/lib/artifactReporter.mjs

@@ -0,0 +1,163 @@
+/**
+ * THE ARTIFACT REPORTER — the queued POST to `/fleet/artifact` and its bounded
+ * retries (2026-09-26, split out of artifacts.mjs — SOLID F051).
+ *
+ * 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 —
+ * `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
+ * and a fake renderer, and a new source of bodies would not edit this file.
+ *
+ * ── 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
+ * 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.
+ */
+
+import { fleetEndpoint } from './fleetWire.mjs';
+
+/** A held upload is tried this many times in all, then dropped with a line. */
+const MAX_TRIES = 4;
+/** Held bodies across every owner — each can be two megabytes. */
+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.
+ */
+export function createArtifactReporter({
+  fleetUrl,
+  token,
+  userAgent,
+  scrub,
+  secretIn,
+  fetchImpl,
+  log = () => {},
+  listChanged,
+  buildUpload,
+  renderPreview,
+}) {
+  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 post = async (body) => {
+    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);
+    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 },
+        signal: AbortSignal.timeout(30_000),
+        body: form,
+      });
+      return (
+        res.ok || (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429)
+      );
+    } catch {
+      return false;
+    }
+  };
+
+  const hold = (key, body, tries) => {
+    if (tries >= MAX_TRIES) {
+      pending.delete(key);
+      log(`artifact ${body.fields.name}: not delivered after ${tries} tries — dropped`);
+      return;
+    }
+    pending.delete(key); // re-insert at the tail, so the cap sheds the oldest
+    pending.set(key, { body, tries });
+    while (pending.size > MAX_PENDING) {
+      const shed = pending.keys().next().value;
+      pending.delete(shed);
+      if (!chains.has(shed)) genOf.delete(shed);
+    }
+  };
+
+  // ONE COPY OF A FILE IS IN FLIGHT AT A TIME, AND ONLY THE NEWEST MAY
+  // DECIDE. Each report of a (owner, name) takes a fresh generation, and every
+  // post for that key is chained behind the previous one — so a slow retry of
+  // an OLD body can neither land on the server after the newer copy (the
+  // server upserts by name, so the last write wins) nor re-hold itself over
+  // the newer one when it fails. A body superseded before it went out is not
+  // sent at all; one superseded while in flight has its answer discarded.
+  let generation = 0;
+  const genOf = new Map(); // key -> the generation allowed to decide
+  const chains = new Map(); // key -> the tail of that key's post chain
+
+  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);
+      if (genOf.get(key) !== gen) return; // a newer copy decides for this key
+      if (ok) pending.delete(key);
+      else hold(key, body, tries + 1);
+    });
+    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
+    });
+    return run;
+  };
+
+  let retrying = false;
+  const retryPending = async () => {
+    if (retrying || pending.size === 0) return;
+    retrying = true;
+    try {
+      for (const [key, held] of [...pending]) {
+        if (pending.get(key) !== held) continue; // superseded meanwhile
+        await send(key, held.body, held.tries, genOf.get(key));
+      }
+    } finally {
+      retrying = false;
+    }
+  };
+
+  /** 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 }) => {
+    if (!placeDir || (!sessionId && !agentId)) return 0;
+    const changed = listChanged(placeDir, before);
+    let n = 0;
+    for (const entry of changed) {
+      const body = buildUpload(entry, { sessionId, agentId, turnId }, scrub, secretIn);
+      if (!body) continue;
+      if (body.withheld) {
+        log(`artifact ${entry.name}: not uploaded — it contains the value of ${body.withheld} from this machine's environment`);
+        continue;
+      }
+      if (body.bytes && /\.html?$/i.test(entry.name)) {
+        const measured = await renderPreview(body.bytes);
+        body.fields.renderState = measured.renderState;
+        if (measured.preview) body.preview = measured.preview;
+      }
+      const key = `${sessionId ?? agentId}:${entry.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);
+      n++;
+    }
+    return n;
+  };
+
+  return { report, retryPending, pendingCount: () => pending.size };
+}