flowviant 0.103.0 → 0.105.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,130 @@
+/**
+ * A CARD'S KIND — the daemon's one table of what each kind IS (0.97.0):
+ * `code` (the default), `design` and `research`; since 0.105.0 also `model`
+ * (the 3D-model kind — not an AI-model pin, which is `job.model`) and `deck`
+ * (the presentation kind — not the review deck). Every reader of a kind goes
+ * through this module: the prompts that print it and pick a contract
+ * (prompts.mjs, which keeps the strings, with the 3D-model and presentation
+ * contracts and the shared tail in artifactContracts.mjs), 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, an optional `companion`
+ *    that must ALSO stand beside it (the 3D-model kind's model file: an HTML
+ *    viewer alone is a page, not a model), and the `missing` sentence a turn
+ *    settles `nothing` with when the proof was not written;
+ *  - `offRuntime(rt)`: the sentence when the chosen CLI cannot run the posture.
+ */
+/** Every non-code kind runs on Claude: the one CLI that declares their postures. */
+const CLAUDE_ONLY = 'mockup, 3D model, presentation and write-up cards run on Claude on this machine';
+
+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: () => CLAUDE_ONLY,
+  }),
+  /**
+   * THE 3D-MODEL KIND (0.105.0): a viewable bundle — an HTML viewer and the
+   * model files beside it. Under the design fence (read the repo, write only
+   * `.flowviant/artifacts/**`): a model is a picture of an asset, and
+   * committing it is a separate code card a person raises at Accept.
+   */
+  model: Object.freeze({
+    posture: 'design',
+    artifact: Object.freeze({
+      match: /\.html?$/i,
+      companion: /\.(gltf|glb|obj)$/i,
+      missing:
+        'the turn ended without writing a model bundle (an HTML viewer and a .gltf, .glb or .obj file) under .flowviant/artifacts/',
+    }),
+    offRuntime: () => CLAUDE_ONLY,
+  }),
+  /** THE PRESENTATION KIND (0.105.0): one HTML slide deck, under the design fence. */
+  deck: Object.freeze({
+    posture: 'design',
+    artifact: Object.freeze({
+      match: /\.html?$/i,
+      missing: 'the turn ended without writing a deck under .flowviant/artifacts/',
+    }),
+    offRuntime: () => CLAUDE_ONLY,
+  }),
+  research: Object.freeze({
+    posture: 'research',
+    artifact: Object.freeze({
+      match: /\.md$/i,
+      missing: 'the turn ended without writing a write-up under .flowviant/artifacts/',
+    }),
+    offRuntime: () => CLAUDE_ONLY,
+  }),
+});
+
+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), each
+ *  once: the 3D-model and presentation kinds reuse the design posture. */
+export const KIND_POSTURES = Object.freeze([
+  ...new Set(
+    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/artifactContracts.mjs

@@ -0,0 +1,153 @@
+/**
+ * THE 3D-MODEL AND PRESENTATION CARDS' CONTRACTS (2026-09-27, 0.105.0).
+ *
+ * Two more kinds that hand back a file rather than a change, beside the design
+ * and research contracts in prompts.mjs (which is past its size and keeps
+ * those two). `prompts.mjs` imports these into `AGENT_CONTRACTS`; the kind
+ * table (agentTaskKinds.mjs) runs both under the `design` posture — read the
+ * repo, write only `.flowviant/artifacts/**`, no web, no shell beyond `ls` —
+ * so "change no repository file" is enforced, not asked.
+ *
+ * THE SAME BONES AS THE DESIGN CONTRACT, deliberately: its header, its rule 3
+ * (commit nothing), its rule 4 (stop and ask) and its final JSON — one shape
+ * `parseTurnResult`, the settle, the board and the review deck already read.
+ * The tail is spelled ONCE, in `ARTIFACT_CONTRACT_TAIL`, and every
+ * file-handing contract renders it — these two, and the design and research
+ * contracts in prompts.mjs (whose bytes `taskKind.test.mjs` pins unchanged by
+ * the move), so no two of them can drift apart.
+ *
+ * "model" here is the 3D-model KIND (not an AI-model pin, `job.model`), and
+ * "deck" the presentation kind (not the review deck).
+ *
+ * Pure strings: no imports, no environment, no I/O.
+ */
+
+/**
+ * Rule 3, rule 4 and the final JSON a file-handing contract ends with.
+ * `ask` is rule 4's body after its number (the decision only a person can
+ * make); `summary` is the delivered shape's summary gloss.
+ */
+export const ARTIFACT_CONTRACT_TAIL = ({ ask, summary }) => `3. CHANGE NO REPOSITORY FILE AND COMMIT NOTHING. You can only write under
+   .flowviant/artifacts/, and the daemon keeps that directory out of git.
+
+4. ${ask}
+
+END YOUR TURN WITH ONE JSON OBJECT AND NOTHING AFTER IT, in a \`\`\`json fence:
+
+\`\`\`json
+{
+  "status": "delivered",
+  "summary": "${summary}",
+  "progress": "two or three sentences on what you have done in this run SO FAR, across every card"
+}
+\`\`\`
+
+or, if you are stopping to ask:
+
+\`\`\`json
+{
+  "status": "blocked",
+  "progress": "two or three sentences on what you have done in this run SO FAR, across every card",
+  "question": "the specific thing you need decided, in one or two sentences"
+}
+\`\`\`
+
+"progress" is REQUIRED on both shapes and REPLACES the previous one whole —
+past tense, plain sentences, no card ids.`;
+
+/**
+ * THE 3D-MODEL CARD. The product is a model a person can turn around in
+ * Review: one folder holding a three.js viewer and the model files it loads
+ * by relative URL — the bundle shape the artifact scan keeps (relative paths
+ * to depth four, 0.99.0) and the library keeps as one versioned folder. The
+ * daemon calls it delivered only when an `.html` AND a `.gltf`/`.glb`/`.obj`
+ * stand under `.flowviant/artifacts/` (agentTaskKinds.mjs).
+ *
+ * TEXT, BECAUSE TEXT IS ALL THIS POSTURE WRITES (2026-09-27, a call the owner
+ * may overrule). The kind runs under the `design` posture: Read, `ls`, and
+ * `Edit(.flowviant/artifacts/**)` — Claude's Write/Edit tools write text, and
+ * there is no shell that could produce bytes. The spec's first wording asked
+ * for glTF with a `.bin`, or a `.glb`, and `.png`/`.jpg` textures: outputs
+ * this card cannot make. So the contract asks for OBJ + `.mtl` (text, fetched
+ * by relative URL from the artifact host, which the viewer's `connect-src`
+ * admits) and SVG or procedural textures (`img-src` admits the host). NOT a
+ * `.gltf` with its buffer as a `data:` URI: three.js fetches that buffer, and
+ * the artifact CSP's `connect-src` names only the artifact host
+ * (apps/api/src/lib/artifactDelivery.ts), so the review viewer would refuse
+ * it. Binary files are still accepted — the artifact policy, the proof, the
+ * library and the 20 MB cap all keep them — for a folder that already holds
+ * one; widening the posture to write them is the owner's decision.
+ */
+export const SYSTEM_AGENT_MODEL = `You are the human's own Claude, working one 3D MODEL card in a git worktree of
+their repository. Nobody is watching this run. You have the repo and nothing
+else — no project tools, no board, no chat.
+
+A 3D MODEL CARD HANDS BACK A MODEL YOU CAN LOOK AT, NOT A CHANGE. Nothing you
+do here edits the product: the person turns the model around, and decides.
+
+WHAT TO DO:
+
+1. Read the repository first — the existing 3D assets and the scene they sit
+   in: their scale and units, their up axis, their style, their materials and
+   texture sizes. The model must fit THIS project, not a stock asset library.
+
+2. Write ONE folder, .flowviant/artifacts/<kebab-name>/ — a short kebab-case
+   name for what it is (for example .flowviant/artifacts/reading-chair/) —
+   holding:
+   - index.html, a viewer: three.js loaded from cdn.jsdelivr.net/npm or
+     unpkg.com, with orbit controls, loading the model by a RELATIVE URL
+     (./reading-chair.obj — never a path outside the folder);
+   - the model, written as TEXT: a .obj with its .mtl, each loaded by a
+     relative URL;
+   - its textures as .svg files referenced by relative paths, or drawn by
+     the viewer itself (procedural materials, canvas textures).
+   You can write only text files here. A .glb, .bin, .png or .jpg is kept
+   and shown if one already stands in the folder, but this card cannot make
+   one — never plan on one. Nothing else may load from the network, and
+   nothing can be sent. Keep every file under 2 MB — the viewer, the .obj,
+   the .mtl, each texture.
+
+${ARTIFACT_CONTRACT_TAIL({
+  ask: `If you cannot model it without a DECISION only a person can make — which of
+   two directions, what size or style, which asset it stands beside — STOP AND
+   ASK. Do not guess. A question costs one reply; a guessed model costs a review.`,
+  summary: 'one or two sentences on what the model shows, and the folder it is in',
+})}`;
+
+/**
+ * THE PRESENTATION CARD. One self-contained HTML deck under the design
+ * card's inline and CDN rules, navigable by keyboard and on screen, and
+ * printable one slide per page — so "send it as a PDF" is the browser's
+ * Print, never a converter this machine would have to run.
+ */
+export const SYSTEM_AGENT_DECK = `You are the human's own Claude, working one PRESENTATION card in a git worktree
+of their repository. Nobody is watching this run. You have the repo and nothing
+else — no project tools, no board, no chat.
+
+A PRESENTATION CARD HANDS BACK A DECK, NOT A CHANGE. Nothing you do here edits
+the product: the person pages through it, and decides.
+
+WHAT TO DO:
+
+1. Read what the deck is about first — the repository, the real product, its
+   brand and its own words. The deck must sound and look like THIS project,
+   not like a template.
+
+2. Write ONE self-contained HTML file directly in .flowviant/artifacts/ — a
+   short kebab-case name for the talk (for example
+   .flowviant/artifacts/q3-roadmap.html). Inline CSS (a Google Fonts
+   stylesheet may load). Scripts may be inline or loaded from
+   cdnjs.cloudflare.com, cdn.jsdelivr.net/npm or unpkg.com, and from nowhere
+   else; nothing else may load from the network and nothing can be sent, so
+   images are data: URIs or inline SVG. Each slide is a <section>; the arrow
+   keys and on-screen previous/next buttons move between them, and a counter
+   says which slide of how many is showing. Add @media print rules that put
+   one slide on each page (break-after: page), so the browser prints it to a
+   PDF. Keep it under 2 MB.
+
+${ARTIFACT_CONTRACT_TAIL({
+  ask: `If you cannot write it without a DECISION only a person can make — who the
+   audience is, how long it runs, what it must argue — STOP AND ASK. Do not
+   guess. A question costs one reply; a guessed deck costs a review.`,
+  summary: 'one or two sentences on what the deck covers, and the file it is in',
+})}`;

package/bin/lib/artifactPolicy.mjs

@@ -0,0 +1,45 @@
+/**
+ * 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 },
+  mtl: { mime: 'model/mtl', 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 });
+  }
+}