flowviant 0.116.0 → 0.124.0

package/bin/lib/agentPlan.mjs

@@ -25,9 +25,13 @@
  * Run: node --test bin/lib/agentPlan.test.mjs
  */
 
-// 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 './uplinkScrub.mjs';
+// THE UPLINK SCRUBBER, as the DEFAULT for the three readers whose every string
+// goes to the server (2026-09-24, the audit; the precheck joined 2026-10-10).
+// See `parseTurnResult`. `scrubCut` is the scrub-then-cut order, spelled once.
+import { scrub as envScrub, scrubCut } from './uplinkScrub.mjs';
+import { groupDependencies } from './planDependencies.mjs';
+import { AGENT_TASK_KINDS } from './agentTaskKinds.mjs';
+import { blockedAnswer } from './agentAsk.mjs';
 
 /** The biggest a single proposal may be. Bounds on a machine, not a policy:
  *  the server caps these again at its own boundary. */
@@ -68,7 +72,8 @@ const MAX_NOTE = 1000;
  * none of which a real answer comes near:
  *
  *  · only the LAST `MAX_SCAN_CHARS` are scanned — every contract here puts the
- *    object LAST, and the fenced block is still looked for in the whole text;
+ *    object LAST, and the fenced block is still looked for in the whole text,
+ *    by a LINEAR scan (`fencedBody`) since 2026-10-10;
  *  · each `{`'s closing brace is found ONCE (see `closers`), so the scan is a
  *    single right-to-left pass instead of one walk per brace;
  *  · only spans that can open an object (`{` then a key or `}`) are handed to
