flowviant 0.86.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
@@ -108,9 +122,27 @@ export function parseProposal(text) {
       ...(Number.isFinite(g.pointsBudget) && g.pointsBudget > 0
         ? { pointsBudget: Math.min(Math.round(g.pointsBudget), 100_000) }
         : {}),
-      ...(Array.isArray(g.waitsOn)
-        ? { waitsOn: g.waitsOn.filter((w) => typeof w === 'string' && w).slice(0, 20) }
-        : {}),
+      // NO `waitsOn`, AND ITS ABSENCE IS THE FEATURE (2026-09-16).
+      //
+      // The planner's schema used to carry it — tempIds of agents that had to
+      // MERGE first — and the owner deleted the idea: "whats the point of
+      // dividing up the agents if one of the agents rely on waiting for one to
+      // finish? if thats the case have it be in the same agent." An agent
+      // already works its cards in order, so a chain split across two agents
+      // buys a second worktree, a second branch and a second review and then
+      // idles one of them; the only thing a split buys is SIMULTANEOUS work.
+      // SYSTEM_PLAN no longer mentions the key at all.
+      //
+      // So a model that emits it anyway is answering a schema it was not given
+      // — an older prompt cached in a resumed conversation, or invention — and
+      // reading it would create a silently-waiting agent through the exact door
+      // the prompt just closed. DROPPED, not REFUSED: this file's own law is
+      // lenient packaging, strict shape, and a stray key is packaging. The
+      // proposal is otherwise good work the operator already paid for.
+      //
+      // The SERVER still accepts and honours `waitsOn` on the wire — 0.86.0
+      // daemons are still proposing it and existing agents still carry it. This
+      // is the end of PROPOSING one, not the end of reading one.
       ...(typeof g.intoAgentId === 'string' && g.intoAgentId
         ? { intoAgentId: g.intoAgentId.slice(0, 64) }
         : {}),
@@ -140,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
@@ -185,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/claude.mjs

@@ -13,7 +13,7 @@
 
 import { spawn } from 'node:child_process';
 import { SAFE } from './config.mjs';
-import { runtimeById, humanizeClaudeTool } from './runtimes.mjs';
+import { runtimeById, humanizeClaudeTool, THINK_MARKER } from './runtimes.mjs';
 
 // Every prompt/kickoff constant lives in prompts.mjs and is re-exported here:
 // a dozen call sites import them from claude.mjs, and none of them care where
@@ -197,12 +197,39 @@ function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText
   if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
     for (const b of ev.message.content) {
       if (b.type === 'thinking' || b.type === 'redacted_thinking') {
-        // The `thinking` text is usually redacted (signature only), so emit a
-        // marker — enough to show Claude is actively reasoning, not hung.
-        push({ kind: 'think', label: b.thinking ? `thinking: ${oneLine(b.thinking)}` : 'thinking…' });
+        /**
+         * NO THINKING TEXT ARRIVES TODAY, AND THAT IS MEASURED (2026-09-16).
+         *
+         * This used to say the text is "usually redacted", which was a guess
+         * doing the work of a fact. The fact: across three real transcripts, 93
+         * thinking blocks, EVERY ONE of them carried an empty `thinking` — and
+         * a live probe with MAX_THINKING_TOKENS set and
+         * `--include-partial-messages` on returned an empty `thinking_delta`
+         * and a complete block of length zero (signature only). So the CLI
+         * emits the FACT that it reasoned and not a word of the reasoning, and
+         * "show the full thinking" cannot be conjured from this stream.
+         *
+         * THE BRANCH BELOW EXISTS ANYWAY, and deliberately. The shape is the
+         * whole point: when text is present it rides `full` UNCLIPPED, so the
+         * day a CLI release starts emitting it, the trace carries the thought
+         * whole with no daemon change and no version floor — the report's own
+         * presence is the capability. Until then every block takes the marker
+         * arm, and `trace.mjs` collapses a run of identical markers so the
+         * absence reads as one quiet step rather than forty.
+         */
+        push(
+          b.thinking
+            ? { kind: 'think', label: `thinking: ${oneLine(b.thinking)}`, full: b.thinking }
+            : { kind: 'think', label: THINK_MARKER }
+        );
       } else if (b.type === 'text' && b.text?.trim()) {
         if (!answerFromResult) appendText(b.text + '\n');
-        push({ kind: 'say', label: oneLine(b.text) });
+        // `label` for the console and the pulse — one collapsed 160-char line,
+        // byte-identical to what it has always printed. `full` for the trace:
+        // a `say` is the agent NARRATING, several sentences at a time, and the
+        // clip at 160 was landing mid-sentence on the one thing a person opens
+        // the page to read.
+        push({ kind: 'say', label: oneLine(b.text), full: b.text });
       } else if (b.type === 'tool_use') {
         push(humanizeToolUse(b.name, b.input || {}, cwd));
         // The STRUCTURED form of the same event, for the transcript's tool

package/bin/lib/fleet.mjs

@@ -82,6 +82,7 @@ import {
   probeSkillsOnce,
   recordSkills,
   RUNTIMES,
+  THINK_MARKER,
 } from './runtimes.mjs';
 import { createWorkManager } from './work.mjs';
 import { scanLocalSessions, ourConversationIds } from './localSessions.mjs';
@@ -1598,7 +1599,13 @@ export async function runFleetDaemon() {
             pagesSeen.add(a.path || a.label);
           }
           // Collapse runs of bare "thinking…" so the feed doesn't fill with it.
-          if (!(a.label === 'thinking…' && feed[feed.length - 1] === 'thinking…')) {
+          // Keyed on the SHARED constant (runtimes.mjs), not on the literal: the
+          // labels being compared here are the ones claude.mjs now builds from
+          // that constant, so a reworded marker would leave this comparison
+          // matching nothing and the 48-slot feed filling with the repeat — the
+          // exact noise this line exists to stop, and silent, because a collapse
+          // that stops collapsing fails no test.
+          if (!(a.label === THINK_MARKER && feed[feed.length - 1] === THINK_MARKER)) {
             feed.push(a.label);
             if (feed.length > 48) feed.shift();
           }

package/bin/lib/prompts.mjs

@@ -588,6 +588,35 @@ export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages =
  * TOUCHED. Everything else — how long something will take, who should own it,
  * whether it is a good idea — is not a question a planner can answer from a
  * repository, and asking for it produces confident invention.
+ *
+ * ── THERE IS NO WAY TO SAY "THIS ONE WAITS" (2026-09-16) ──
+ *
+ * The answer schema used to carry `waitsOn`, a list of tempIds an agent had to
+ * see MERGE before it could start, and the owner deleted the idea outright:
+ *
+ *   "for the planning agent, whats the point of dividing up the agents if one
+ *    of the agents rely on waiting for one to finish? if thats the case have it
+ *    be in the same agent. the point of having it divide into various agent is
+ *    so that its capable of parallel and simultaneous work."
+ *
+ * That is not a preference about a field, it is what an agent IS. An agent is
+ * one CLI in one worktree working its cards IN ORDER — ordering is the thing it
+ * already does, for free, with no branch to merge in between. So a planner that
+ * splits a chain across two agents has bought nothing and paid twice: a second
+ * worktree, a second branch, a second review, and a second agent sitting idle
+ * until the first one lands. The ONLY thing a split buys is two CLIs typing at
+ * the same time, and work that waits cannot do that by definition.
+ *
+ * So the vocabulary is gone rather than discouraged. A rule the model can still
+ * express a violation of is a rule it will sometimes express a violation of;
+ * removing the key removes the move. Rule 1 below carries the reasoning in the
+ * planner's own terms, and `agentPlan.mjs` drops the key if a model on an older
+ * prompt sends it anyway.
+ *
+ * WHAT DID NOT CHANGE, on purpose: the SERVER still accepts `waitsOn` on the
+ * wire and still honours it on stored proposals, because 0.86.0 daemons are
+ * still running and agents created under the old prompt still exist. This is a
+ * change to what is PROPOSED, not to what can be read.
  */
 export const SYSTEM_PLAN = `You are the human's own Claude, planning a batch of work in their repository.
 
@@ -602,8 +631,13 @@ as a single reviewable branch.
 THE RULES THAT MATTER:
 
 1. SEQUENTIAL WORK BELONGS IN ONE AGENT. If B needs A's code to exist, put them
-   in the same agent, A first. Splitting a chain across agents means the second
-   one waits for the first to MERGE before it can even start.
+   in the same agent, A first — an agent works its cards in the order you give,
+   so ordering is free and costs no merge in between. THE ONLY REASON TO SPLIT
+   IS WORK THAT CAN RUN AT THE SAME TIME. There is no way to say that one agent
+   waits for another, and that is deliberate: an agent that has to wait is a
+   split done wrong. Splitting a chain buys a second worktree, a second branch
+   and a second review, and the second agent sits idle until the first one
+   merges — slower than one agent doing both in order.
 
 2. SPLIT ONLY WHAT CAN GENUINELY RUN AT THE SAME TIME. Two agents editing the
    same files land two branches that conflict, and somebody resolves it by hand.
@@ -641,7 +675,6 @@ after it. Wrap it in a \`\`\`json fence:
       "name": "auth",
       "taskIds": ["<card id>", "<card id>"],
       "pointsBudget": 8,
-      "waitsOn": [],
       "intoAgentId": null
     }
   ]
@@ -649,7 +682,7 @@ after it. Wrap it in a \`\`\`json fence:
 \`\`\`
 
 Every selected card id must appear EXACTLY ONCE across all agents. Use the ids
-exactly as given. "waitsOn" holds tempIds of agents that must MERGE first.`;
+exactly as given.`;
 
 /**
  * The planner's turn.
@@ -797,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.
  *
@@ -819,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.`;