flowviant 0.87.0 → 0.88.0

package/bin/lib/agentCards.mjs

@@ -0,0 +1,122 @@
+/**
+ * THE CARD SPECS AN AGENT WAS ACTUALLY GIVEN, kept on the box that gave them
+ * (2026-09-16).
+ *
+ * The AI pre-review reads a branch at review entry and has to answer "does this
+ * diff do what each card asked for" — which needs the cards. Nothing on the
+ * machine holds them: an agent turn is fed ONE card at a time, the server types
+ * the next when the previous lands, and the daemon composes the prompt and
+ * forgets it. By the time the queue empties, the only trace of card one on this
+ * disk is whatever its commits happen to say about themselves, and a commit
+ * message is a CLAIM about the work rather than the work's specification.
+ *
+ * So each turn appends the spec it typed. It is the daemon's own text — the same
+ * `AGENT_TASK_SPEC` block the agent read, so the reviewer reads what the agent
+ * read rather than a second rendering of the card that can drift from it.
+ *
+ * ── WHERE IT LIVES, AND WHY THAT IS THE WHOLE LIFECYCLE ──
+ *
+ * The worktree's PRIVATE git dir (`sessionMetaPath`), scoped by agent id. Three
+ * properties come free with that choice and none of them needs code:
+ *
+ *   · it is INVISIBLE to `git status`, so a stash can never make a worktree
+ *     dirty — which would refuse a ship, the exact trap a marker file in the
+ *     working tree fell into;
+ *   · it DIES with `git worktree remove`, so retiring an agent's worktree
+ *     retires its stash. There is no sweep to write and none to forget;
+ *   · it is per-BOX by construction, which is the honest answer to a machine
+ *     handover: a box that adopted an agent mid-run holds only the prompts IT
+ *     typed. The reviewer prompt SAYS how many it is missing rather than
+ *     inventing the specs it does not have.
+ *
+ * ── IT IS A STASH, NOT A LEDGER ──
+ *
+ * Nothing reads it but the precheck, nothing is decided by it, and losing it
+ * costs one label nobody was promised. Every failure here is swallowed for that
+ * reason: a turn must never fail because a note about it could not be written.
+ */
+
+import { appendFileSync, readFileSync } from 'node:fs';
+
+/**
+ * How many card specs one agent may accumulate.
+ *
+ * A bound on a MACHINE — an agent's queue is a handful of cards, and this exists
+ * so a pathological agent (a card re-delivered fifty times, an agent grown past
+ * its budget) cannot turn a prompt into a file read. The NEWEST are kept, which
+ * is the same tail-is-what-matters rule the trace keeps.
+ */
+export const MAX_STASHED_CARDS = 40;
+/** The most one spec may contribute. A brief is written by whoever filed the
+ *  card and the server caps it, but this file is composed into a prompt and a
+ *  bound it owns is a bound that cannot be argued away upstream. */
+export const MAX_SPEC_CHARS = 8_000;
+
+/**
+ * Write down the spec this turn is about to hand the agent.
+ *
+ * ONE JSON OBJECT PER LINE, APPENDED. Append rather than rewrite because two
+ * turns of one agent never run at once (an agent's place is taken as a WRITER)
+ * but a crash between read and write of a whole-file rewrite would lose every
+ * earlier card — and because an append is atomic enough at this size that a
+ * half-written line is the only damage a kill can do, which the reader drops.
+ *
+ * A re-delivered card appends a SECOND line for the same id; the reader keeps
+ * the last, because that is the spec the agent most recently worked from.
+ */
+export function stashCard(path, taskId, spec) {
+  if (!path) return false;
+  const id = String(taskId ?? '').trim();
+  const text = String(spec ?? '');
+  if (!id || !text.trim()) return false;
+  try {
+    appendFileSync(
+      path,
+      JSON.stringify({ taskId: id.slice(0, 64), prompt: text.slice(0, MAX_SPEC_CHARS) }) + '\n'
+    );
+    return true;
+  } catch {
+    // A stash that could not be written costs the precheck one card's spec,
+    // which it will say it could not check rather than guess at.
+    return false;
+  }
+}
+
+/**
+ * What this box holds, newest spec per card, in the order the cards were worked.
+ *
+ * MALFORMED LINES ARE DROPPED ALONE — the boundary rule this repo states for
+ * every relayed list: one truncated line (a daemon killed mid-append) must not
+ * throw away the thirty-nine good specs beside it.
+ */
+export function readStash(path) {
+  if (!path) return [];
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    return []; // no file: this agent has run no card turn on this box
+  }
+  /** taskId → spec. A Map, so the LAST write per card wins while the insertion
+   *  order stays the order the cards were first handed out — which is the order
+   *  the branch was built in, and the order a reviewer reads them in. */
+  const byId = new Map();
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!v || typeof v !== 'object') continue;
+    const taskId = typeof v.taskId === 'string' ? v.taskId.trim() : '';
+    const prompt = typeof v.prompt === 'string' ? v.prompt : '';
+    if (!taskId || !prompt.trim()) continue;
+    byId.set(taskId, prompt.slice(0, MAX_SPEC_CHARS));
+  }
+  const all = [...byId].map(([taskId, prompt]) => ({ taskId, prompt }));
+  // The NEWEST cards when there are too many — a reviewer reading a grown
+  // agent's branch is reading the work at its end.
+  return all.slice(-MAX_STASHED_CARDS);
+}

package/bin/lib/agentPlan.mjs

