flowviant 0.113.0 → 0.114.1

package/bin/cli.mjs

@@ -325,7 +325,7 @@ async function uninstallCommand() {
 // repo each is bound to, and which the legacy mirror points at. Needs no
 // network: it reads the store, which is the exact thing a confused person is
 // trying to see. The remedies are named because this listing IS the moment of
-// confusion ("why did it say skadooble?"), not documentation.
+// confusion ("why did it say contoso?"), not documentation.
 async function projectsCommand() {
   const { listStoredProjects, projectLabel } = await import('./lib/credentials.mjs');
   const { connectedOn } = await import('./lib/credentialDate.mjs');
@@ -336,7 +336,7 @@ async function projectsCommand() {
   }
   for (const e of entries) {
     // THE DATE RIDES THE ID, always — this listing exists for the moment
-    // somebody is asking "why did it say skadooble?", and "which of these two
+    // somebody is asking "why did it say contoso?", and "which of these two
     // did I set up last month" is the same question one step on. Absent when
     // nothing recorded one (a credential stored before the field existed);
     // nothing is invented.

package/bin/lib/agentTaskKinds.mjs

@@ -2,7 +2,9 @@
  * A CARD'S KIND — the daemon's one table of what each kind IS (0.97.0):
  * `code` (the default), `design` and `research`; since 0.105.0 also `model`
  * (the 3D-model kind — not an AI-model pin, which is `job.model`) and `deck`
- * (the presentation kind — not the review deck). Every reader of a kind goes
+ * (the presentation kind — not the review deck); since 0.114.0 `image` (one or
+ * more generated PNG/WebP pictures — the first non-code kind that runs on
+ * Codex rather than Claude). Every reader of a kind goes
  * through this module: the prompts that print it and pick a contract
  * (prompts.mjs, which keeps the strings, with the 3D-model and presentation
  * contracts and the shared tail in artifactContracts.mjs), the agent lane
@@ -31,8 +33,12 @@
  *    sentence a turn settles `nothing` with when the proof was not written;
  *  - `offRuntime(rt)`: the sentence when the chosen CLI cannot run the posture.
  */
-/** Every non-code kind runs on Claude: the one CLI that declares their postures. */
+/** The mockup, 3D-model, presentation and write-up kinds run on Claude: the one
+ *  CLI that declares their postures (`design`, `research`). */
 const CLAUDE_ONLY = 'mockup, 3D model, presentation and write-up cards run on Claude 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';
 
 export const AGENT_TASK_KINDS = Object.freeze({
   code: Object.freeze({
@@ -65,6 +71,25 @@ export const AGENT_TASK_KINDS = Object.freeze({
     }),
     offRuntime: () => CLAUDE_ONLY,
   }),
+  /**
+   * THE IMAGE KIND (0.114.0): one or more raster pictures, generated by
+   * Codex's own image tool (`image_generation`, the machine's Codex login —
+   * no API key) and copied under `.flowviant/artifacts/`. Its own posture,
+   * `image`, which ONLY Codex declares (runtimeCodex.mjs): read the repo,
+   * write only the artifacts directory, image generation on, no web. Claude
+   * Code draws no raster image, so a Claude container is refused before spawn
+   * in these words. Proven by one PNG or WebP — the formats the card is told
+   * to hand back; a picture drawn some other way (SVG, an HTML page) is not
+   * the delivery.
+   */
+  image: 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/',
+    }),
+    offRuntime: () => CODEX_ONLY,
+  }),
   /** THE PRESENTATION KIND (0.105.0): one HTML slide deck, under the design fence. */
   deck: Object.freeze({
     posture: 'design',
@@ -119,7 +144,8 @@ export const unknownAgentTaskKind = (v) =>
 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. */
+ *  once: the 3D-model and presentation kinds reuse the design posture; the
+ *  image kind has its own. */
 export const KIND_POSTURES = Object.freeze([
   ...new Set(
     Object.values(AGENT_TASK_KINDS)

package/bin/lib/agentTaskTypes.mjs

@@ -16,7 +16,9 @@
  * the kind line (`AGENT_TASK_SPEC`), so the spec stashed for the pre-review
  * carries it too. Each sentence is true to what its kind's posture can do: a
  * code type may build and test; a write-up type reads and writes one Markdown
- * file; a mockup type writes under .flowviant/artifacts/ and nothing else.
+ * file; a mockup type writes under .flowviant/artifacts/ and nothing else; the
+ * Image type (0.114.0) generates pictures with Codex's own tool and copies
+ * them there.
  *
  * `label` is the app's `TASK_TYPE_LABEL`, the word a person picked. The ids
  * (in the app's picker order), their kinds and their labels are held to the
@@ -101,6 +103,13 @@ export const AGENT_TASK_TYPES = Object.freeze({
       'write each icon as its own .svg file directly in .flowviant/artifacts/, and make the mockup page ' +
       'the sheet that shows them all, inline, at the sizes they are used.',
   }),
+  image: Object.freeze({
+    label: 'Image',
+    kind: 'image',
+    contract:
+      'generate the picture the card describes with your image tool, at the size and in the style it ' +
+      'names, and hand back each image it asks for as its own PNG or WebP file.',
+  }),
   research: Object.freeze({
     label: 'Research',
     kind: 'research',

package/bin/lib/artifactContracts.mjs

@@ -1,5 +1,6 @@
 /**
- * THE 3D-MODEL AND PRESENTATION CARDS' CONTRACTS (2026-09-27, 0.105.0).
+ * THE 3D-MODEL, PRESENTATION AND IMAGE CARDS' CONTRACTS (2026-09-27, 0.105.0;
+ * the image card 2026-09-29, 0.114.0).
  *
  * Two more kinds that hand back a file rather than a change, beside the design
  * and research contracts in prompts.mjs (which is past its size and keeps
@@ -19,8 +20,11 @@
  * "model" here is the 3D-model KIND (not an AI-model pin, `job.model`), and
  * "deck" the presentation kind (not the review deck).
  *
- * Pure strings: no imports, no environment, no I/O.
+ * Pure strings: no environment, no I/O. The one import is the generated
+ * artifact policy's caps (pure data), so the image contract's size limit is
+ * the one the uploader enforces, never a second spelling of it.
  */
+import { ARTIFACT_BINARY_MODEL_EXTS, ARTIFACT_BINARY_MODEL_MAX_BYTES, ARTIFACT_MAX_BYTES } from './artifactPolicy.mjs';
 
 /**
  * Rule 3, rule 4 and the final JSON a file-handing contract ends with.
@@ -55,6 +59,25 @@ or, if you are stopping to ask:
 "progress" is REQUIRED on both shapes and REPLACES the previous one whole —
 past tense, plain sentences, no card ids.`;
 
+/**
+ * NOBODY IS AT THIS SCREEN (2026-09-29, the owner: Chrome "kept opening on my
+ * desktop … but me as the user didnt click anything"). A board agent looking
+ * at the page it made started Chrome itself, and a Chrome started on the
+ * default profile hands its window to the person's own running Chrome. The
+ * turn's environment now closes those roads (noWindowEnv.mjs); these words
+ * are for what an environment cannot close — an agent reaching for a window
+ * on purpose — and say how to look without one: headless, a profile of its
+ * own, a screenshot it reads back. `flowviant shot` is not named because
+ * nothing puts `flowviant` on a turn's PATH (an npx or tray-bundled daemon
+ * has none there). Every file-handing kind that draws a page renders
+ * `LOOK_HEADLESS` in its rule 2; the image card renders `NO_WINDOW`.
+ */
+export const NO_WINDOW = `Never open a browser window or any desktop application: this is somebody's
+   own screen, and nobody is at it.`;
+export const LOOK_HEADLESS = `${NO_WINDOW} To look at your page, screenshot it
+   headless with a profile of its own and read the PNG:
+     google-chrome --headless=new --user-data-dir="$(mktemp -d)" --virtual-time-budget=5000 --screenshot=/tmp/<name>.png file://<the page's absolute path>`;
+
 /**
  * THE 3D-MODEL CARD (rewritten 0.107.0, the owner, 2026-09-27: "yeah just
  * glb"). The product is ONE .glb a person downloads and imports; the card
@@ -129,6 +152,8 @@ WHAT TO DO:
 
    Keep the page under 2 MB.
 
+   ${LOOK_HEADLESS}
+
 ${ARTIFACT_CONTRACT_TAIL({
   ask: `If you cannot model it without a DECISION only a person can make — which of
    two directions, what size or style, which asset it stands beside — STOP AND
@@ -167,9 +192,79 @@ WHAT TO DO:
    one slide on each page (break-after: page), so the browser prints it to a
    PDF. Keep it under 2 MB.
 
+   ${LOOK_HEADLESS}
+
 ${ARTIFACT_CONTRACT_TAIL({
   ask: `If you cannot write it without a DECISION only a person can make — who the
    audience is, how long it runs, what it must argue — STOP AND ASK. Do not
    guess. A question costs one reply; a guessed deck costs a review.`,
   summary: 'one or two sentences on what the deck covers, and the file it is in',
 })}`;
+
+/** The upload cap a PNG or WebP artifact meets (the generated policy's), as
+ *  the contract says it: "20 MB" since the app gave generated pictures the
+ *  binary ceiling (2026-09-29). The larger of the two, should they differ. */
+const imageCapBytes = Math.max(
+  ...['png', 'webp'].map((ext) =>
+    ARTIFACT_BINARY_MODEL_EXTS.includes(ext) ? ARTIFACT_BINARY_MODEL_MAX_BYTES : ARTIFACT_MAX_BYTES
+  )
+);
+export const IMAGE_CAP_WORDS = `${Math.floor(imageCapBytes / (1024 * 1024))} MB`;
+
+/**
+ * THE IMAGE CARD (0.114.0, the owner 2026-09-29). The product is one or more
+ * RASTER pictures, and the one CLI on the machine that makes them is Codex,
+ * through its own image tool on its own login (`image_generation` — no API
+ * key; Flowviant generates nothing). So this is the first contract spoken to
+ * Codex rather than Claude, and it runs under Codex's `image` fence (read the
+ * repo, write only `.flowviant/artifacts/**`, no web — runtimeCodex.mjs).
+ *
+ * WHERE THE BYTES ARE. Codex's tool saves each image under
+ * `$CODEX_HOME/generated_images/…` and names the path (its own instructions:
+ * "copy it and leave the original in place"); the fence reads everywhere and
+ * writes only the artifacts directory, so the contract's one mechanical step
+ * is the COPY. The artifact scan finds what was copied; the delivery is proven
+ * by one .png or .webp there (agentTaskKinds.mjs).
+ *
+ * NEVER DRAWN IN CODE: an agent without the tool could paint an SVG or a
+ * canvas and call it the picture — a stand-in that reports success. The card
+ * asked for a generated picture, so a missing or refusing tool is a question
+ * 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.
+
+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
+decides.
+
+WHAT TO DO:
+
+1. Read the card and the repository first — the brand, its colours and type,
+   and where the picture will be used: its size and shape (a hero banner, an
+   app icon, a social card) and what stands beside it. The picture must belong
+   to THIS product. A size, aspect ratio or style the card names wins;
+   otherwise say in your summary what you assumed.
+
+2. Make each picture the card asks for WITH YOUR IMAGE GENERATION TOOL. Never
+   draw one in code — no SVG, no canvas, no HTML page, no script that paints
+   pixels: the card asks for a generated picture. The tool saves each image
+   under $CODEX_HOME/generated_images/ and tells you where. COPY each image you
+   hand back into .flowviant/artifacts/ under a short kebab-case name for what
+   it shows (for example .flowviant/artifacts/hero-banner.png), as a PNG or a
+   WebP file — one file per image, and nothing else in that directory: no page,
+   no notes, no scripts, no discarded variants. Keep each file under
+   ${IMAGE_CAP_WORDS}; if one is larger, save it as WebP or at a smaller size.
+
+   ${NO_WINDOW} Look at a picture through your own tools,
+   never an image viewer.
+
+${ARTIFACT_CONTRACT_TAIL({
+  ask: `If you cannot make it without a DECISION only a person can make — what it
+   shows, its style, its size, where it goes — STOP AND ASK. Do not guess. And
+   if your image tool is not available here, or refuses or fails, STOP and say
+   so in your question, quoting its words — never draw a stand-in some other
+   way. A question costs one reply; a guessed picture costs a review.`,
+  summary: 'one or two sentences on what the images show, the files they are in, and the size and style you assumed',
+})}`;

package/bin/lib/artifactPolicy.mjs

@@ -15,7 +15,7 @@ export const ARTIFACT_POLICY_SOURCE = 'packages/shared/src/schemas/artifact.sche
 export const ARTIFACT_MAX_BYTES = 2097152;
 /** Binary model buffers (the extensions below). */
 export const ARTIFACT_BINARY_MODEL_MAX_BYTES = 20971520;
-export const ARTIFACT_BINARY_MODEL_EXTS = ['glb', 'bin'];
+export const ARTIFACT_BINARY_MODEL_EXTS = ['glb', 'bin', 'png', 'webp'];
 /** Per session and per agent — the server keeps as many per owner. */
 export const ARTIFACT_MAX_PER_OWNER = 40;
 

package/bin/lib/artifacts.mjs

@@ -74,7 +74,7 @@
  * that cannot show an artifact must not have the CLI told it will.
  */
 
-import { constants, closeSync, fstatSync, lstatSync, openSync, readdirSync, readSync } from 'node:fs';
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { cutKeepingExtension } from './safeFileName.mjs';
@@ -105,6 +105,39 @@ export const artifactMaxBytesFor = (name) => {
 /** Listed per scan, newest first — the server keeps as many per owner. */
 export const ARTIFACT_MAX_FILES = ARTIFACT_MAX_PER_OWNER;
 
+/**
+ * THE ARTIFACTS DIRECTORY, STANDING BEFORE A FENCED KIND TURN SPAWNS (0.114.0).
+ *
+ * Codex's image profile makes `<place>/.flowviant/artifacts` its ONE writable
+ * root, and a root that does not exist cannot be made from inside the fence
+ * (measured on 0.156.1: `mkdir` under it failed "Read-only file system"). So
+ * the lane makes it first — and only as a REAL directory under a REAL
+ * `.flowviant`, the scan's own rule (`scanArtifacts`) on the write side: a
+ * repository can commit `.flowviant -> ~/.ssh`, and a fence granted on a path
+ * through that link is a write grant on its target. Either component being a
+ * symlink or a non-directory answers false and creates nothing; the caller
+ * refuses the turn in words.
+ */
+export function ensureArtifactDir(placeDir) {
+  const parent = join(placeDir, '.flowviant');
+  const dir = join(placeDir, ARTIFACT_DIR);
+  const real = (p) => {
+    try {
+      const st = lstatSync(p);
+      return st.isDirectory() && !st.isSymbolicLink() ? true : false;
+    } catch (e) {
+      return e?.code === 'ENOENT' ? null : false;
+    }
+  };
+  if (real(parent) === false || real(dir) === false) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return false;
+  }
+  return real(parent) === true && real(dir) === true;
+}
+
 export function artifactTypeFor(name) {
   const dot = String(name).lastIndexOf('.');
   if (dot <= 0) return null;

package/bin/lib/claudePosture.mjs

@@ -361,6 +361,13 @@ const CLAUDE_PERM = {
   'plan-mode': () => PLAN_MODE_PERM,
   design: (kd) => designPermFor(kd),
   research: (kd) => researchPerm(kd),
+  // THE IMAGE POSTURE IS CODEX'S (0.114.0) and Claude does not declare it
+  // (runtimeClaude.mjs `profiles`), so turnProfile.mjs refuses a Claude turn
+  // under it before argv is built. The entry exists because `runTurn` looks
+  // Claude's list up BY NAME for every runtime (the adapter that is not Claude
+  // ignores it), and a missing name throws. Were it ever reached on Claude it
+  // is the consult list: read-only, no write at all — failing closed.
+  image: (kd) => consultPermFor(kd),
 };
 export const CLAUDE_PERM_PROFILES = Object.freeze(Object.keys(CLAUDE_PERM));
 export function claudePermFor(profileName, knowledgeDir) {

package/bin/lib/claudeStream.mjs

@@ -10,6 +10,7 @@
  */
 
 import { humanizeClaudeTool, THINK_MARKER } from './runtimeEvents.mjs';
+import { turnModelOf } from './turnModel.mjs';
 
 // Turn one Claude tool_use into a compact activity {kind, label}, or null for
 // tools not worth surfacing. `kind:'read'` is what the file counter counts; a
@@ -82,7 +83,7 @@ export function usageFromResult(ev) {
 // container that reports no spend, which is indistinguishable from an older
 // daemon by design. A callback that is silent when it breaks has to be called
 // directly by something.
-export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage, onRateLimit }) {
+export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage, onRateLimit, onModel }) {
   let ev;
   try {
     ev = JSON.parse(line);
@@ -97,6 +98,13 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
     onActivity?.(a);
   };
   if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
+    // THE MODEL THAT ANSWERED (2026-09-29, turnModel.mjs) — the fallback for an
+    // init that named none. The turn's own messages only: a subagent's carry
+    // `parent_tool_use_id`, and its model is not the turn's.
+    if (ev.parent_tool_use_id == null) {
+      const answered = turnModelOf(ev.message.model);
+      if (answered) onModel?.(answered);
+    }
     for (const b of ev.message.content) {
       if (b.type === 'thinking' || b.type === 'redacted_thinking') {
         /**
@@ -163,6 +171,11 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
     // status (`needs-auth` above all — a sign-in that has to happen at this
     // box). Relayed raw; `recordMcpServers` (runtimeCapabilities.mjs) normalises it and
     // drops this daemon's own `flowviant` server.
+    //
+    // `model` (2026-09-29) is the model this turn RESOLVED — `opus` is an
+    // alias, and this is the CLI naming what it chose. See turnModel.mjs.
+    const resolved = turnModelOf(ev.model);
+    if (resolved) onModel?.(resolved);
     if (Array.isArray(ev.skills) || typeof ev.session_id === 'string' || Array.isArray(ev.mcp_servers)) {
       onInit?.({
         skills: Array.isArray(ev.skills) ? ev.skills.map(String) : undefined,

package/bin/lib/credentials.mjs

@@ -153,7 +153,7 @@ export function safeName(name) {
  * (2026-09-19).
  *
  * Two projects genuinely named the same thing is not a hypothetical: production
- * held two called "BRIF AI", both bound to the same checkout on one box, so
+ * held two projects with one name, both bound to the same checkout on one box, so
  * `npx flowviant` there offered two IDENTICAL picker rows and the only way to
  * choose between them was to guess. A picker whose options cannot be told apart
  * is not a picker.
@@ -185,9 +185,9 @@ export function projectRowLabel(e, entries) {
  * WHICH STORED PROJECTS SHARE ONE REPO — the duplicate the owner met and could
  * not name (2026-09-23).
  *
- * `npx flowviant machines` printed "BRIF AI" twice, and he read it as two
- * daemons or two "machine profiles" on one box for one project: *"when I go to
- * BRIF AI to disconnect the duplicate, I only see one."* It was two PROJECTS
+ * `npx flowviant machines` printed one project name twice, and he read it as
+ * two daemons or two "machine profiles" on one box for one project: *"when I go
+ * to <the project> to disconnect the duplicate, I only see one."* It was two PROJECTS
  * with one name, both bound to one checkout — and the id-on-every-row rule
  * (2026-09-19) had not made that legible, because two hex prefixes say
  * "different" without saying "same repo". A project's Machines page shows its
@@ -256,8 +256,8 @@ export function boundElsewhere(entries, repoRoot, projectId) {
  */
 export function directoryTakenRefusal(bound, repoRoot, { incoming } = {}) {
   // Every project in the sentence is labelled against the WHOLE set, the
-  // incoming one included: a refusal reading "already connected to BRIF AI,
-  // so BRIF AI was not connected" is the puzzle it exists to end.
+  // incoming one included: a refusal reading "already connected to Acme App,
+  // so Acme App was not connected" is the puzzle it exists to end.
   const all = [...bound, ...(incoming ? [incoming] : [])];
   const names = bound.map((e) => projectRowLabel(e, all));
   const list = names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}` : names[0];
@@ -284,7 +284,7 @@ function normalizeName(s) {
  * WHICH stored project most likely goes with this repo — a HINT for the
  * picker's default, and DELIBERATELY not a licence to serve it. `resolveStored
  * Credential` matches by repo PATH and refuses to guess past that, because
- * serving a project the path did not name is the "it said skadooble in my
+ * serving a project the path did not name is the "it said contoso in my
  * calendar repo" surprise this whole file exists to prevent. A name that
  * matches the repo's folder or its github repo-name is softer evidence — good
  * enough to put the cursor on that row so the answer is one keypress, never
@@ -450,7 +450,7 @@ export function matchStoredProject(ref) {
  *
  * Deliberately NO mirror fallback once more than one project is stored: the
  * mirror is whichever login happened last, and serving it because it was
- * recent is exactly the calendar-says-skadooble surprise this file exists to
+ * recent is exactly the calendar-says-contoso surprise this file exists to
  * end. Two projects means the answer is a QUESTION (or --project, or the
  * repo binding), never recency.
  */
@@ -473,7 +473,7 @@ export function resolveStoredCredential(argv = process.argv, cwd = process.cwd()
 
   // ONE stored project with no binding: the pre-0.55.0 world. Serve it — a
   // headless restart must not hang — but flag it, so a TTY start asks ONCE and
-  // binds, which is what turns "it said skadooble in my calendar repo" into a
+  // binds, which is what turns "it said contoso in my calendar repo" into a
   // question instead of a surprise.
   if (entries.length === 1 && !entries[0].repoRoot) {
     return { entry: entries[0], source: 'only', needsConfirm: Boolean(repoRoot), repoRoot };

package/bin/lib/fleetRoster.mjs

@@ -467,7 +467,7 @@ export function announceFirstPoll(roster) {
     );
     note(c.dim('  wiki + agents stream to THIS project — view its Code canvas in Flowviant.'));
     // Remember the NAME beside the stored credential, so the picker and
-    // `flowviant projects` can say "skadooble" instead of an id — a
+    // `flowviant projects` can say "contoso" instead of an id — a
     // credential saved before the server sent names backfills here. No-op
     // for a --fleet/env token (nothing stored to annotate).
     setStoredProjectName(roster.project.id, roster.project.name);

package/bin/lib/git.mjs

@@ -260,11 +260,11 @@ export function detectBaseRef(repoRoot) {
  * A base ref an agent's worktree can actually be cut from.
  *
  * `origin/<branch>` is the right base when the repo HAS an origin. A repo with
- * no remote (a local-only project — the owner's "Death Note - Roblox",
- * 2026-09-25) has no `origin/*` refs at all, and cutting a worktree from one
- * fails; every agent turn then ended "nothing" in a second. So: the ref itself
- * when it resolves to a commit, else the LOCAL branch of the same name, else
- * the ref unchanged (and the worktree step says why in git's words).
+ * no remote (a local-only project, 2026-09-25) has no `origin/*` refs at
+ * all, and cutting a worktree from one fails; every agent turn then ended
+ * "nothing" in a second. So: the ref itself when it resolves to a commit,
+ * else the LOCAL branch of the same name, else the ref unchanged (and the
+ * worktree step says why in git's words).
  */
 export function usableBaseRef(repoRoot, ref) {
   const resolves = (r) => {

package/bin/lib/knowledgeLibrary.mjs

@@ -18,21 +18,24 @@
  * including its original relative sidecar paths and measured preview. At
  * 0.105.0 the end-product kinds add `models/<slug>-v<N>/` (a 3D model, a
  * folder like a design: its viewer, its model files, its textures) and
- * `decks/<slug>-v<N>.html` (a presentation, one file).
+ * `decks/<slug>-v<N>.html` (a presentation, one file). At 0.114.0 the image
+ * kind adds `images/<slug>-v<N>.png` or `.webp` — one BINARY file per kept
+ * picture, fetched and written as bytes like every entry.
  *
- * SUBDIRECTORIES, AND EXACTLY FOUR. The safe-name rule for a knowledge file
+ * SUBDIRECTORIES, AND EXACTLY FIVE. The safe-name rule for a knowledge file
  * forbids every separator; a library item is the one thing allowed ONE (or,
- * for a bundle kind, a versioned folder), and only after one of the four
+ * for a bundle kind, a versioned folder), and only after one of the five
  * literal prefixes, with a stem that is already safe and the extension its
  * kind hands back. `..`, another prefix, a leading dot, a folder for a
  * single-file kind — refused, never rewritten, because a rewritten path could
- * collide with another item's real one. The four directories are OURS the way
+ * collide with another item's real one. The five directories are OURS the way
  * the library directory is: a symlink or a file planted there is removed (the
  * link, never its target) and a real directory made.
  *
  * ABSENT MEANS "LEAVE IT ALONE", the same rule the whole key keeps: a manifest
  * with no `library` key is an older server, and `designs/`, `models/`,
- * `decks/`, `research/` and `LIBRARY.md` are neither synced nor swept.
+ * `images/`, `decks/`, `research/` and `LIBRARY.md` are neither synced nor
+ * swept.
  * `library: { items: [] }` is the emptied catalog, SAID — every directory and
  * the catalog go.
  */
@@ -91,15 +94,18 @@ const DESIGN_EXT = Object.freeze(['.html', '.htm', '.gltf', '.obj', '.glb', '.bi
  * fact below — `LIBRARY_DIRS`, the path rule, the reference rule, the
  * previews, the catalog — reads this, so a kind is one row here. It was five
  * parallel tables keyed by kind, and a kind missed in one of them threw.
- * `model` is the 3D-model kind, `deck` the presentation kind.
+ * `model` is the 3D-model kind, `deck` the presentation kind, `image` the
+ * picture kind (0.114.0: one PNG or WebP, which is its own preview — no page
+ * for the server to measure).
  */
 export const LIBRARY_KINDS = Object.freeze({
   design: Object.freeze({ dir: 'designs', bundle: true, ext: DESIGN_EXT, preview: true, word: 'design' }),
   model: Object.freeze({ dir: 'models', bundle: true, ext: Object.freeze([...DESIGN_EXT, '.mtl']), preview: true, word: '3D model' }),
+  image: Object.freeze({ dir: 'images', bundle: false, ext: Object.freeze(['.png', '.webp']), preview: false, word: 'image' }),
   deck: Object.freeze({ dir: 'decks', bundle: false, ext: Object.freeze(['.html', '.htm']), preview: true, word: 'deck' }),
   research: Object.freeze({ dir: 'research', bundle: false, ext: Object.freeze(['.md']), preview: false, word: 'research' }),
 });
-/** The four subdirectories a kept item may live in, by kind — read off
+/** The five subdirectories a kept item may live in, by kind — read off
  *  `LIBRARY_KINDS`. */
 export const LIBRARY_DIRS = Object.freeze(
   Object.fromEntries(Object.entries(LIBRARY_KINDS).map(([kind, k]) => [kind, k.dir]))
@@ -279,7 +285,7 @@ export function renderLibraryCatalog(items) {
   });
   return (
     '# Library\n\n' +
-    'The mockups, 3D models, decks and research this project kept. Paths are relative to this directory;\n' +
+    'The mockups, 3D models, images, decks and research this project kept. Paths are relative to this directory;\n' +
     'a newer version supersedes an older one of the same name.\n\n' +
     `${lines.join('\n')}\n`
   );

package/bin/lib/machineListing.mjs

@@ -36,14 +36,14 @@
  * the connected flowviants? because im not sure if i have any duplicate or
  * redundant daemons running". Measured the day it was asked: four live daemons
  * across two boxes, two credentials last heard three days ago, and two projects
- * both named "BRIF AI" bound to the same checkout — which is why `npx
+ * with one name bound to the same checkout — which is why `npx
  * flowviant` there offered two identical picker rows. THE PROJECT ID IS
  * THEREFORE ALWAYS PRINTED: it is the only thing that tells those two apart,
  * and the whole listing is worth less without it. **And since 0.95.0 the
  * collision is SAID, not left to be noticed**: the id told him the rows were
  * different projects, and he still read them as one project connected twice
- * ("BRIF AI appears twice meaning I likely have 2 daemon or 'machine
- * profiles' on my machine for the same BRIF AI project"). `renderCollisions`
+ * ("<the project> appears twice meaning I likely have 2 daemon or 'machine
+ * profiles' on my machine for the same <the project> project"). `renderCollisions`
  * prints one line per repo that two projects are bound to, naming both.
  *
  * ── IT IS A RELAY ──
@@ -266,7 +266,7 @@ export function projectPhrase(e) {
 /**
  * TWO PROJECTS ON ONE REPO, SAID OUT LOUD (2026-09-23).
  *
- * The owner ran this command, saw "BRIF AI" twice, and concluded he had two
+ * The owner ran this command, saw one project name twice, and concluded he had two
  * daemons for one project. The id on each row said they were different
  * projects; nothing said they were bound to the SAME checkout, which is the
  * fact that makes it a duplicate rather than two rows. So the listing ends

package/bin/lib/noWindowEnv.mjs

@@ -0,0 +1,104 @@
+/**
+ * A TURN NOBODY IS SITTING AT PUTS NO WINDOW ON ANYBODY'S SCREEN (2026-09-29).
+ *
+ * The owner, on WSL: Chrome "kept opening on my desktop … but me as the user
+ * didnt click anything". Board agents checking their three.js pages started
+ * Chrome themselves, and an inherited environment gives such a process three
+ * roads to the person's screen:
+ *  · a Chrome started without --user-data-dir takes the DEFAULT profile, and
+ *    while the person's own Chrome runs on it the new process hands its
+ *    command line to that one through the profile's SingletonSocket — taken
+ *    before any display is opened (measured) — so the PERSON'S Chrome opens
+ *    the window, and no display variable of ours is involved;
+ *  · a headed browser, Playwright's `headless: false`, any GUI program draws
+ *    wherever DISPLAY / WAYLAND_DISPLAY point, and WSLg points them at the
+ *    Windows desktop;
+ *  · xdg-open, Python's webbrowser, a dev server's --open honour BROWSER, which
+ *    on WSL is usually the Windows browser.
+ *
+ * So every turn but a Terminal tab's — the one lane where a person at the
+ * keyboard may ask for a window — runs with:
+ *  · DISPLAY and WAYLAND_SOCKET removed, and WAYLAND_DISPLAY set EMPTY rather
+ *    than removed: unset, libwayland falls back to `$XDG_RUNTIME_DIR/wayland-0`
+ *    (measured: a client with it unset connected there), and that is exactly
+ *    the socket WSLg keeps; empty names no socket, a Chrome that picks Wayland
+ *    from it fails "Failed to connect to Wayland display" and exits (measured),
+ *    and xdg-open reads empty as no display at all;
+ *  · BROWSER=none, childEnv.mjs's word for the same thing;
+ *  · a browser home of its own: CHROME_CONFIG_HOME, the root Chrome and
+ *    Chromium put their default profile under (chrome_paths_linux.cc), and
+ *    CHROME_USER_DATA_DIR, the profile itself (chrome_main_delegate.cc) — the
+ *    one a fork like Brave still honours where it ignores the first
+ *    (measured) — so a browser the agent starts bare opens a profile nobody
+ *    else is running and can never reach the person's.
+ *
+ * Nothing that runs here needs what is removed: the CLIs' own headless modes
+ * (`claude -p`, `codex exec`) and headless browsers run without a display
+ * (measured). XDG_CONFIG_HOME is deliberately NOT moved: it is where Claude,
+ * Codex and git keep their own configuration.
+ *
+ * What an environment cannot stop is an agent that runs a Windows program on
+ * purpose through WSL interop (`explorer.exe`, `cmd.exe /c start`); the kind
+ * contracts ask it not to (artifactContracts.mjs, `NO_WINDOW`).
+ */
+import { lstatSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Removed outright; WAYLAND_DISPLAY is kept but emptied (see above). */
+export const WINDOW_ENV_REMOVED = Object.freeze(['DISPLAY', 'WAYLAND_SOCKET']);
+
+/** A copy of `env` a turn nobody is sitting at runs with. Never mutates its
+ *  input. `browserHome` is the directory its browsers keep their profile in. */
+export function withoutWindows(env, browserHome = null) {
+  const out = { ...(env ?? {}) };
+  for (const k of WINDOW_ENV_REMOVED) delete out[k];
+  out.WAYLAND_DISPLAY = '';
+  out.BROWSER = 'none';
+  if (browserHome) {
+    out.CHROME_CONFIG_HOME = browserHome;
+    out.CHROME_USER_DATA_DIR = join(browserHome, 'user-data');
+  }
+  return out;
+}
+
+/**
+ * AN AGENT'S BROWSER HOME is kept beside its Codex home, in its worktree's
+ * private git dir: never committed, the same profile turn after turn, and
+ * removed with the worktree when the agent retires. The pre-review and the
+ * project check stand in the same worktree for the same agent, and take it
+ * too. Null when there is no git dir to hold it.
+ */
+export const agentBrowserHome = (sessionMetaPath, wt, agentId) =>
+  sessionMetaPath?.(wt, 'flowviant-agent-browser', agentId) ?? null;
+
+/**
+ * The directory, made: `kept` when a lane has one (0700, never removed here),
+ * else one of this turn's own that `cleanup` removes. A kept path that is not
+ * a real directory is replaced, never followed; one that cannot be made falls
+ * back to a turn's own. Never throws — the turn runs without a browser home
+ * sooner than not at all, and its display variables are gone either way.
+ */
+export function openBrowserHome(kept) {
+  if (kept) {
+    try {
+      try { if (!lstatSync(kept).isDirectory()) rmSync(kept, { force: true }); } catch { /* absent */ }
+      mkdirSync(kept, { recursive: true, mode: 0o700 });
+      return { dir: kept, cleanup: () => {} };
+    } catch { /* fall through to a turn's own */ }
+  }
+  try {
+    const dir = mkdtempSync(join(tmpdir(), 'flowviant-browser-'));
+    let removed = false;
+    return {
+      dir,
+      cleanup: () => {
+        if (removed) return;
+        removed = true;
+        try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
+      },
+    };
+  } catch {
+    return { dir: null, cleanup: () => {} };
+  }
+}