flowviant 0.114.0 → 0.114.2

package/README.md

@@ -147,6 +147,15 @@ Two knobs bound the blast radius, and both are worth setting on a shared box:
   its permission engine is machine-wide — which is surfaced in the app rather
   than papered over.
 
+Fenced turns — design, 3D-model, deck and research cards, the pre-review,
+the planner, intake, the wiki and the New task chat — read none of your Claude
+Code settings files: their permissions and hooks are Flowviant's posture
+alone, and of `~/.claude/settings.json` they keep only how Claude signs in
+(`apiKeyHelper`, `env` and the like) and your model defaults. Code agents and
+Terminal tabs still read yours, so your own allow rules and `defaultMode` add
+to `FLOWVIANT_SAFE=1`'s allowlist there. Codex's fenced turns run with
+`--ignore-user-config` the same way.
+
 The posture is reported on every poll and shown in the project's
 Settings → Machine section, so the team can see whether the box runs the
 guarded toolset or full permissions.

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/artifactContracts.mjs

@@ -59,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
@@ -133,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
@@ -171,6 +192,8 @@ 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
@@ -234,6 +257,9 @@ WHAT TO DO:
    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

package/bin/lib/claudePersonal.mjs

@@ -0,0 +1,145 @@
+/**
+ * A FENCED CLAUDE TURN TAKES ITS PERMISSIONS AND HOOKS FROM FLOWVIANT ALONE
+ * (2026-09-29, the owner, asked whether an agent's fence should ignore the
+ * person's own permission settings: "yes, the agent's fence can ignore").
+ *
+ * A 3D-model agent under the design posture, whose whole shell is
+ * `Bash(ls:*)`, ran `google-chrome` and Playwright scripts. Every fenced lane
+ * read the person's `~/.claude/settings.json` — an agent turn through
+ * `--setting-sources user`, the pre-review, planner, intake, wiki and capture
+ * chat by naming no source at all, which ALSO reads the cwd's
+ * `.claude/settings*.json`, and the pre-review's cwd is the agent's own
+ * worktree. A settings file is a second author of the posture. MEASURED on
+ * Claude Code 2.1.284 — see claudePersonal.test.mjs for the probes and the
+ * offline check that pins them on the real CLI. In short: a personal
+ * `permissions.allow` rule admitted a command the list refused, a personal
+ * `defaultMode: "bypassPermissions"` turned the fenced turn into a bypass, and
+ * personal and worktree hooks fired; under `--setting-sources ''` none of them
+ * loaded, and the turn ran on the same login.
+ *
+ * AN EMPTY SOURCE LIST DROPS THE WHOLE USER SOURCE, not only its permissions:
+ * `~/.claude/CLAUDE.md`, personal skills and subagents went too (measured),
+ * and with the file go the plugins it enables. No flag keeps half of it — a
+ * flag setting's allow rules only add to the person's. On a fenced lane that
+ * is the right loss: the posture and the contract are Flowviant's, the base
+ * branch's instructions and skills arrive through the prompt and the reviewed
+ * plugin (`--plugin-dir` still loads, measured), and a personal plugin brings
+ * hooks of its own. Codex's fenced postures are hermetic the same way
+ * (`--ignore-user-config`, runtimeCodex.mjs).
+ *
+ * WHAT IS KEPT is what makes the CLI the person's CLI, never what it may do:
+ * how it signs in and reaches its provider, how a model the turn does not pin
+ * runs, and how long the person's own store is kept. An ALLOWLIST, so a key a
+ * later CLI adds — a sandbox auto-allow, a permission mode — never rides by
+ * default. It rides INSIDE the posture's own `--settings`, because the CLI
+ * reads one: given two, only the last one's hook fired (measured).
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { MACHINE_CREDENTIAL_ENV } from './machineEnv.mjs';
+import { WINDOW_ENV_REMOVED, withoutWindows } from './noWindowEnv.mjs';
+
+/** The flag pair that loads no settings file — user, project or local.
+ *  Managed (policy) settings and `--settings` still apply. */
+export const NO_SETTING_SOURCES = Object.freeze(['--setting-sources', '']);
+
+/**
+ * The personal settings a fenced turn keeps, by key.
+ *
+ *  · THE LOGIN — the helpers the CLI runs to authenticate and where it signs
+ *    in, and `env`, where a login routes (ANTHROPIC_BASE_URL,
+ *    CLAUDE_CODE_USE_BEDROCK, AWS_PROFILE). `env` gives the person's file no
+ *    more reach than the operator's shell, which every turn inherits already;
+ *    what a turn's environment promises is still removed from it
+ *    (`keptEnv`).
+ *  · HOW AN UNPINNED MODEL RUNS ("Machine default uses the CLI's own
+ *    setting"): per-model effort, thinking, the model map a provider needs.
+ *    `model` itself is not here: every Claude turn names `--model`, the
+ *    daemon's pin when the card has none (config.mjs), so the person's
+ *    default model never reached a daemon turn before either.
+ *  · THE PERSON'S OWN STORE: how long transcripts live and whether memory is
+ *    kept, so a fenced turn's start never prunes or writes on a default the
+ *    person turned off.
+ */
+export const PERSONAL_KEPT = Object.freeze([
+  'apiKeyHelper',
+  'proxyAuthHelper',
+  'awsAuthRefresh',
+  'awsCredentialExport',
+  'gcpAuthRefresh',
+  'forceLoginMethod',
+  'forceLoginOrgUUID',
+  'forceLoginGatewayUrl',
+  'env',
+  'modelOverrides',
+  'modelSettings',
+  'effortLevel',
+  'maxEffortLevel',
+  'alwaysThinkingEnabled',
+  'fallbackModel',
+  'cleanupPeriodDays',
+  'autoMemoryEnabled',
+]);
+
+/** What a turn nobody is sitting at has set or removed (noWindowEnv.mjs) and
+ *  the machine credential (machineEnv.mjs): never put back by a settings file. */
+const TURN_OWNED_ENV = new Set([
+  ...MACHINE_CREDENTIAL_ENV,
+  ...WINDOW_ENV_REMOVED,
+  ...Object.keys(withoutWindows({}, '/')),
+]);
+function keptEnv(env) {
+  if (!env || typeof env !== 'object' || Array.isArray(env)) return null;
+  const out = {};
+  for (const [k, v] of Object.entries(env)) if (typeof v === 'string' && !TURN_OWNED_ENV.has(k)) out[k] = v;
+  return Object.keys(out).length ? out : null;
+}
+
+/** Far past any real settings file; a bigger one is not read. */
+const SETTINGS_MAX_BYTES = 1024 * 1024;
+
+/**
+ * The person's user settings file — `$CLAUDE_CONFIG_DIR/settings.json`, else
+ * `~/.claude/settings.json`, where the CLI itself looks — reduced to
+ * PERSONAL_KEPT. `{}` when it is absent, unreadable or not a JSON object: the
+ * turn then runs on the CLI's stored login and defaults, and the fence is the
+ * same either way.
+ */
+export function personalClaudeSettings(env = process.env) {
+  const dir = env.CLAUDE_CONFIG_DIR || join(env.HOME || homedir(), '.claude');
+  const path = join(dir, 'settings.json');
+  let raw;
+  try {
+    if (statSync(path).size > SETTINGS_MAX_BYTES) return {};
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  const out = {};
+  for (const key of PERSONAL_KEPT) {
+    if (!Object.hasOwn(raw, key) || raw[key] == null) continue;
+    if (key !== 'env') out[key] = raw[key];
+    else {
+      const kept = keptEnv(raw.env);
+      if (kept) out.env = kept;
+    }
+  }
+  return out;
+}
+
+/**
+ * `perm` with `kept` folded into its `--settings` — the posture's keys win, so
+ * a kept key a posture ever names is the fence's word. A posture with no
+ * `--settings` gets one before its lists (`--allowedTools` is variadic). With
+ * nothing kept, `perm` is returned as it was.
+ */
+export function withPersonalSettings(perm, kept) {
+  const personal = kept && typeof kept === 'object' && !Array.isArray(kept) ? kept : {};
+  if (!Object.keys(personal).length) return [...perm];
+  const at = perm.indexOf('--settings');
+  if (at < 0) return ['--settings', JSON.stringify(personal), ...perm];
+  const posture = JSON.parse(perm[at + 1]);
+  return [...perm.slice(0, at), '--settings', JSON.stringify({ ...personal, ...posture }), ...perm.slice(at + 2)];
+}

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/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: () => {} };
+  }
+}