@@ -1,5 +1,7 @@
 /**
- * READING A PLANNER'S ANSWER.
+ * READING A MODEL'S ANSWER, in the agent lane's three shapes: a planner's
+ * PROPOSAL, an agent's own TURN RESULT, and (2026-09-16) the AI pre-review's
+ * TRIAGE.
  *
  * The scratch agent behind a Deploy press is asked for one JSON object and
  * nothing else. This is what turns its final message into a proposal, and it is
@@ -31,38 +33,50 @@ const MAX_NAME = 80;
 const MAX_NOTE = 1000;
 
 /**
- * Find the object.
+ * Find the objects.
  *
  * A fenced block first, because that is what was asked for. Otherwise every `{`
  * in the text is tried as a start, and its BALANCED end is found by counting
- * braces while skipping string literals — the first candidate that parses into
- * something with an `agents` array wins.
+ * braces while skipping string literals — each caller then takes the first
+ * candidate whose SHAPE is the one it asked for.
  *
  * The obvious cheap version — first `{` to last `}` — is wrong in a way a test
  * caught: a planner that writes "I looked at {the auth module} first" before its
  * JSON produces a span starting at the wrong brace, and the whole plan is lost
  * to a sentence. Scanning candidates costs nothing at this size and cannot be
  * defeated by prose.
+ *
+ * ONE SCANNER FOR ALL THREE READERS in this file (2026-09-16). It was written
+ * twice — once here and once inline in `parseTurnResult` — and a third copy was
+ * about to be written for the precheck. A brace scanner that skips string
+ * literals is exactly the kind of thing where two copies quietly stop agreeing
+ * about escapes and nobody notices, because the disagreement only shows up on a
+ * card title with a quote in it.
  */