@@ -90,10 +95,10 @@ const MAX_NESTED_PARSES = 200;
 const MAX_NESTED_CHARS = 4 * 1024 * 1024;
 
 export function candidateObjects(text) {
-  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const fenced = fencedBody(text);
   const raw = text.length > MAX_SCAN_CHARS ? text.slice(text.length - MAX_SCAN_CHARS) : text;
   const bodies = [];
-  if (fenced) bodies.push(fenced[1]);
+  if (fenced !== null) bodies.push(fenced);
   const close = closers(raw);
   let topEnd = -1;
   let nestedParses = 0;
@@ -125,6 +130,35 @@ export function candidateObjects(text) {
   return out;
 }
 
+/**
+ * THE FIRST FENCED BLOCK'S BODY, or null — what
+ * `text.match(/```(?:json)?\s*([\s\S]*?)```/)[1]` answered, found in ONE
+ * forward pass (2026-10-10, the audit's F079).
+ *
+ * That regex ran over the WHOLE text — the only search the `MAX_SCAN_CHARS`
+ * bound above skipped — and it backtracks quadratically on an opening fence
+ * followed by a long whitespace run with no closing fence: the greedy `\s*` and
+ * the lazy body re-scan the run from every split. Measured: 80 KB took 0.6 s,
+ * 320 KB nine seconds, of synchronous CPU in which no poll, lease or other
+ * lane moved — and a turn's stdout is model-written and uncapped. Same
+ * answer, by `indexOf`: the first ``` anywhere, an optional `json`, the
+ * whitespace after it skipped, and the body runs to the next ```. If that
+ * opening has no closer, no later opening can have one either, so there is no
+ * fence. The search stays over the whole text, as the bound above promises.
+ */
+const FENCE_SPACE = /\s*/y;
+function fencedBody(text) {
+  const open = text.indexOf('```');
+  if (open < 0) return null;
+  let at = open + 3;
+  if (text.startsWith('json', at)) at += 4;
+  FENCE_SPACE.lastIndex = at;
+  FENCE_SPACE.exec(text);
+  at = FENCE_SPACE.lastIndex;
+  const close = text.indexOf('```', at);
+  return close < 0 ? null : text.slice(at, close);
+}
+
 /**
  * For every `{`, the index of the `}` that closes it when read as the START of
  * an object (outside any string), or -1 — the answer `balanced` gives, for all
@@ -186,8 +220,9 @@ export function parseProposal(text, scrub = envScrub) {
     if (taskIds.length === 0) continue;
     agents.push({
       tempId: String(g.tempId || `a${i + 1}`).slice(0, 64),
-      name: String(scrub(String(g.name ?? ''))).slice(0, MAX_NAME),
+      name: scrubCut(g.name, MAX_NAME, scrub),
       taskIds,
+      ...(typeof g.rationale === 'string' ? { rationale: scrubCut(g.rationale, 1000, scrub) } : {}),
       ...(Number.isFinite(g.pointsBudget) && g.pointsBudget > 0
         ? { pointsBudget: Math.min(Math.round(g.pointsBudget), 100_000) }
         : {}),
@@ -218,10 +253,25 @@ export function parseProposal(text, scrub = envScrub) {
     });
   }
   if (agents.length === 0) return null;
+  const ids = new Set(agents.flatMap(g => g.taskIds));
+  const lines = (v) => Array.isArray(v) ? v.filter(x => typeof x === 'string').slice(0, 20).map(x => scrubCut(x, 300, scrub)) : [];
+  if (parsed.evidence !== undefined && (!Array.isArray(parsed.evidence) || parsed.evidence.length > 1200 || parsed.evidence.some(e => !ids.has(e?.taskId)))) return null;
+  const evidence = parsed.evidence?.map(e => ({ taskId: e.taskId, inspectedFiles: lines(e.inspectedFiles), affectedFiles: lines(e.affectedFiles), prerequisiteOutputs: lines(e.prerequisiteOutputs), ...(typeof e.limits === 'string' ? { limits: scrubCut(e.limits, 1000, scrub) } : {}) }));
+  const collisions = Array.isArray(parsed.collisions) ? parsed.collisions.map(c => ({ taskIds: c?.taskIds, files: lines(c?.files), rationale: scrubCut(c?.rationale, 1000, scrub) })) : parsed.collisions;
+  const grouped = groupDependencies(agents, parsed.dependencies, collisions);
+  if (!grouped) return null;
+  const dependencies = parsed.dependencies?.map(e => ({ taskId: e.taskId, requires: e.requires }));
   return {
-    agents: uniqueTempIds(agents),
+    agents: uniqueTempIds(grouped).map(g => ({ ...g, ...((evidence !== undefined || collisions !== undefined || parsed.dependencies !== undefined) ? { evidence: {
+      cards: (evidence ?? []).filter(e => g.taskIds.includes(e.taskId)),
+      dependencies: (dependencies ?? []).filter(e => g.taskIds.includes(e.taskId)),
+      collisions: (collisions ?? []).filter(c => c.taskIds.some(id => g.taskIds.includes(id))),
+    } } : {}) })),
+    ...(parsed.dependencies !== undefined ? { dependencies } : {}),
+    ...(collisions !== undefined ? { collisions } : {}),
+    ...(evidence !== undefined ? { evidence } : {}),
     ...(typeof parsed.note === 'string' && parsed.note.trim()
-      ? { note: String(scrub(parsed.note)).slice(0, MAX_NOTE) }
+      ? { note: scrubCut(parsed.note, MAX_NOTE, scrub) }
       : {}),
   };
 }
@@ -284,7 +334,7 @@ function uniqueTempIds(list) {
 const MAX_PROGRESS = 8000;
 const progressOf = (v, scrub) => {
   const t = typeof v.progress === 'string' ? v.progress.trim() : '';
-  return t ? { progress: String(scrub(t)).slice(0, MAX_PROGRESS) } : {};
+  return t ? { progress: scrubCut(t, MAX_PROGRESS, scrub) } : {};
 };
 
 /**
@@ -337,22 +387,32 @@ const progressOf = (v, scrub) => {
  * its prefix. So the scrub rides in, as `parsePrecheck`'s does, and runs over
  * each whole field first.
  *
- * DEFAULTED TO THE REAL SCRUBBER, unlike the precheck's identity default: the
- * production callers pass nothing, and a redaction that depends on each caller
- * remembering is the one that is missing the day it matters. Scrubbing twice
- * (the caller still scrubs `answer`) is harmless — a redaction marker contains
- * no secret to match.
+ * DEFAULTED TO THE REAL SCRUBBER, like `parseProposal` and (since 2026-10-10)
+ * `parsePrecheck`: the production callers pass nothing, and a redaction that
+ * depends on each caller remembering is the one that is missing the day it
+ * matters. Scrubbing twice (the caller still scrubs `answer`) is harmless — a
+ * redaction marker contains no secret to match.
  */
 export function parseTurnResult(text, scrub = envScrub) {
-  const clean = (s, cap) => String(scrub(s)).slice(0, cap);
+  const clean = (s, cap) => scrubCut(s, cap, scrub);
   for (const v of candidateObjects(String(text ?? ''))) {
+    if (v.status === 'prerequisite') {
+      const r = v.prerequisite;
+      if (!r || typeof r.title !== 'string' || !r.title.trim() || typeof r.brief !== 'string' || !r.brief.trim()
+        || typeof r.taskKind !== 'string' || !Object.hasOwn(AGENT_TASK_KINDS, r.taskKind)) continue;
+      return { outcome: 'question', answer: typeof v.summary === 'string' ? clean(v.summary, 8000) : 'Requested a prerequisite card.',
+        ...progressOf(v, scrub), prerequisite: { title: clean(r.title.trim(), 300), brief: clean(r.brief.trim(), 2000), taskKind: r.taskKind } };
+    }
     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
       // parks an agent with nothing to reply to. Treated as `nothing`, which
       // at least says truthfully that the machine went quiet.
       if (!question) continue;
-      return { outcome: 'question', answer: clean(question, 8000), ...progressOf(v, scrub) };
+      // Its declared choices (2026-10-13) ride on as the one fence the page
+      // reads, built here (agentAsk.mjs); malformed ones leave the question
+      // as plain text.
+      return { outcome: 'question', answer: blockedAnswer(clean(question, 8000), v, scrub), ...progressOf(v, scrub) };
     }
     if (v.status === 'delivered') {
       return {
@@ -377,12 +437,43 @@ export function parseTurnResult(text, scrub = envScrub) {
 }
 
 /** 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
+ *  again, and held to it by the release gate (check-app-parity.mjs rule 31).
+ *  A note is one sentence of triage and `overall` a few short points; 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;
+export const MAX_PRECHECK_CARDS = 60;
+export const MAX_PRECHECK_NOTE = 400;
+export const MAX_PRECHECK_OVERALL = 1200;
+/** Per-criterion results (2026-10-10): the criteria kept per card, a
+ *  criterion's own text, and its one line on why. */
+export const MAX_PRECHECK_CRITERIA = 12;
+export const MAX_PRECHECK_CRITERION = 200;
+export const MAX_PRECHECK_LINE = 160;
+
+/**
+ * ONE CARD'S CRITERIA, as the reader judged them (2026-10-10).
+ *
+ * PER ENTRY, the rule cards keep: a verdict word nobody listed, a missing or
+ * blank criterion, or a line that is not a string costs that row alone. A
+ * null line is the model saying it has none, so it reads as absent. The
+ * criterion's TEXT is kept, never an index: the card's Done-when list can be
+ * edited after the reading, and the row must show what was judged.
+ */
+function precheckCriteria(raw, scrub) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const k of raw) {
+    if (out.length >= MAX_PRECHECK_CRITERIA) break;
+    if (!k || typeof k !== 'object') continue;
+    if (typeof k.criterion !== 'string' || !k.criterion.trim()) continue;
+    if (k.verdict !== 'met' && k.verdict !== 'concern' && k.verdict !== 'unclear') continue;
+    if (k.line != null && typeof k.line !== 'string') continue;
+    const criterion = scrubCut(k.criterion.trim(), MAX_PRECHECK_CRITERION, scrub);
+    const line = typeof k.line === 'string' ? scrubCut(k.line.trim(), MAX_PRECHECK_LINE, scrub) : '';
+    out.push({ criterion, verdict: k.verdict, ...(line ? { line } : {}) });
+  }
+  return out;
+}
 
 /**
  * READING THE AI PRE-REVIEW's ANSWER (2026-09-16).
@@ -404,6 +495,11 @@ const MAX_PRECHECK_OVERALL = 1200;
  * 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.
  *
+ * EACH CARD MAY CARRY ITS CRITERIA (2026-10-10), one entry per "done when"
+ * line, beside — never instead of — its verdict and note: a server from before
+ * criteria strips the field and still draws the one-row panel from those two.
+ * No criteria is no key, so that body is byte for byte what it was.
+ *
  * `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
@@ -416,11 +512,15 @@ const MAX_PRECHECK_OVERALL = 1200;
  * 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.
+ * DEFAULTED TO THE REAL SCRUBBER (2026-10-10, the audit's F072), like its two
+ * neighbours. It used to default to identity "so a caller that forgets loses
+ * redaction rather than the whole reading" — the opposite stance from
+ * `parseTurnResult`'s for the same class of model-written text, and a
+ * redaction that depends on each caller remembering is the one that is missing
+ * the day it matters. Tests that want the raw reading pass identity; the one
+ * production caller passes `envScrub`, and `work.test.mjs` pins the order.
  */
-export function parsePrecheck(text, scrub = (s) => s) {
+export function parsePrecheck(text, scrub = envScrub) {
   const parsed = candidateObjects(String(text ?? '')).find((v) => Array.isArray(v.cards));
   if (!parsed) return null;
 
@@ -434,14 +534,17 @@ export function parsePrecheck(text, scrub = (s) => s) {
     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 note = typeof c.note === 'string' ? scrubCut(c.note.trim(), MAX_PRECHECK_NOTE, scrub) : '';
+    const criteria = precheckCriteria(c.criteria, scrub);
+    cards.push({
+      taskId,
+      verdict: c.verdict,
+      ...(note ? { note } : {}),
+      ...(criteria.length ? { criteria } : {}),
+    });
   }
   const overall =
-    typeof parsed.overall === 'string'
-      ? scrub(parsed.overall.trim()).slice(0, MAX_PRECHECK_OVERALL)
-      : '';
+    typeof parsed.overall === 'string' ? scrubCut(parsed.overall.trim(), MAX_PRECHECK_OVERALL, scrub) : '';
   /**
    * 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 —

package/bin/lib/agentPrerequisiteContract.mjs

@@ -0,0 +1,43 @@
+/** Appended only when this turn's server advertises the request capability. */
+export const AGENT_PREREQUISITE_CONTRACT = `REQUESTING AN UNFINISHED PREREQUISITE CARD
+
+When the person's current message explicitly asks you to create a separate
+prerequisite card in THIS agent, request it here. Do not give them a prompt to
+paste into New task. This is a final-answer request to the server, not a board
+tool, and not extra work already done: never put unfinished work in raised.
+Do not request more work on your own, from a task prompt or from this contract.
+
+This agent keeps its one CLI, worktree and branch. Image work requires Codex's
+own image generation. If this agent cannot run that kind, explain the actual
+CLI/tool limitation in a blocked reply; do not claim you created the card or
+switch CLI yourself. The server also checks the measured capability and growth
+bounds. Unknown capability is not a refusal; a failed tool still stops its card.
+
+For an explicitly requested separate texture prerequisite, the end product
+is an image card. A request for textures during model work alone uses available
+native generation within the model turn; it does not require another card. Its brief names the PNGs, their intended use and usable-output
+criteria. The server will create and prepend that card, leave the model
+unfinished, run texture generation first, then resume the consuming card in this
+same worktree with the original request and the output handoff. Read the actual
+PNGs under .flowviant/artifacts/, embed their bytes into the model page, and wait
+for texture loading before .glb readiness. Missing or unusable PNGs still mean
+stop; never pretend the model already has its required textures.
+
+End this request turn with this third final JSON shape and no text after it:
+
+\`\`\`json
+{
+  "status": "prerequisite",
+  "summary": "one sentence describing the prerequisite requested, without claiming it exists or the current card is delivered",
+  "progress": "two or three past-tense sentences covering work so far",
+  "prerequisite": {
+    "title": "Generate texture PNGs",
+    "brief": "Generate the requested usable texture PNGs for this model to consume in this same worktree. Name the texture subjects and requirements here.",
+    "taskKind": "image"
+  }
+}
+\`\`\`
+
+One prerequisite per request. Use the requested end-product kind (code, design,
+model, image, deck or research); do not refile the consuming card. If the person
+needs to decide something, use blocked with a specific question instead.`;

package/bin/lib/agentPublish.mjs

@@ -27,7 +27,7 @@
  * SHAPE, never a path, never a value that reaches argv unread.
  */
 
-import { isSafePathSegment } from './git.mjs';
+import { isValidSha, sessionBranchRef, stripUrlUserinfo } from './git.mjs';
 
 /**
  * THE SHAPE A PUBLISHED REF MAY HAVE — the server's own `PUBLISH_REF_RE`,
@@ -52,19 +52,19 @@ export function isPublishRef(ref) {
   return typeof ref === 'string' && PUBLISH_REF_RE.test(ref);
 }
 
-/** The local branch an agent works on. One definition, so a push, a fetch and
- *  the begun-guard's own `rev-parse` can never name three different branches. */
-export function agentBranchRef(place) {
-  return isSafePathSegment(place) ? `refs/heads/session/${place}` : null;
-}
+/** The local branch an agent works on. One definition — git.mjs's
+ *  `sessionBranchRef`, the same name the cutter and the begun-guard read — so
+ *  a push, a fetch and the guard's own `rev-parse` can never name three
+ *  different branches. */
+export const agentBranchRef = sessionBranchRef;
 
 /** A sha this machine MEASURED, in the one form `rev-parse` prints. The lease
  *  below is built from nothing else: an unrecognised value is treated as no
- *  observation at all rather than interpolated into argv. */
-const SHA_RE = /^[0-9a-f]{7,40}$/;
-export function isSha(v) {
-  return typeof v === 'string' && SHA_RE.test(v);
-}
+ *  observation at all rather than interpolated into argv. git.mjs's
+ *  `isValidSha`, re-exported under the name this module's readers use — it
+ *  was a verbatim copy of that regex, so a tightening could land in one and
+ *  not the other (audit 2026-10-10, F749). */
+export const isSha = isValidSha;
 
 /**
  * PUSH THIS AGENT'S BRANCH TO ITS PUBLISHED NAME.
@@ -153,8 +153,7 @@ export function publishDeleteArgs(ref) {
  */
 const DIAGNOSTIC_RE = /^(fatal:|error:|remote:|!)|\b(denied|rejected|refused)\b/i;
 export function publishErrorText(raw) {
-  const lines = String(raw ?? '')
-    .replace(/\/\/[^/@\s]+@/g, '//')
+  const lines = stripUrlUserinfo(raw)
     .split('\n')
     .map((l) => l.trim())
     .filter(Boolean);

package/bin/lib/agentTaskKinds.mjs

@@ -37,9 +37,9 @@
  *  which Claude and — since 0.115.0 — Codex declare (2026-09-29, measured:
  *  runtimeCodex.mjs `codexDesignFence`). */
 const DESIGN_CLIS = 'mockup, 3D model and presentation cards run on Claude or Codex on this machine';
-/** The write-up kind runs on Claude alone: Codex cannot fence the web it needs
- *  apart from the whole-box reads its sandbox allows (same place). */
-const CLAUDE_ONLY = 'write-up cards run on Claude on this machine';
+/** Write-ups run on Claude or isolated Codex (0.117.0); the copied input view
+ *  keeps host credentials outside the web-enabled tool fence. */
+const RESEARCH_CLIS = 'write-up cards run on Claude or Codex on this machine';
 /** The image kind runs on Codex: the one CLI that declares its posture, because
  *  the pictures come from Codex's own image tool on its own login. */
 const CODEX_ONLY = 'image cards run on Codex on this machine';
@@ -90,7 +90,7 @@ export const AGENT_TASK_KINDS = Object.freeze({
     posture: 'image',
     artifact: Object.freeze({
       match: /\.(png|webp)$/i,
-      missing: 'the turn ended without writing a PNG or WebP image under .flowviant/artifacts/',
+      missing: 'the turn ended without writing a usable PNG or WebP image under .flowviant/artifacts/',
     }),
     offRuntime: () => CODEX_ONLY,
   }),
@@ -109,7 +109,7 @@ export const AGENT_TASK_KINDS = Object.freeze({
       match: /\.md$/i,
       missing: 'the turn ended without writing a write-up under .flowviant/artifacts/',
     }),
-    offRuntime: () => CLAUDE_ONLY,
+    offRuntime: () => RESEARCH_CLIS,
   }),
 });
 
@@ -144,9 +144,6 @@ export const unknownAgentTaskKind = (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; the
  *  image kind has its own. */

package/bin/lib/agySessions.mjs

@@ -13,6 +13,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { procPids, scanProcs } from './procScan.mjs';
+import { AGY_CONV_RE } from './conversationIds.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),
@@ -24,13 +25,12 @@ import { procPids, scanProcs } from './procScan.mjs';
 // 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;
+  if (!AGY_CONV_RE.test(id)) return 0;
   let newest = 0;
   for (const suffix of ['.db', '.db-wal']) {
     try {
@@ -121,7 +121,7 @@ export function scanAgyConversations({ ours, mine, cutoff, processAlive = agyPro
     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;
+      if (typeof id !== 'string' || !AGY_CONV_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;

package/bin/lib/artifactContracts.mjs

@@ -6,7 +6,7 @@
  * 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` —
+ * repo, write only artifacts and scratch, with CLI-specific supporting tools —
  * so "change no repository file" is enforced, not asked.
  *
  * THE SAME BONES AS THE DESIGN CONTRACT, deliberately: its header, its rule 3
@@ -26,13 +26,70 @@
  */
 import { ARTIFACT_BINARY_MODEL_EXTS, ARTIFACT_BINARY_MODEL_MAX_BYTES, ARTIFACT_MAX_BYTES } from './artifactPolicy.mjs';
 
+/**
+ * WHEN AN AGENT STOPS TO ASK, IT HELPS THE PERSON DECIDE (2026-10-03; its
+ * choices as fields of their own, 2026-10-13).
+ *
+ * "STOP AND ASK" used to be the whole of it, so a stuck agent asked one bare
+ * question with its choices inlined as "(1) … (2) …", and the Agent page had
+ * nothing to draw but "Write my own answer". Every card-agent contract (code
+ * and every file-handing kind) closes on this: read the card, the repo and
+ * the run first; ask ONE question per turn, its reason in `context` (body
+ * text beneath the one-line question, 2026-10-13); name the choices
+ * in `options` (and `multiSelect`) beside `question`, which the daemon turns
+ * into the one fence the page reads (`agentAsk.mjs`) — the agent never writes
+ * the fence itself, the owner's ruling; re-check after each answer; never
+ * re-ask. The label rules are SYSTEM_WORK rule 5's, because the page sends a
+ * label as the answer exactly as the Terminal's card does.
+ *
+ * THE SKIP IS THE APP'S. The agent page offers "Skip this question" on every
+ * standing question and sends a reply that BEGINS with those words (Flowviant
+ * `AGENT_SKIP_REPLY`) through the ordinary answer lane — so this keys on the
+ * prefix, never the whole sentence, and the app's wording can change without
+ * a daemon release. A skip is a stated provisional default where the work can
+ * go on, and never a substitute for an input only the person holds.
+ */
+export const HELP_THEM_DECIDE = `WHEN YOU STOP TO ASK, HELP THEM DECIDE. The person may not know what the card
+is missing, so you lead:
+- Before asking, read the whole card (brief, done-when and its discussion),
+  the repository and this run, and check the card for every gap that would
+  change the work: the goal, who it is for, scope, the flows and behaviour,
+  edge cases, constraints, and how done is judged. Never ask what the card,
+  the repository or an earlier answer already settles.
+- Ask ONE question per turn, the one that matters most. "question" is the
+  question itself — one sentence, read as a heading. In "context", say what
+  decision it settles and how it changes the work, with any findings or
+  evidence the person needs; it shows beneath the question as body text, in
+  Markdown, so lists and line breaks survive.
+- When the answer is a pick between options you can name, put them in
+  "options" — two to eight — and the page shows each as a choice beside a
+  box for their own words. Never inline the choices in "question" as
+  "(1) … (2) …", and never write a fenced block yourself: the fields are the
+  whole of it. A label IS the answer, a few words a person would say out
+  loud, never a comma (several chosen labels arrive comma-joined, in the
+  order listed); a tradeoff goes in "description", one short sentence,
+  optional. Never add an "Other" or "Skip" option — the page offers its own
+  free-text answer and its own Skip. "multiSelect": true only for a genuine
+  check-several-of-these case ("which pages?"); otherwise false. For an open
+  question — one only their own words can answer — leave "options" out.
+- When they answer, check the card again before you go on: ask the next
+  question that still changes the work, or carry on with the card once none
+  is left. Never ask again a question they answered or skipped.
+- A message that begins "Skip this question" skips your last question. Where
+  the work can go on, take your best default, say it plainly as PROVISIONAL in
+  "progress" and in "summary", and carry on. Where it truly cannot go on
+  without something only they can provide — a credential, an account, an
+  outside decision — stop and name exactly that dependency; a skip never
+  supplies it.`;
+
 /**
  * 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.
+   .flowviant/artifacts/ and the turn’s granted scratch directory; deliver
+   only artifacts. The daemon keeps those directories out of git.
 
 4. ${ask}
 
@@ -52,12 +109,17 @@ or, if you are stopping to ask:
 {
   "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"
+  "context": "optional: what the decision settles and why, and any findings, in Markdown",
+  "question": "the specific thing you need decided, in one sentence",
+  "options": [{ "label": "an answer they could pick", "description": "optional: its tradeoff, in one short sentence" }],
+  "multiSelect": false
 }
 \`\`\`
 
 "progress" is REQUIRED on both shapes and REPLACES the previous one whole —
-past tense, plain sentences, no card ids.`;
+past tense, plain sentences, no card ids.
+
+${HELP_THEM_DECIDE}`;
 
 /**
  * NOBODY IS AT THIS SCREEN (2026-09-29, the owner: Chrome "kept opening on my
@@ -87,13 +149,10 @@ export const LOOK_HEADLESS = `${NO_WINDOW} To look at your page, screenshot it
  * when the person presses Download .glb in Review (apps/web
  * `workbench/glbExport.ts`, the other half of the handshake below).
  *
- * WHY NOT A MODEL FILE ON DISK. This kind runs under the `design` posture:
- * Read, `ls`, and `Edit(.flowviant/artifacts/**)` — text only, no shell. A
- * .glb is binary; a .gltf's buffer is base64 floats nobody writes by hand.
- * The 0.105.0 contract asked for OBJ + .mtl + SVG textures instead, and a
- * katana came back as seven files, textures no game engine imports and a
- * generator script (2026-09-27). Built in code, drawn textures are canvases,
- * and the exporter embeds them in the .glb as PNGs.
+ * WHY A PAGE: one self-contained viewer gives every supported CLI the same
+ * delivered product. Supporting native textures are embedded into the page;
+ * GLTFExporter embeds their pixels into the person's one downloaded GLB.
+ * Available helpers do not change that contract into a pile of model files.
  *
  * THE HANDSHAKE IS SPELLED WORD FOR WORD because the web keys on it: the page
  * announces `glb-ready` once its model stands, and answers `export-glb` with
@@ -103,8 +162,8 @@ export const LOOK_HEADLESS = `${NO_WINDOW} To look at your page, screenshot it
  * it is just never offered a Download .glb.
  */
 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.
+their repository. Nobody is watching this run. You have the repo and the tools
+TOOLS ON THIS CARD names below — 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, downloads it as
@@ -121,7 +180,8 @@ WHAT TO DO:
 2. Write ONE file, .flowviant/artifacts/<kebab-name>/index.html — a short
    kebab-case name for what it is (for example
    .flowviant/artifacts/reading-chair/index.html). Nothing else goes in that
-   folder: no model files, no textures, no scripts, no notes. The page BUILDS
+   folder: no model files, no scripts, no notes. Generated source textures
+   may be kept elsewhere under .flowviant/artifacts/; the page is self-contained. The page BUILDS
    THE MODEL IN CODE and shows it:
    - three.js as ES modules from cdn.jsdelivr.net/npm, through an import map
      for "three" and "three/addons/"; orbit controls, lights and a neutral
@@ -129,8 +189,18 @@ WHAT TO DO:
    - the model is ONE THREE.Group named for what it is, built from three.js
      geometry (lathe, extrude, tube, box and the rest, one mesh per part),
      with MeshStandardMaterial only. Colour, roughness and metalness are
-     material values, or textures you DRAW ON A CANVAS in the page
-     (THREE.CanvasTexture, 1024px or less) — never an image file.
+     material values, canvas textures, or generated image textures. When the
+     person requests generated textures, USE native image generation if it is
+     available on this turn; do not require another card or change the kind.
+     Embed each texture as a data: URI in this page (no local or remote image
+     URLs), load it with THREE.TextureLoader and wait for all textures before
+     announcing glb-ready. Keep maps at 1024px or less and set colour maps to
+     THREE.SRGBColorSpace. Assign maps to the model's MeshStandardMaterial so
+     GLTFExporter embeds the texture pixels in the downloaded .glb. Await
+     image decoding before export; never announce readiness for unloaded maps.
+     If the native tool is missing or fails, explain its actual limitation.
+     A separately billed CLI/API fallback requires the person's explicit
+     choice before using it; never ask for OPENAI_API_KEY as the default path.
    - the ground, a grid, the lights, a figure for scale and every other
      helper stay OUTSIDE that group: they are the viewer's, not the model.
    - no download or save button of your own: the page cannot download
@@ -168,8 +238,8 @@ ${ARTIFACT_CONTRACT_TAIL({
  * 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.
+of their repository. Nobody is watching this run. You have the repo and the tools
+TOOLS ON THIS CARD names below — 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.
@@ -232,8 +302,9 @@ export const IMAGE_CAP_WORDS = `${Math.floor(imageCapBytes / (1024 * 1024))} MB`
  * to the person, quoting the tool's words, never a substitute.
  */
 export const SYSTEM_AGENT_IMAGE = `You are the human's own Codex, working one IMAGE card in a git worktree of
-their repository. Nobody is watching this run. You have the repo and your image
-generation tool, and nothing else — no project tools, no board, no chat, no web.
+their repository. Nobody is watching this run. You have the repo, your image
+generation tool and the tools TOOLS ON THIS CARD names below — no board, no
+chat, no web.
 
 AN IMAGE CARD HANDS BACK PICTURES, NOT A CHANGE. Nothing you do here edits the
 product: the person looks at the images, downloads the ones they want, and