package/bin/lib/projectToolRuntimes.mjs

@@ -15,24 +15,51 @@
  * projectTools.mjs. projectTools.test.mjs pins every transport word to here.
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 
 export const toml = (value) => JSON.stringify(String(value));
 
-/** Keep personal Codex files, but do not copy its project trust grants. An
- * untrusted worktree's .codex/config.toml is ignored by Codex 0.156.1. */
-function isolatedCodexHome(dir, env, worktree) {
-  const source = resolve(env.CODEX_HOME || join(homedir(), '.codex'));
-  const dest = join(dir, 'codex-home');
-  mkdirSync(dest, { mode: 0o700 });
-  if (existsSync(source)) {
-    for (const name of readdirSync(source)) {
-      if (name === 'config.toml') continue;
-      symlinkSync(join(source, name), join(dest, name));
-    }
+/**
+ * ONE LINK PER PERSONAL ENTRY, MADE OR MENDED IN PLACE (2026-09-29). A home
+ * that outlives its turn is refreshed rather than rebuilt, so it must end up
+ * exactly what a fresh build would link: a link already right stays, a link
+ * pointing anywhere else is re-pointed, and a real file or directory standing
+ * where a personal entry belongs — Codex rewrote a link by rename, or made its
+ * own before the person's existed — gives way to the link, because the
+ * personal copy is the one login and the one store (one login per CLI). A
+ * racing refresh that made the same link first is not an error.
+ */
+function linkPersonalEntry(target, link) {
+  let st = null;
+  try { st = lstatSync(link); } catch { /* absent: link it */ }
+  if (st?.isSymbolicLink() && readlinkSync(link) === target) return;
+  if (st) rmSync(link, { recursive: true, force: true }); // never follows a link
+  try {
+    symlinkSync(target, link);
+  } catch (error) {
+    if (error?.code !== 'EEXIST' || readlinkSync(link) !== target) throw error;
   }
+}
+
+/**
+ * Keep personal Codex files, but do not copy its project trust grants. An
+ * untrusted worktree's .codex/config.toml is ignored by Codex 0.156.1.
+ *
+ * `dest` IS REFRESHED IN PLACE, NEVER ASSUMED EMPTY (2026-09-29). An agent's
+ * home is kept between its turns (prepareAgentTools' `codexHome`), because
+ * Codex's shared thread index (`state_5.sqlite`, reached through the link)
+ * records each rollout under the CODEX_HOME in force, unresolved: a home that
+ * died with its turn left the agent's pinned thread pointing into a deleted
+ * directory, and the next card's `resume <id>` failed "no rollout found".
+ * So every personal entry is (re)linked, every link whose entry left the
+ * personal home is dropped, config.toml is rewritten whole each turn (the
+ * worktree's skills can change between turns), and what Codex made here
+ * itself under a name the person has not got is kept.
+ */
+function isolatedCodexHome(dest, env, worktree) {
+  const source = resolve(env.CODEX_HOME || join(homedir(), '.codex'));
   const configPath = join(source, 'config.toml');
   const sourceConfig = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
   const topLevel = sourceConfig.split(/^\s*\[/m, 1)[0];
@@ -65,7 +92,33 @@ function isolatedCodexHome(dir, env, worktree) {
       throw new Error('Cannot isolate Codex project skills with inline skills.config');
     for (const skill of worktreeSkills) config += `\n[[skills.config]]\npath = ${toml(skill)}\nenabled = false\n`;
   }
-  writeFileSync(join(dest, 'config.toml'), config, { mode: 0o600 });
+
+  // The home itself, only once the config is decided: a refused turn touches
+  // nothing here. A home that is not a real directory is not ours to write
+  // through — a link standing here would carry what follows somewhere else.
+  try { if (!lstatSync(dest).isDirectory()) rmSync(dest, { force: true }); } catch { /* absent */ }
+  mkdirSync(dest, { recursive: true, mode: 0o700 });
+  chmodSync(dest, 0o700);
+  const personal = existsSync(source) ? readdirSync(source).filter((name) => name !== 'config.toml') : [];
+  for (const name of personal) linkPersonalEntry(join(source, name), join(dest, name));
+  const linked = new Set(personal);
+  for (const name of readdirSync(dest)) {
+    if (linked.has(name) || name === 'config.toml') continue;
+    // Only a LINK is ours to drop: a real entry under a name the person has
+    // not got is Codex's own (its sessions, on a box whose personal home had
+    // none yet), and this agent's threads live in it.
+    try { if (lstatSync(join(dest, name)).isSymbolicLink()) rmSync(join(dest, name), { force: true }); } catch { /* gone */ }
+  }
+  // Written beside and RENAMED over, so a config.toml that is somehow a link
+  // is replaced as an entry and never written through: the personal
+  // config.toml is the one file this home must never reach.
+  const staged = join(dest, `.config.toml.${process.pid}.${Date.now()}`);
+  try {
+    writeFileSync(staged, config, { mode: 0o600, flag: 'wx' });
+    renameSync(staged, join(dest, 'config.toml'));
+  } finally {
+    rmSync(staged, { force: true });
+  }
   return { path: dest, personalDeveloperInstructions };
 }
 
@@ -85,8 +138,9 @@ function reviewedClaudePlugin(dir, snapshot) {
 
 /**
  * The table. `refuseMcp(config)` names why this runtime cannot take one MCP
- * configuration it otherwise could; `prepare(dir, snapshot, env, worktree)`
- * returns the runner-specific part of prepareAgentTools' result.
+ * configuration it otherwise could; `prepare(dir, snapshot, env, worktree,
+ * kept)` returns the runner-specific part of prepareAgentTools' result — under
+ * `dir`, which dies with the turn, except what `kept` names a lasting place for.
  */
 const TOOL_RUNTIMES = {
   claude: {
@@ -99,8 +153,11 @@ const TOOL_RUNTIMES = {
     mcp: true,
     skills: true,
     refuseMcp: (config) => (config.type === 'sse' ? 'Codex cannot take SSE MCP' : null),
-    prepare: (dir, _snapshot, env, worktree) => {
-      const isolated = isolatedCodexHome(dir, env, worktree);
+    // The agent's own lasting home when the caller has one (2026-09-29: its
+    // threads are indexed under it — see isolatedCodexHome), else one that
+    // dies with the turn, as every home did before.
+    prepare: (dir, _snapshot, env, worktree, kept) => {
+      const isolated = isolatedCodexHome(kept?.codexHome ?? join(dir, 'codex-home'), env, worktree);
       return { codexHome: isolated.path, personalDeveloperInstructions: isolated.personalDeveloperInstructions };
     },
   },
@@ -132,7 +189,8 @@ export function skillsRefusal(runner) {
   return runner === 'none' ? 'no installed CLI can take instructions' : `${runner} cannot take instructions`;
 }
 
-/** The runner-specific files a turn needs, written under `dir`. */
-export function prepareForRunner(runner, dir, snapshot, env, worktree) {
-  return { pluginDir: null, codexHome: null, personalDeveloperInstructions: false, ...(rowFor(runner).prepare?.(dir, snapshot, env, worktree) ?? {}) };
+/** The runner-specific files a turn needs, written under `dir` — or, for what
+ *  `kept` names, where the caller keeps it between turns. */
+export function prepareForRunner(runner, dir, snapshot, env, worktree, kept = {}) {
+  return { pluginDir: null, codexHome: null, personalDeveloperInstructions: false, ...(rowFor(runner).prepare?.(dir, snapshot, env, worktree, kept) ?? {}) };
 }

package/bin/lib/projectTools.mjs

@@ -99,8 +99,16 @@ export function readBaseTools(root, ref, env = process.env) {
 
 const expand = (value, env) => String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => env[key] ?? '');
 
-/** Temporary per-turn files are removed after the last retry. No personal CLI config is written. */
-export function prepareAgentTools(snapshot, runner, env = process.env, worktree = null) {
+/**
+ * Temporary per-turn files are removed after the last retry. No personal CLI config is written.
+ *
+ * `codexHome` is the AGENT'S OWN CODEX_HOME, kept between its turns
+ * (2026-09-29): a place the caller owns, refreshed here each turn and never
+ * removed by `cleanup`, because Codex indexes a thread under the home it ran
+ * in and the next card resumes that thread. Absent, a Codex turn gets a home
+ * that dies with it.
+ */
+export function prepareAgentTools(snapshot, runner, env = process.env, worktree = null, { codexHome: keptCodexHome = null } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'flowviant-agent-tools-'));
   const usable = snapshot.tools.filter((t) => t.state === 'ready' && mcpRefusal(runner, t.config) == null);
   const mcpServers = {};
@@ -142,7 +150,7 @@ export function prepareAgentTools(snapshot, runner, env = process.env, worktree
   ].filter(Boolean).join('\n\n');
   let prepared;
   try {
-    prepared = prepareForRunner(runner, dir, snapshot, env, worktree);
+    prepared = prepareForRunner(runner, dir, snapshot, env, worktree, { codexHome: keptCodexHome });
   } catch (error) {
     rmSync(dir, { recursive: true, force: true });
     throw error;