-function extract(raw) {
+function candidateObjects(raw) {
   const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
-  const candidates = [];
-  if (fenced) candidates.push(fenced[1]);
+  const bodies = [];
+  if (fenced) bodies.push(fenced[1]);
   for (let i = 0; i < raw.length; i++) {
     if (raw[i] !== '{') continue;
     const end = balanced(raw, i);
-    if (end > i) candidates.push(raw.slice(i, end + 1));
+    if (end > i) bodies.push(raw.slice(i, end + 1));
   }
-  for (const body of candidates) {
+  const out = [];
+  for (const body of bodies) {
     if (!body.trim()) continue;
     try {
       const v = JSON.parse(body);
-      if (v && typeof v === 'object' && Array.isArray(v.agents)) return v;
+      if (v && typeof v === 'object') out.push(v);
     } catch {
       /* the next candidate may be the object */
     }
   }
-  return null;
+  return out;
+}
+
+function extract(raw) {
+  return candidateObjects(raw).find((v) => Array.isArray(v.agents)) ?? null;
 }
 
 /** The index of the `}` that closes the `{` at `from`, or -1. Skips string
@@ -158,23 +172,7 @@ export function parseProposal(text) {
  * up here rather than being read as success.
  */
 export function parseTurnResult(text) {
-  const parsedRaw = String(text ?? '');
-  const fenced = parsedRaw.match(/```(?:json)?\s*([\s\S]*?)```/);
-  const candidates = [];
-  if (fenced) candidates.push(fenced[1]);
-  for (let i = 0; i < parsedRaw.length; i++) {
-    if (parsedRaw[i] !== '{') continue;
-    const end = balanced(parsedRaw, i);
-    if (end > i) candidates.push(parsedRaw.slice(i, end + 1));
-  }
-  for (const body of candidates) {
-    let v;
-    try {
-      v = JSON.parse(body);
-    } catch {
-      continue;
-    }
-    if (!v || typeof v !== 'object') continue;
+  for (const v of candidateObjects(String(text ?? ''))) {
     if (v.status === 'blocked') {
       const question = typeof v.question === 'string' ? v.question.trim() : '';
       // A "blocked" with no question is not an answer anybody can act on — it
@@ -203,3 +201,80 @@ export function parseTurnResult(text) {
   }
   return null;
 }
+
+/** The precheck's own bounds — mirrored at the server boundary, which caps
+ *  again. A note is one sentence of triage and `overall` is one paragraph; the
+ *  numbers are the ones SYSTEM_PRECHECK asks for, stated here so a model that
+ *  ignores them cannot make the row bigger than the surface can render. */
+const MAX_PRECHECK_CARDS = 60;
+const MAX_PRECHECK_NOTE = 400;
+const MAX_PRECHECK_OVERALL = 1200;
+
+/**
+ * READING THE AI PRE-REVIEW's ANSWER (2026-09-16).
+ *
+ * Same law as its two neighbours — LENIENT ON PACKAGING, STRICT ON SHAPE — and
+ * here the strict half has a sharper consequence than usual: this text is about
+ * to be rendered on the surface where somebody decides whether a branch reaches
+ * main. A half-read answer is a plausible-looking triage nobody wrote.
+ *
+ * NULL IS THE SAFE ANSWER AND THE COMMON ONE. A precheck that came back
+ * unparseable posts NOTHING, and the absence renders nothing: the human's review
+ * is exactly what it was before this feature existed. That is the whole reason
+ * this may be strict where `parseProposal` cannot be — a lost proposal wastes a
+ * press somebody made, a lost precheck costs a label nobody was promised.
+ *
+ * ONE ENTRY PER CARD, and the FIRST one wins: a model that judges a card twice
+ * has contradicted itself, and rendering two notes on one card face would ask
+ * the reviewer to arbitrate between them. An unknown verdict word is dropped
+ * rather than coerced — `ok` is a claim ("I looked and found nothing"), and
+ * guessing it from a word nobody listed would be the parser making that claim.
+ *
+ * `scrub` RIDES IN, AND IT RUNS BEFORE EVERY CUT (review, 2026-09-17).
+ *
+ * The caller used to scrub afterwards — `envScrub(cd.note).slice(0, 400)` over
+ * a note this function had ALREADY cut to 400. `scrub` replaces EXACT full
+ * values, so a credential straddling the cut arrived here pre-severed, matched
+ * nothing, and its surviving prefix was stored and rendered to every member of
+ * the project. That is byte-for-byte the bug `runCheck`'s output lane records
+ * learning the expensive way, and the reviewer this parses reads a worktree
+ * holding the project's materialized dev secrets — a note quoting a `.env`
+ * line is the ordinary way to reach it. The fix is `toolEventOf`'s: the scrub
+ * rides INTO the builder and runs over the whole field, before the cap.
+ *
+ * DEFAULTED TO IDENTITY so the parser stays testable on its own, and so a
+ * caller that forgets loses redaction rather than the whole reading — but the
+ * ONE production caller passes `envScrub`, and `work.test.mjs` pins the order.
+ */
+export function parsePrecheck(text, scrub = (s) => s) {
+  const parsed = candidateObjects(String(text ?? '')).find((v) => Array.isArray(v.cards));
+  if (!parsed) return null;
+
+  const cards = [];
+  const seen = new Set();
+  for (const c of parsed.cards.slice(0, MAX_PRECHECK_CARDS)) {
+    if (!c || typeof c !== 'object') continue;
+    const taskId = typeof c.taskId === 'string' ? c.taskId.trim().slice(0, 64) : '';
+    if (!taskId || seen.has(taskId)) continue;
+    if (c.verdict !== 'ok' && c.verdict !== 'concerns') continue;
+    seen.add(taskId);
+    // SCRUB, THEN CUT — see the docblock. The whole field is in hand here, so an
+    // exact-value match still finds a secret that spans the cap.
+    const note =
+      typeof c.note === 'string' ? scrub(c.note.trim()).slice(0, MAX_PRECHECK_NOTE) : '';
+    cards.push({ taskId, verdict: c.verdict, ...(note ? { note } : {}) });
+  }
+  const overall =
+    typeof parsed.overall === 'string'
+      ? scrub(parsed.overall.trim()).slice(0, MAX_PRECHECK_OVERALL)
+      : '';
+  /**
+   * AN ANSWER THAT SAYS NOTHING IS NOT AN ANSWER. No readable card verdict and
+   * no overall means the model produced the right punctuation and no content —
+   * posting that would put an empty "Claude's pre-review" heading on the deck,
+   * which reads as a feature that ran and found the branch unremarkable. It did
+   * not run.
+   */
+  if (cards.length === 0 && !overall) return null;
+  return { cards, ...(overall ? { overall } : {}) };
+}

package/bin/lib/prompts.mjs

@@ -830,13 +830,25 @@ const safeName = (n) =>
     .trim()
     .slice(0, 60) || 'agent';
 
-const taskBlock = (task) =>
+/**
+ * A CARD'S SPEC, WRITTEN DOWN ONCE.
+ *
+ * EXPORTED (2026-09-16) because a second reader now needs the identical text:
+ * the AI pre-review is composed from the card specs the daemon STASHED as it
+ * typed each turn's prompt, and the whole claim of that surface is that the
+ * reviewer read what the agent read. Two builders for one thing is two
+ * renderings of a card that can drift — and the drift would be invisible,
+ * because nobody reads both prompts side by side.
+ */
+export const AGENT_TASK_SPEC = (task) =>
   `id: ${task?.id ?? ''}\n` +
   `title: ${task?.title ?? ''}\n` +
   (task?.brief ? `\nbrief:\n${task.brief}\n` : '') +
   (task?.criteria?.length ? `\ndone when:\n${task.criteria.map((c) => `- ${c}`).join('\n')}\n` : '') +
   (task?.anchors?.length ? `\nthis card owns:\n${task.anchors.map((a) => `- ${a}`).join('\n')}\n` : '');
 
+const taskBlock = AGENT_TASK_SPEC;
+
 /**
  * A PERSON SPOKE TO THE AGENT — usually the answer to its own question.
  *
@@ -852,3 +864,126 @@ export const AGENT_HUMAN_KICKOFF = ({ agentName, message, askedByName, task, pos
   `${fence('WHAT THEY SAID', message)}\n\n` +
   (task ? `${fence('THE CARD YOU ARE ON', taskBlock(task))}\n\n` : '') +
   `Carry on, and end with the JSON object as usual.`;
+
+/**
+ * THE AI PRE-REVIEW — a FRESH Claude reads the branch before the human does
+ * (2026-09-16).
+ *
+ * The owner asked for it in these words: "before having the user manually check,
+ * can we have the daemon … spawn an agent to review the work so basically we get
+ * an ai to look at the review before a human looks at it for a double check."
+ *
+ * ── FRESH EYES, AND THAT IS THE ENTIRE DESIGN ──
+ *
+ * This is NOT the agent's own conversation asked to check itself. An agent that
+ * has spent four turns arguing itself into a design defends that design; asked
+ * whether its work meets the card, it answers from the same context that
+ * produced the work and finds it good. So the precheck is a NEW `claude -p` with
+ * no resumed conversation, standing in the agent's worktree because it needs the
+ * code and the diff, under the READ-ONLY profile the scratch planner and the
+ * capture chat already run behind, with no MCP at all. It reads; it cannot
+ * write; it has no control plane to reach even if the repository it is reading
+ * tries to steer it.
+ *
+ * ── IT LABELS AND NEVER BLOCKS ──
+ *
+ * The project's own check states this law and this obeys it identically:
+ * Approve, the verdicts and the ship quiz do not know this exists. A precheck
+ * that failed, timed out, or was never run posts NOTHING, and the absence
+ * renders nothing — ignorance never withholds a human's review, the same
+ * three-state rule every readout in this product keeps.
+ *
+ * ── AND IT IS ASKED FOR A TRIAGE, NOT A VERDICT ──
+ *
+ * The one thing a second reader can do that the first cannot is say WHERE TO
+ * LOOK FIRST. Asked to approve or reject, a model produces a confident judgment
+ * nobody asked it for and somebody will eventually treat as one. Asked what a
+ * reviewer should check first, it produces a list of places — which is useful
+ * whether it is right or wrong, because the human is about to look anyway.
+ */
+export const SYSTEM_PRECHECK = `You are a SECOND reviewer with fresh eyes, reading a branch an agent has just
+finished. You did not write this code and you were not in the conversation that
+produced it. That is the whole point of you.
+
+A PERSON REVIEWS THIS NEXT, and your job is to tell them what to look at first.
+You are not approving or rejecting anything: nothing you say gates the merge,
+nothing you say is shown to the agent, and nobody is waiting on a decision from
+you.
+
+YOU ARE READ-ONLY. You cannot write, edit or create files, and you have no tools
+beyond reading this repository. Do not try.
+
+HOW TO READ IT:
+
+1. READ THE DIFF. A commit message is a CLAIM about the work; the diff is the
+   work. Run the diff command you are given and read what actually changed
+   before you say anything about it.
+2. VERIFY EACH CARD AGAINST ITS OWN ACCEPTANCE CRITERIA. For every card you are
+   given, decide FROM THE DIFF whether what was asked for is actually there.
+   "ok" means you looked and found nothing a reviewer needs warning about.
+   "concerns" means there is something specific you would want them to check
+   first.
+3. BE SPECIFIC OR SAY NOTHING. "Looks reasonable" helps nobody. A concern names
+   a file, a function or a behaviour and says what about it worries you. If you
+   cannot point at something, the verdict is "ok".
+4. NEVER INVENT. If a card's spec was not given to you, judge it from the diff
+   and the commits and SAY in your note what you could not check it against.
+   Never assume a file exists, a test passes, or a criterion was met because a
+   commit message says so.
+5. YOU ARE NOT A STYLE GUIDE. Correctness, missing pieces, things the criteria
+   asked for that the diff does not show, changes that reach further than the
+   card did. Not formatting, not naming preferences, not the rewrite you would
+   have preferred.
+
+END YOUR TURN WITH ONE JSON OBJECT AND NOTHING AFTER IT, in a \`\`\`json fence:
+
+\`\`\`json
+{
+  "cards": [
+    { "taskId": "<card id, exactly as given>", "verdict": "ok", "note": "" },
+    { "taskId": "<card id, exactly as given>", "verdict": "concerns", "note": "what a reviewer should look at first, and why" }
+  ],
+  "overall": "what you would tell the reviewer before they start reading"
+}
+\`\`\`
+
+One entry per card, AT MOST ONE note each, and use the card ids exactly as
+given. A note is at most 400 characters and "overall" at most 1200: you are
+writing the first paragraph of somebody's review, not the review.`;
+
+/**
+ * The precheck's turn.
+ *
+ * THE CARDS AND THE COMMITS ARE FENCED. A card's title, brief and criteria are
+ * written by whoever files cards in this project; a commit subject is written by
+ * a model that has just been editing files. Both are untrusted content this turn
+ * reads, and the instruction that matters — "read the diff and triage it" — is
+ * ours and sits outside the fence.
+ *
+ * `missingSpecs` IS MEASURED, NOT GUESSED. A box that adopted this agent
+ * mid-run (the machine moved, or an older turn ran elsewhere) holds only the
+ * prompts IT typed, so the stash can be short of what the branch carries. The
+ * count is the difference between the `Flowviant-Task:` trailers on the branch
+ * and the specs on this disk — so the reviewer is told what it could not read
+ * rather than being handed a silent gap, and never told a card exists that
+ * nothing measured.
+ */
+export const AGENT_PRECHECK_KICKOFF = ({
+  agentName,
+  cards,
+  missingSpecs = 0,
+  commits,
+  diffCommand,
+}) =>
+  `The agent "${safeName(agentName)}" has finished its queue. A person is about to ` +
+  `review this branch; you are reading it first.\n\n` +
+  `${fence('THE CARDS IT WAS GIVEN', cards || '(none of this branch’s card specs are on this machine)')}\n\n` +
+  (missingSpecs > 0
+    ? `${missingSpecs} earlier card${missingSpecs === 1 ? "'s spec is" : "s' specs are"} ` +
+      `not on this box — review ${missingSpecs === 1 ? 'it' : 'them'} from the diff and the ` +
+      `commits below, and say in your note what you could not check them against.\n\n`
+    : '') +
+  `${fence('THE COMMITS ON THIS BRANCH', commits || '(none)')}\n\n` +
+  `Read the diff yourself before you judge any of it:\n\n` +
+  `    ${diffCommand}\n\n` +
+  `Then answer with the JSON object and nothing else.`;

package/bin/lib/work.mjs

@@ -52,7 +52,8 @@ import { listenersIn, measureListeners, listenersSupported } from './listeners.m
 import { measureProcesses, liveGroups, processesSupported } from './processes.mjs';
 import { mutateRegistry, processAlive, readRegistry } from './procRegistry.mjs';
 import { createPlaceLock } from './placeLock.mjs';
-import { parseProposal, parseTurnResult } from './agentPlan.mjs';
+import { parseProposal, parsePrecheck, parseTurnResult } from './agentPlan.mjs';
+import { readStash, stashCard } from './agentCards.mjs';
 import { sweepMergedBranch } from './shipSweep.mjs';
 import { mergeOutward as shipMergeOutward } from './shipMerge.mjs';
 import { openTunnel } from './preview.mjs';
@@ -68,8 +69,11 @@ import {
   SYSTEM_PLAN,
   AGENT_PLAN_KICKOFF,
   SYSTEM_AGENT,
+  SYSTEM_PRECHECK,
   AGENT_TASK_KICKOFF,
+  AGENT_TASK_SPEC,
   AGENT_HUMAN_KICKOFF,
+  AGENT_PRECHECK_KICKOFF,
 } from './prompts.mjs';
 import {
   materializeInto,
@@ -84,6 +88,7 @@ import {
   pickRuntimeFor,
   recordSkills,
   toolEventOf,
+  removeProbeTranscript,
   CLAUDE_TOOL_PROSE_KINDS,
   RUNTIMES,
 } from './runtimes.mjs';
@@ -222,6 +227,7 @@ export function createWorkManager({
   const AGENT_TRACE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-trace');
   const AGENT_PARKED_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-parked');
   const AGENT_CHECK_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-check-done');
+  const AGENT_PRECHECK_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-precheck');
   const AGENT_MERGE_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-merge-claim');
   const AGENT_MERGE_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-merge-done');
   // What arrived on base, whichever road it took — observed after every beat
@@ -4810,6 +4816,34 @@ export function createWorkManager({
        */
       const resume = rt === 'claude' && Boolean(ranMarker && existsSync(ranMarker));
 
+      /**
+       * WRITE THE CARD DOWN BEFORE HANDING IT OVER — the material the AI
+       * pre-review reads at review entry (see agentCards.mjs).
+       *
+       * HERE rather than at review entry because here is the ONLY moment this
+       * machine holds the card at all: the server feeds an agent one card per
+       * prompt and keeps no copy on this disk, so by the time the queue empties
+       * card one exists locally as nothing but its own commit messages — which
+       * are a claim about the work, not the specification it was judged against.
+       *
+       * BEFORE the CLI runs rather than after, so a turn that crashes still
+       * leaves the spec behind: the card really was given to the agent, the
+       * commits it made are on the branch, and a reviewer is entitled to read
+       * what was asked for either way.
+       *
+       * ONE SPEC BUILDER (`AGENT_TASK_SPEC`) shared with the kickoff below, so
+       * what the reviewer reads is byte-identical to what the agent read.
+       * Failure is swallowed inside `stashCard`: a note about a turn may never
+       * cost the turn.
+       */
+      if (job.kind === 'task' && job.task) {
+        stashCard(
+          sessionMetaPath(wt, 'flowviant-agent-cards', agentId),
+          job.task.id,
+          AGENT_TASK_SPEC(job.task)
+        );
+      }
+
       /**
        * THE WHOLE STREAM, not just its latest line — see trace.mjs.
        *
@@ -5009,9 +5043,10 @@ export function createWorkManager({
         branch,
         worktree: wt,
       });
-      // The queue just emptied. Run the project's own check HERE, in the
-      // worktree we are already standing in and still hold the lock on.
-      if (reply?.review === true) await runCheck(agentId, wt);
+      // The queue just emptied. Run the project's own check and the AI
+      // pre-review HERE, in the worktree we are already standing in and still
+      // hold the lock on — see `runReviewEntry`.
+      if (reply?.review === true) await runReviewEntry(agentId, wt, job.agentName);
     });
     /**
      * …AND THEN PUBLISH, IF THE PROJECT PUBLISHES.
@@ -5102,8 +5137,8 @@ export function createWorkManager({
         // body — never the CLI, which would spend the operator's quota again
         // and write a second set of commits. The reply can still carry the one
         // instruction a settle can (`review: true`, the queue just emptied),
-        // so the project's check runs from here too, under the same writer
-        // lock the turn itself would have held.
+        // so the project's check and the AI pre-review run from here too, under
+        // the same writer lock the turn itself would have held.
         agentTurns.add(id);
         void (async () => {
           const reply = await postAgentTurn(held.body);
@@ -5111,7 +5146,7 @@ export function createWorkManager({
           const wt = typeof held.body.worktree === 'string' ? held.body.worktree : null;
           if (reply?.review === true && isSafePathSegment(place) && wt && existsSync(wt)) {
             await inPlace(place, place.startsWith('a-'), () =>
-              runCheck(String(job.agentId || ''), wt)
+              runReviewEntry(String(job.agentId || ''), wt, job.agentName)
             );
           }
         })()
@@ -5361,6 +5396,363 @@ export function createWorkManager({
     });
   };
 
+  // ── THE AI PRE-REVIEW ──────────────────────────────────────────────────────
+  //
+  // A FRESH Claude reads the branch before the human does. The owner asked for
+  // it in these words: "before having the user manually check, can we have the
+  // daemon … spawn an agent to review the work so basically we get an ai to look
+  // at the review before a human looks at it for a double check."
+  //
+  // IT IS NOT THE AGENT CHECKING ITSELF. `runTurn` is called with no `resume`,
+  // so there is no conversation to inherit: an agent that spent four turns
+  // arguing itself into a design defends that design, and asked whether its work
+  // meets the card it answers from the very context that produced the work. The
+  // reviewer stands IN the agent's worktree because it needs the code and the
+  // diff, under `readOnly` (CONSULT_PERM — Read, Grep, Glob and a few git reads)
+  // with NO MCP passed at all, so there is no control plane on this turn even if
+  // the repository it reads tries to steer it.
+  //
+  // IT LABELS AND NEVER BLOCKS — the check's own law, one function up. Approve,
+  // the per-card verdicts and the ship quiz do not know this exists. Every exit
+  // below POSTS NOTHING, and the server renders an absent precheck as nothing:
+  // a failed, timed-out, skipped or unparseable read leaves the human's review
+  // exactly as it was before this feature existed. Ignorance never withholds.
+  //
+  // NO VERSION FLOOR. This is a daemon→server report on a NEW endpoint, so an
+  // older daemon simply never posts, and an older SERVER 404s — which `postPre`
+  // treats as delivered-and-done for the agent-trace reason stated there.
+  //
+  // IT RIDES THE BEAT THE CHECK ALREADY OWNS (`runReviewEntry`), AFTER it: the
+  // check is a local command and this is a model call, so the cheap answer lands
+  // on the row first and a wedged reviewer cannot delay it.
+  /**
+   * FIVE MINUTES, and `runTurn` has no timer of its own.
+   *
+   * Half the planner's cap, because this turn is strictly smaller — it reads one
+   * branch's diff and answers, where a planner reads a repository to decide
+   * whether a batch of work collides. And it is HELD INSIDE THE PLACE WRITER
+   * LOCK by the beat it rides, so every minute here is a minute the agent's next
+   * turn (or its merge) is waiting: a generous cap on a label would be spending
+   * the work's time on a note about the work.
+   */
+  const PRECHECK_TIMEOUT_MS = 5 * 60_000;
+  /** Commit subjects handed to the reviewer. A bound on the prompt, not on the
+   *  branch — the reviewer reads the diff itself, and the log is context. */
+  const PRECHECK_LOG_LINES = 80;
+
+  /**
+   * ONE PRE-REVIEW, POSTED.
+   *
+   * Resolves TRUE for a permanent refusal as well as a success, and that is
+   * deliberate — the `postAgentTrace` rule, for the same reason: a server with
+   * no such route 404s this body and will 404 every retry of it, so re-sending
+   * would be a wedge wearing a retry's clothes. A NETWORK error resolves false
+   * and is retried ONCE, because unlike a trace batch this body cost a whole
+   * model call and losing it to a blip means the operator paid for a label
+   * nobody ever sees.
+   */
+  const postPre = async (body) => {
+    try {
+      const res = await fetch(AGENT_PRECHECK_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify(body),
+      });
+      return (
+        res.ok ||
+        (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429)
+      );
+    } catch {
+      return false; // a blip — worth one more attempt at a model call's answer
+    }
+  };
+
+  /**
+   * THE BRANCH'S OWN COMMITS, subject + trailers, and the card ids they name.
+   *
+   * MEASURED, never asserted — the same reason `commitsBetween` exists. The
+   * trailer ids are what let the prompt say "N earlier cards' specs are not on
+   * this box" honestly: the difference between the cards this branch claims and
+   * the specs this disk holds is a fact, and a box that adopted the agent
+   * mid-run is exactly the case where it is non-zero.
+   *
+   * IT CANNOT THROW. `baseRef()` is free text an owner typed and may name no
+   * ref at all; an unreadable range costs the reviewer its context, never the
+   * review-entry beat it is standing in.
+   */
+  const branchLog = (wt) => {
+    let out;
+    try {
+      out = git(['log', '--format=%s%n%b%n--', `${baseRef()}..HEAD`, '--not', baseRef()], wt);
+    } catch {
+      return { text: '', taskIds: [] };
+    }
+    if (typeof out !== 'string') return { text: '', taskIds: [] };
+    const taskIds = new Set();
+    for (const m of out.matchAll(/^\s*Flowviant-Task:\s*(\S+)\s*$/gm)) {
+      taskIds.add(m[1].slice(0, 64));
+    }
+    const text = out
+      .split('\n')
+      .filter((l) => l.trim())
+      .slice(0, PRECHECK_LOG_LINES)
+      .join('\n');
+    return { text, taskIds: [...taskIds] };
+  };
+
+  const runPrecheck = async (agentId, wt, agentName) => {
+    /**
+     * WHICH CLI READS. `pickRuntimeFor('consult')` — the same picker the scratch
+     * planner uses, and for the same reason: this prompt was written against
+     * Claude, and a machine with no read-only-capable runtime simply does not
+     * produce a precheck. Nothing is posted and nothing is said on the row.
+     */
+    const rt = pickRuntimeFor('consult');
+    if (!rt) return;
+    /**
+     * THE PRESSURE GUARD, at the spawn, exactly as every other unattended lane
+     * asks it. `churn` and never `interactive`: nobody is watching this, and a
+     * label is the first thing that should not be started on a box that is
+     * struggling. Deferring here does NOT queue anything — there is no job and
+     * no re-offer — so a precheck skipped under pressure is simply a precheck
+     * that did not happen, which is what absence already means.
+     */
+    const hold = admit('churn');
+    if (hold) {
+      note(`${c.cyan('pre-review')} ${c.dim(`— skipped: ${hold.reason}`)}`);
+      return;
+    }
+    const releaseSlot = admit.reserve();
+
+    // THE HEAD THE READING BELONGS TO, taken BEFORE the turn — the
+    // `checkFingerprint` shape, so a commit landing after this voids it rather
+    // than letting an old reading label a branch it never saw. Optional: an
+    // unreadable head costs the staleness comparison, not the precheck.
+    let headSha = null;
+    try {
+      headSha = (git(['rev-parse', 'HEAD'], wt) || '').trim() || null;
+    } catch {
+      headSha = null;
+    }
+
+    const stash = readStash(sessionMetaPath(wt, 'flowviant-agent-cards', agentId));
+    const log = branchLog(wt);
+    /** Cards the BRANCH names that this box has no spec for. Measured, not
+     *  guessed — see agentCards.mjs on why a stash is per-box. */
+    const held = new Set(stash.map((s) => s.taskId));
+    const missingSpecs = log.taskIds.filter((id) => !held.has(id)).length;
+
+    let out = '';
+    let child = null;
+    let timer = null;
+    /** The cap fired: the CLI was still running when this machine stopped it. */
+    let wedged = false;
+    /**
+     * THE CONVERSATION THIS READING SPEAKS UNDER — held for exactly one reason:
+     * to DELETE the transcript it leaves behind (review, 2026-09-17).
+     *
+     * This is the first thing in the daemon to run a second `claude -p` inside
+     * an AGENT's worktree, and the agent's own resume is `--continue`, which is
+     * CWD-KEYED — the invariant `runAgentTurn` states in words ("ONE AGENT IS
+     * ONE DIRECTORY, so the CLI's own cwd-keyed resume is exactly right here").
+     * Leaving this turn's `~/.claude/projects/<munged-cwd>/<id>.jsonl` in place
+     * makes the read-only stranger the newest conversation in that directory,
+     * so the agent's NEXT turn — a send-back's re-queued card, a merge-resolve,
+     * a human's typed answer — resumes "you are a SECOND reviewer… YOU ARE
+     * READ-ONLY" instead of its own four-turn context, under build permissions.
+     * That is the 0.69.0 Workbench cross-resume and codex's `resume --last`,
+     * arriving a third time by a third route.
+     *
+     * `removeProbeTranscript` is exported for precisely this and already serves
+     * the skills probe and the dev-command resolver.
+     */
+    let preSession = null;
+    try {
+      /**
+       * THE CAP RESOLVES THE WAIT ITSELF rather than waiting for `close` after
+       * the kill — the shape the project check and the planner both keep. A
+       * SIGKILLed process whose stdio a grandchild still holds can be slow to
+       * emit `close`, or never emit it, and this promise is inside the place's
+       * writer lock.
+       */
+      let stopWaiting = () => {};
+      const capped = new Promise((r) => {
+        stopWaiting = r;
+      });
+      const turn = runTurn({
+        prompt: AGENT_PRECHECK_KICKOFF({
+          agentName,
+          cards: stash.map((s) => s.prompt).join('\n---\n'),
+          missingSpecs,
+          commits: log.text,
+          diffCommand: `git diff ${baseRef()}...HEAD`,
+        }),
+        system: SYSTEM_PRECHECK,
+        // READ-ONLY, and no MCP: `mcpArgs` is omitted entirely rather than
+        // passed empty, so there is no control plane on this turn at all.
+        readOnly: true,
+        cwd: wt,
+        runtime: rt,
+        // NO `resume`, AND THAT IS THE FEATURE. A resumed turn would be the
+        // agent grading its own homework out of its own context; this is a
+        // stranger reading a diff.
+        streamJson: true,
+        answerFromResult: true,
+        label: c.cyan('[pre-review]'),
+        // The id the CLI reports at `system.init` — harvested off the stream
+        // this turn already parses, no probe and no extra spawn. Held only so
+        // the `finally` below can delete this turn's transcript; see
+        // `preSession`.
+        onInit: (i) => {
+          if (typeof i.sessionId === 'string' && i.sessionId.trim())
+            preSession = i.sessionId.trim();
+        },
+        onSpawn: (ch) => {
+          child = ch;
+          // No task id: a pre-review belongs to no card, and the machine
+          // snapshot's per-task rows must not invent one. It still COUNTS
+          // against the machine's ceiling — see liveTurnCount.
+          workChildren.set(ch, null);
+          releaseSlot();
+          // ARMED AT THE SPAWN, not at entry: time spent getting here is not a
+          // wedged CLI. The CHILD and never its group — a read-only turn starts
+          // no server, so there is nothing behind it worth signalling and
+          // everything to lose by signalling somebody else's.
+          timer = setTimeout(() => {
+            wedged = true;
+            try {
+              ch.kill('SIGKILL');
+            } catch {
+              /* already gone */
+            }
+            stopWaiting('');
+          }, PRECHECK_TIMEOUT_MS);
+          timer.unref?.();
+        },
+      });
+      out = await Promise.race([turn, capped]);
+    } catch {
+      return; // a label may never fail the beat it rides
+    } finally {
+      if (timer) clearTimeout(timer);
+      if (child) workChildren.delete(child);
+      releaseSlot();
+      /**
+       * DELETE THIS READING'S TRANSCRIPT, on EVERY exit — settled, wedged and
+       * killed, or thrown — because every one of them leaves the file behind
+       * and the agent's `--continue` reads the newest one in the directory.
+       *
+       * AFTER the kill and ON A DELAY, the skills probe's own shape: the
+       * transcript is the CHILD's file, so removing it while the child is still
+       * dying races a recreate. Unref'd — it must not hold the process open.
+       */
+      if (preSession) setTimeout(() => removeProbeTranscript(wt, preSession), 750).unref?.();
+    }
+
+    // A WEDGED READING POSTS NOTHING. There is no row to settle and nobody
+    // waiting on an answer, so the honest record is that no pre-review exists —
+    // the same silence a machine that never ran one leaves.
+    if (wedged) {
+      note(`${c.cyan('pre-review')} ${c.dim('— ran past five minutes and was stopped')}`);
+      return;
+    }
+
+    /**
+     * SCRUBBED ON THE WAY OUT, every string — AND SCRUBBED BEFORE IT IS CUT,
+     * which is the order that matters and the reason `envScrub` rides INTO the
+     * parser rather than being applied to what comes back out.
+     *
+     * This turn read the repository with `cat` and `git show` in a worktree
+     * holding the project's materialized dev secrets, and its answer is about to
+     * be stored and rendered to every member of the project. `scrub` replaces
+     * EXACT full values, so a note capped first and scrubbed second hands the
+     * scrub a credential already cut in half: it matches nothing and the
+     * surviving prefix ships. The check's output lane learned exactly that the
+     * expensive way, and this lane relearned it in review (2026-09-17) — see
+     * `parsePrecheck`, which now caps only what it has already redacted.
+     */
+    const result = parsePrecheck(out, envScrub);
+
+    /**
+     * A QUOTA LIMIT SKIPS THE PRE-REVIEW AND PARKS NOTHING — AND A LIMIT IS
+     * ONLY A LIMIT WHEN THE READING PRODUCED NOTHING.
+     *
+     * `limitLine` is a literal phrase match over the CLI's whole output, and
+     * under `answerFromResult` that output IS the reviewer's answer — so a
+     * pre-review OF rate-limiting code, or any triage that quotes the phrase,
+     * read as a quota failure and threw a perfectly good reading away. The
+     * agent-turn lane fixed this exact false positive once (`const limit = res
+     * ? null : limitLine(out)`); gating on "nothing parsed" is what makes the
+     * match mean what it says.
+     *
+     * And when it IS a limit, nothing parks. `postAgentParked` stops EVERY
+     * agent on the project, because the CLI login is shared — the right answer
+     * when the thing that hit the limit was somebody's actual work, the wrong
+     * one here: parking a whole fleet because a LABEL could not be written
+     * would let an optional readout take the product's primary lane down. The
+     * branch is still reviewable; it just has no note on it.
+     */
+    if (!result) {
+      if (limitLine(out)) {
+        note(`${c.cyan('pre-review')} ${c.dim('— skipped: the CLI reported a limit')}`);
+      }
+      // UNPARSEABLE POSTS NOTHING. A half-read triage is a plausible-looking
+      // paragraph nobody wrote, rendered on the surface where somebody decides
+      // whether a branch reaches main — see parsePrecheck.
+      return;
+    }
+
+    const body = {
+      agentId,
+      ...(headSha ? { headSha } : {}),
+      cards: result.cards.map((cd) => ({
+        taskId: cd.taskId,
+        verdict: cd.verdict,
+        ...(cd.note ? { note: cd.note } : {}),
+      })),
+      ...(result.overall ? { overall: result.overall } : {}),
+    };
+    // ONE RETRY, and only for a network error — see `postPre`. A permanent
+    // refusal is an older server, and asking it again changes nothing.
+    if (!(await postPre(body))) await postPre(body);
+  };
+
+  /**
+   * REVIEW ENTRY — everything this machine does the moment an agent's queue
+   * empties, in one place.
+   *
+   * It exists so the two readings cannot drift apart at the three call sites
+   * that own this beat (the settle reply, the held body's re-POST, and the
+   * stale-merge re-read after base is folded in). Each of those used to call
+   * `runCheck` directly; a second thing to run at the same moment is a second
+   * thing three call sites can forget.
+   *
+   * THE CHECK FIRST, ALWAYS. It is a local command whose answer the board wants
+   * on the row immediately; the pre-review is a model call that may take
+   * minutes. Ordering them the other way would put a label behind a label.
+   *
+   * NEITHER MAY THROW PAST THIS POINT. Both are optional readouts and both run
+   * INSIDE the place's writer lock on a path whose callers settle real work —
+   * `runAgentMerge` in particular reports a claimed merge after this returns.
+   */
+  const runReviewEntry = async (agentId, wt, agentName) => {
+    try {
+      await runCheck(agentId, wt);
+    } catch {
+      /* the row keeps its previous check answer, which is null the first time */
+    }
+    try {
+      await runPrecheck(agentId, wt, agentName);
+    } catch {
+      /* no pre-review is posted, and absence renders nothing */
+    }
+  };
+
   // ── THE MERGE ──────────────────────────────────────────────────────────────
   //
   // LEASED, because two `git merge --no-ff` and two pushes over one branch is
@@ -5514,9 +5906,12 @@ export function createWorkManager({
           });
           return;
         }
-        // The branch changed, so the previous check answered about a different
-        // tree. Re-run it before anything merges.
-        await runCheck(agentId, wt);
+        // The branch changed, so the previous check — and the previous
+        // pre-review — answered about a different tree. Re-read it before
+        // anything merges: a failed merge sends the agent BACK to review, which
+        // is a review-entry beat like any other, and a stale reading standing
+        // over a rebased branch is exactly what `precheckSha` exists to void.
+        await runReviewEntry(agentId, wt, job.agentName);
       }
       // `git()` THROWS on a non-zero exit, and `symbolic-ref` exits non-zero on
       // a detached HEAD — so the guard below was unreachable and the throw

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {