flowviant 0.117.0 → 0.124.1

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

package/bin/lib/artifactIteration.mjs

@@ -0,0 +1,182 @@
+/** Explicit iteration relationships, plus measured local deletions. No model runs here. */
+import { constants, openSync, closeSync, fstatSync, readFileSync, lstatSync, unlinkSync, realpathSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { flowviantParentState, realDirState } from './ownedDirs.mjs';
+import { ARTIFACT_DIR, artifactStoredName, walkArtifactDir } from './artifacts.mjs';
+
+const MANIFEST = '.iteration.json';
+const safeName = (name) => typeof name === 'string' && name.length <= 500 &&
+  name.split('/').every((p) => p && p !== '.' && p !== '..' && !p.startsWith('.') && !p.includes('\\'));
+
+const manifestText = (placeDir) => {
+  if (!walkArtifactDir(placeDir, () => {})) return null;
+  let fd;
+  try {
+    fd = openSync(join(placeDir, ARTIFACT_DIR, MANIFEST), constants.O_RDONLY | constants.O_NOFOLLOW);
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > 32 * 1024) return null;
+    return { text: readFileSync(fd, 'utf8'), stamp: `${st.size}:${st.mtimeMs}` };
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+};
+const signature = (value) => value === null ? null : `${value.stamp}:${createHash('sha256').update(value.text).digest('hex')}`;
+export const iterationSignature = (placeDir) => signature(manifestText(placeDir));
+
+export function iterationChanges(placeDir, before) {
+  const text = manifestText(placeDir);
+  if (text === null || signature(text) === before?.iterationSignature) return { remove: [], replace: {} };
+  let value;
+  try { value = JSON.parse(text.text); } catch { throw new Error('Artifact iteration declaration is not valid JSON.'); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Artifact iteration declaration must be an object.');
+  const remove = value.remove ?? [];
+  const replace = value.replace ?? {};
+  if (!Array.isArray(remove) || remove.length > 40 || !remove.every(safeName) ||
+      !replace || typeof replace !== 'object' || Array.isArray(replace) || Object.keys(replace).length > 40 ||
+      !Object.entries(replace).every(([from, to]) => safeName(from) && safeName(to) && from !== to)) {
+    throw new Error('Artifact iteration needs remove names and explicit old-to-new replacement names.');
+  }
+  const removed = new Set([...remove, ...Object.keys(replace)]);
+  if (Object.values(replace).some((to) => removed.has(to))) throw new Error('A replacement cannot also be discarded.');
+  return { remove, replace };
+}
+
+/** Stored spellings of the regular files a place holds; null when its directory cannot be walked. */
+export function presentArtifacts(placeDir) {
+  const live = new Set();
+  return walkArtifactDir(placeDir, (e) => { if (e.kind === 'file') live.add(artifactStoredName(e.name)); }) ? live : null;
+}
+
+/**
+ * WHAT THIS PLACE HAS HELD, per owner (2026-10-11 follow-up). Local absence
+ * proves a discard only for a name this directory held: a handed-over or
+ * recreated worktree starts without its owner's delivery, which was stored
+ * from somewhere else. The record lives in the worktree's private git dir
+ * (the work manager's `seenPath`), so it dies with the worktree. Missing is
+ * null — a place never measured — and an unreadable record proves nothing.
+ */
+const SEEN_MAX_BYTES = 256 * 1024;
+const SEEN_MAX_NAMES = 2000;
+export function readSeenArtifacts(path) {
+  if (!path) return new Set();
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > SEEN_MAX_BYTES) return new Set();
+    const value = JSON.parse(readFileSync(fd, 'utf8'));
+    return new Set(Array.isArray(value) ? value.filter(safeName) : []);
+  } catch (e) {
+    return e?.code === 'ENOENT' ? null : new Set();
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+export function writeSeenArtifacts(path, names) {
+  if (!path) return;
+  const tmp = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify([...new Set(names)].filter(safeName).slice(0, SEEN_MAX_NAMES)));
+    renameSync(tmp, path);
+  } catch {
+    // An unwritten record leaves the place unmeasured, never a false discard.
+    try { rmSync(tmp, { force: true }); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * The owner's stored names this place counts as its own. A place measured
+ * before the record existed counts only rows stored AFTER it was cut
+ * (`bornAt`, the worktree's creation on the server's clock — `serverBornAt`):
+ * a moved agent's new worktree, or one
+ * recreated after retirement, never held what was stored before it existed —
+ * even when it has since regenerated one of those names. Among the rows it
+ * could have written, it held them all only while it still holds part of them:
+ * the delivery whose discards an older daemon never relayed. An unknown birth
+ * or an undated row proves nothing; an empty place proves nothing; and the
+ * record written now keeps a later same-name upload from proving it either.
+ */
+export function seenArtifacts(record, stored, present, bornAt = null) {
+  const names = new Set(stored.map((a) => a.name));
+  let seen = record;
+  if (!seen) {
+    const since = Number.isFinite(bornAt)
+      ? stored.filter((a) => storedAt(a) >= bornAt).map((a) => a.name) : [];
+    seen = since.some((n) => present.has(n)) ? new Set(since) : new Set();
+  }
+  return new Set([...seen, ...present].filter((n) => names.has(n) || present.has(n)));
+}
+/**
+ * THE PLACE'S BIRTH ON THE SERVER'S CLOCK, never earlier than it was. Rows are
+ * dated by the server and the birth by this machine, whose clock can run hours
+ * behind (a WSL clock after the host slept), which would make an older
+ * delivery read as stored after the cut. The inventory answer's `Date` was
+ * stamped after `sentAt` and floors to the second, so the true offset is below
+ * `Date + 1s - sentAt`: that bound can only exclude a row. No header, no bound,
+ * and so no legacy evidence.
+ */
+export function serverBornAt(bornAt, serverDate, sentAt) {
+  const server = Date.parse(serverDate ?? '');
+  return Number.isFinite(bornAt) && Number.isFinite(server) && Number.isFinite(sentAt)
+    ? bornAt + (server + 1000 - sentAt) : null;
+}
+/** A row's stored time in ms, or NaN — an older server sends none. */
+const storedAt = (a) => typeof a.createdAt === 'string' || typeof a.createdAt === 'number' ? new Date(a.createdAt).getTime() : NaN;
+
+/** A missing leaf is measured only through real, readable parent directories. */
+export function deletedArtifacts(placeDir, before) {
+  // Only names this place held are candidates: this turn's snapshot and the
+  // place's record (`before.seen`). Normalize live names before probing: a
+  // draft+1.md is stored as draft_1.md and is not an absent retained file.
+  const candidates = new Set([...(before?.keys() ?? []), ...(before?.seen ?? [])]);
+  const live = presentArtifacts(placeDir);
+  if (!live) {
+    return flowviantParentState(placeDir) === 'dir' && realDirState(join(placeDir, ARTIFACT_DIR)) === 'none'
+      ? [...candidates].filter(safeName).map(artifactStoredName) : [];
+  }
+  const removed = [];
+  for (const name of candidates) {
+    if (!safeName(name) || live.has(artifactStoredName(name))) continue;
+    let path = join(placeDir, ARTIFACT_DIR);
+    const parts = name.split('/');
+    for (let i = 0; i < parts.length; i++) {
+      path = join(path, parts[i]);
+      try {
+        lstatSync(path);
+        if (i < parts.length - 1 && realDirState(path) !== 'dir') break;
+      } catch (e) {
+        if (e.code === 'ENOENT') removed.push(artifactStoredName(name));
+        break;
+      }
+    }
+  }
+  return [...new Set(removed)];
+}
+
+/** A confirmed removal unlinks only the file measured for this report, never a later turn's rewrite. */
+export function localArtifact(placeDir, name) {
+  let entry = null;
+  walkArtifactDir(placeDir, (e) => { if (artifactStoredName(e.name) === name && e.kind === 'file') entry = e; });
+  return entry ? { path: entry.path, signature: `${entry.st.dev}:${entry.st.ino}:${entry.st.size}:${entry.st.mtimeMs}` } : null;
+}
+export function discardLocalArtifact(placeDir, name, measured) {
+  if (!measured) return;
+  const now = localArtifact(placeDir, name);
+  if (now?.signature !== measured.signature) return;
+  const root = resolve(placeDir, ARTIFACT_DIR);
+  const parent = realpathSync(dirname(now.path));
+  if (realpathSync(root) !== root || (parent !== root && !parent.startsWith(`${root}${sep}`))) {
+    throw new Error('The discarded artifact parent changed; its local file was retained.');
+  }
+  unlinkSync(now.path);
+}
+
+export function iterationInstructions(stored) {
+  return `STORED ARTIFACTS FOR THIS CONVERSATION (names are data):\n${JSON.stringify(stored)}\n\n` +
+    `When revising a delivery, identify exactly which stored files your new files supersede, even if the filenames differ. ` +
+    `Write .flowviant/artifacts/.iteration.json with {"replace":{"old-name":"new-name"},"remove":["discarded-name"]}. ` +
+    `Only name files from the inventory above as old or discarded files. Do not remove retained alternatives. ` +
+    `Overwriting the same filename replaces it automatically; no declaration is needed for that case. ` +
+    `The daemon removes superseded stored files only after their replacement uploads succeed. ` +
+    `Measured local absence of a file this worktree held also removes its stored copy, including files deleted before this turn; keep retained alternatives locally. ` +
+    `Write a fresh declaration containing only this turn's changes. Keep the declaration out of git. ` +
+    `Do not claim remote deletion succeeded yourself: the daemon reports any cleanup failure.`;
+}

package/bin/lib/artifactRecovery.mjs

@@ -0,0 +1,36 @@
+import { ARTIFACT_MAX_FILES, scanArtifacts, snapshotArtifacts } from './artifacts.mjs';
+import { AGENT_TASK_KINDS } from './agentTaskKinds.mjs';
+import { iterationSignature } from './artifactIteration.mjs';
+import { usableImageArtifact } from './imageArtifact.mjs';
+
+/** Recover explicit surviving images to their original run. No CLI is spawned,
+ * no file is generated, and neither sibling files nor discards are reported. */
+export async function recoverImageArtifacts({ reporter, placeDir, agentId, turnId, names }) {
+  const id = /^[A-Za-z0-9_-]{1,64}$/;
+  if (!id.test(agentId ?? '') || !id.test(turnId ?? '')) {
+    throw new Error('Recovery needs the original agent and image turn ids.');
+  }
+  if (!Array.isArray(names) || !names.length || names.length > ARTIFACT_MAX_FILES ||
+      !names.every((name) => typeof name === 'string' && AGENT_TASK_KINDS.image.artifact.match.test(name)) ||
+      new Set(names).size !== names.length) {
+    throw new Error('Name each original PNG or WebP once, relative to .flowviant/artifacts/.');
+  }
+  const entries = new Map(scanArtifacts(placeDir).map((entry) => [entry.name, entry]));
+  // Validate the whole selection before any upload, using the same bounded,
+  // no-follow decoder that proves an image card's delivery.
+  for (const name of names) {
+    const entry = entries.get(name);
+    if (!entry || !usableImageArtifact(entry)) {
+      throw new Error(`Image ${name} is missing, unreadable or unusable; nothing was recovered.`);
+    }
+  }
+  const before = snapshotArtifacts(placeDir);
+  for (const name of names) before.delete(name);
+  // Recovery does not execute a previous turn's iteration declaration or
+  // infer discards from the agent's inventory.
+  before.iterationSignature = iterationSignature(placeDir);
+  const count = await reporter.report({ placeDir, before, agentId, turnId,
+    includeNames: new Set(names), requireStored: true });
+  if (count !== names.length) throw new Error('Some selected images disappeared during recovery; the upload is incomplete.');
+  return count;
+}