flowviant 0.116.0 → 0.117.0

package/bin/lib/claudePosture.mjs

@@ -91,12 +91,22 @@ function fencedReads(knowledgeDir) {
   ];
 }
 
-/** The shell readers CONSULT and PLAN keep. Each one is PATH-VALIDATED by the
- *  CLI itself — measured on 2.1.281 (2026-09-24): with `Bash(cat:*)`,
- *  `Bash(head:*)` and `Bash(ls:*)` allowed, `cat`/`ls`/`head` on a file outside
- *  the working directories were each refused ("Claude Code may only
- *  concatenate files from the allowed working directories") — so it is the
- *  Read/Grep/Glob TOOLS, not these, that needed the fence above. */
+/** The shell readers CONSULT and PLAN keep. `cat`, `ls` and `head` are
+ *  PATH-VALIDATED by the CLI itself — measured on 2.1.281 (2026-09-24): with
+ *  `Bash(cat:*)`, `Bash(head:*)` and `Bash(ls:*)` allowed, each was refused a
+ *  file outside the working directories ("Claude Code may only concatenate
+ *  files from the allowed working directories") — so it is the Read/Grep/Glob
+ *  TOOLS, not these, that needed the fence above.
+ *
+ *  THE GIT READERS WERE NEVER MEASURED THAT WAY (2026-10-10, the audit), and
+ *  `git diff` reads any file on the box: `--no-index` compares two arbitrary
+ *  paths, and git switches to it on its own when a path lies outside the work
+ *  tree (`git diff ~/.ssh/id_ed25519 /dev/null` prints the key). So the read
+ *  guard is their path fence: it refuses `--no-index`, and a git argument that
+ *  is absolute, `~`-rooted or climbs a `..` segment (revision ranges `a..b`
+ *  still pass). It also refuses every one of these readers the checkout's
+ *  secret files by name — the shell's half of CHECKOUT_SECRETS below, since a
+ *  Read deny says nothing about `cat`. See hooks/readGuard.mjs. */
 const CONSULT_BASH = [
   'Bash(ls:*)',
   'Bash(wc:*)',
@@ -108,6 +118,14 @@ const CONSULT_BASH = [
   'Bash(git rev-parse:*)',
 ];
 
+/** The checkout's own secrets, denied BY NAME on the postures that read the
+ *  repo and hand what they read to someone (2026-10-10, the audit): consult
+ *  (intake's brief lands with no press), plan and the wiki (every page is
+ *  uploaded). Research's measured pair — `Read(./**)` read `.env` without it —
+ *  plus Wrangler's `.dev.vars`, which no root `.env*` scan sees. The read guard
+ *  refuses the same files to the shell readers (hooks/readGuard.mjs). */
+const CHECKOUT_SECRETS = ['Read(./.env*)', 'Read(./**/.env*)', 'Read(./**/.dev.vars)'];
+
 /**
  * PLAN — read the repo, write the plan, never the code.
  *
@@ -120,10 +138,11 @@ const CONSULT_BASH = [
  * hijacked turn's most destructive reachable act is dropping a slice from the
  * plan it is already in, which a human can see and undo in the thread.
  *
- * Note what is absent versus WIKI_PERM: Write, Edit, mkdir and rm. The
- * cartographer needs those because it authors files; a planner authors records
- * through an API, and there is no file on this machine it has any business
- * touching.
+ * Note what is absent versus the wiki's list: Edit, mkdir and rm. The
+ * cartographer needs those because it authors files (in the vault, and only
+ * there); a planner authors records through an API, and there is no file on
+ * this machine it has any business touching. The checkout's secrets are denied
+ * by name (CHECKOUT_SECRETS), as on consult.
  */
 export function planPermFor(knowledgeDir) {
   return [
@@ -132,6 +151,8 @@ export function planPermFor(knowledgeDir) {
     'mcp__flowviant',
     ...fencedReads(knowledgeDir),
     ...CONSULT_BASH,
+    '--disallowedTools',
+    ...CHECKOUT_SECRETS,
   ];
 }
 
@@ -153,24 +174,13 @@ const PERM = SAFE
     ]
   : ['--dangerously-skip-permissions'];
 
-// Wiki turns are read-the-repo + write-the-vault ONLY — always curated, never
-// --dangerously-skip-permissions: no gh, no push-capable git, no package
-// managers, and nothing that can EXECUTE arbitrary commands — no `find`
-// (-exec/-delete) and no `git grep` (-O<pager> runs a shell; the Grep tool
-// covers search). Command execution is the line: it enables network exfil,
-// which plain file writes never do. `rm` IS allowed: pruning a stale vault
-// page requires a real file deletion (that's how the sync protocol learns of
-// it), and the blast radius is bounded — the daemon resets the repo worktree
-// after every wiki turn, and the vault has its own git history.
-// (Write/Edit can't be path-scoped here; the worktree reset is the backstop.)
-const WIKI_PERM = [
-  ...READ_GUARD,
-  '--allowedTools',
-  'Read',
-  'Grep',
-  'Glob',
-  'Edit',
-  'Write',
+/** The cartographer's shell: the consult readers, plus `mkdir` and `rm` for
+ *  the vault (pruning a stale page needs a real deletion — that is how the
+ *  sync protocol learns of it) and `git status`. The CLI path-validates
+ *  `mkdir`/`rm` to the working directories, which is why the vault is handed
+ *  over by `--add-dir` (runtimeClaude.mjs). No `find` (-exec/-delete) and no
+ *  `git grep` (-O<pager> runs a shell; the Grep tool covers search). */
+const WIKI_BASH = [
   'Bash(ls:*)',
   'Bash(wc:*)',
   'Bash(head:*)',
@@ -184,19 +194,86 @@ const WIKI_PERM = [
   'Bash(git rev-parse:*)',
 ];
 
+/**
+ * THE CARTOGRAPHER — read the repo, write the vault, and nothing else
+ * (2026-10-10, the audit: it joins the fenced postures of 2026-09-24).
+ *
+ * It ran on bare Read/Grep/Glob/Edit/Write, and its comment said file writes
+ * "never" exfiltrate and the worktree reset was the backstop. Neither held.
+ * The vault is an UPLINK — every page is synced to the project's wiki — so a
+ * bare Read of `~/.flowviant/credentials.json` copied into a page leaves the
+ * box; and the reset cleans the wiki worktree only, never a write outside it:
+ * `<vault>/.git/config` with a `core.fsmonitor` the daemon's own `git add`
+ * then ran, the checkout's `.flowviant/check.json`, a shell rc file. This turn
+ * runs UNATTENDED after every merge, on a member-written card title and on
+ * repo text, so the list is the enforcement and the prompt is only prose.
+ *
+ * Reads are the read fence (`fencedReads`: the worktree, the knowledge library
+ * when one is passed) plus the vault by its absolute path; Grep carries no
+ * allow rule, as in consult. The ONE write is `Edit(//<vault>/**)`, the vault's
+ * `.git` is denied both ways, and the checkout's secrets are denied by name.
+ *
+ * PROBED on Claude Code 2.1.296 before relying on it (2026-10-10), this exact
+ * list as the adapter builds it (`--add-dir <vault>`, stated `default` mode),
+ * cwd a detached worktree, the vault under `<home>/.flowviant/vaults/<id>`, a
+ * `-p` turn told to try each in turn:
+ *  · ALLOWED: Write of a new `<vault>/pages/x.md` and Edit of `<vault>/index.md`
+ *    (the Edit rule governs Write too; where ARTIFACT_WRITE's 2.1.281 note
+ *    below reads anchored spellings as no write, this `//`-anchored Edit rule
+ *    scoped as written on 2.1.296); `ls`, `rm` and `mkdir` in the vault; Read
+ *    and Glob in the vault and the worktree.
+ *  · REFUSED: Write of a canary outside both ("Claude requested permissions to
+ *    write to …, but you haven't granted it yet"), of the checkout's
+ *    `.flowviant/check.json`, of a file in the worktree itself, and of
+ *    `<vault>/.git/config` ("File is in a directory that is denied by your
+ *    permission settings"); Read of `<home>/.flowviant/credentials.json`, of the
+ *    checkout's `.git/config`, and of the worktree's `.env` (denied by name).
+ *    Every refused write left the disk unchanged.
+ *  · CONTROLS: without the Edit rule the vault page was refused too — so
+ *    `--add-dir` admits reads, never writes, and the rule is load-bearing;
+ *    without the `.git` deny, the `.git/config` write was still refused by the
+ *    CLI's own check ("… which is a sensitive file") — so the deny is a belt
+ *    on this CLI, kept because that check is the vendor's and unpinned.
+ *
+ * A vault no permission rule can name (not absolute, or carrying glob or rule
+ * syntax) gets NO list: `claudePermFor` answers null and Claude's adapter
+ * refuses the turn in words, rather than running it unfenced or unable to
+ * write.
+ */
+export function wikiPermFor(knowledgeDir, vaultDir) {
+  const vault = ruleSafeAbsolute(vaultDir);
+  if (!vault) return null;
+  return [
+    ...READ_GUARD,
+    '--allowedTools',
+    ...fencedReads(knowledgeDir),
+    `Read(/${vault}/**)`,
+    `Glob(/${vault}/**)`,
+    `Edit(/${vault}/**)`,
+    ...WIKI_BASH,
+    '--disallowedTools',
+    ...CHECKOUT_SECRETS,
+    `Read(/${vault}/.git/**)`,
+    `Edit(/${vault}/.git/**)`,
+  ];
+}
+
 // A CONSULT reads and answers. Nothing else.
 //
-// It used to run on WIKI_PERM, whose comment two blocks up says the quiet part:
-// Write/Edit "can't be path-scoped here; the worktree reset is the backstop".
-// That is a fine trade for the cartographer, which exists to author files and
-// gets reset after every turn. It is the wrong trade for a consult, whose prompt
-// is steered by a question ANY project editor can write and which had no reset
-// behind it — so a sentence in a chat box could reach Write, rm and mkdir on
-// someone else's machine. The permission list is the enforcement; the prompt's
-// "do not change anything" is only an instruction, and instructions are exactly
-// what an injected question competes with.
+// It used to run on the cartographer's old list, whose comment said the quiet
+// part: Write/Edit "can't be path-scoped here; the worktree reset is the
+// backstop". That was the wrong trade for a consult, whose prompt is steered
+// by a question ANY project editor can write and which had no reset behind it
+// — so a sentence in a chat box could reach Write, rm and mkdir on someone
+// else's machine (and it was the wrong trade for the cartographer too: see
+// `wikiPermFor`). The permission list is the enforcement; the prompt's "do not
+// change anything" is only an instruction, and instructions are exactly what
+// an injected question competes with.
+//
+// The checkout's secrets are denied by name (2026-10-10): a consult's answer
+// leaves the box, and intake's drafted brief lands on the board with no press.
 export function consultPermFor(knowledgeDir) {
-  return [...READ_GUARD, '--allowedTools', ...fencedReads(knowledgeDir), ...CONSULT_BASH];
+  return [...READ_GUARD, '--allowedTools', ...fencedReads(knowledgeDir), ...CONSULT_BASH, '--disallowedTools', ...CHECKOUT_SECRETS];
 }
 
 /**
@@ -306,7 +383,7 @@ const ARTIFACT_WRITE = 'Edit(.flowviant/artifacts/**)';
  *    `readOnlyHint: true`, and none of the session tools (stream_session_turn,
  *    log_work, file_card …) are read-only or annotated so. So a plan turn runs
  *    PLAIN — no MCP, the plain tab's contract — rather than mounting a control
- *    plane whose every call the CLI refuses. See workSessionTurns.mjs.
+ *    plane whose every call the CLI refuses. See workTurnShape.mjs.
  */
 export const PLAN_MODE_PERM = ['--permission-mode', 'plan'];
 export function designPermFor(knowledgeDir) {
@@ -355,7 +432,7 @@ export const RESEARCH_PERM = researchPerm(null);
  */
 const CLAUDE_PERM = {
   build: () => PERM,
-  wiki: () => WIKI_PERM,
+  wiki: (kd, vaultDir) => wikiPermFor(kd, vaultDir),
   consult: (kd) => consultPermFor(kd),
   plan: (kd) => planPermFor(kd),
   'plan-mode': () => PLAN_MODE_PERM,
@@ -370,8 +447,8 @@ const CLAUDE_PERM = {
   image: (kd) => consultPermFor(kd),
 };
 export const CLAUDE_PERM_PROFILES = Object.freeze(Object.keys(CLAUDE_PERM));
-export function claudePermFor(profileName, knowledgeDir) {
+export function claudePermFor(profileName, knowledgeDir, vaultDir) {
   const build = Object.hasOwn(CLAUDE_PERM, profileName) ? CLAUDE_PERM[profileName] : null;
   if (!build) throw new Error(`no Claude permission list for profile '${profileName}'`);
-  return build(knowledgeDir);
+  return build(knowledgeDir, vaultDir);
 }

package/bin/lib/claudeSessions.mjs

@@ -24,6 +24,8 @@ import {
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { parseProcStat } from './procStat.mjs';
+import { CLAUDE_SESSION_RE } from './conversationIds.mjs';
 
 // ENDED sessions are the adoptable inventory, and the useful ones are FRESH:
 // newest per directory, few. (The window itself is the coordinator's.)
@@ -87,7 +89,7 @@ function transcriptTitle(file, mtimeMs) {
  * the tab keeps whatever name it has.
  */
 export function titleForSession(cwd, sessionId) {
-  if (!cwd || typeof sessionId !== 'string' || !/^[A-Za-z0-9_-]{8,64}$/.test(sessionId)) {
+  if (!cwd || typeof sessionId !== 'string' || !CLAUDE_SESSION_RE.test(sessionId)) {
     return null;
   }
   const projects = join(homedir(), '.claude', 'projects');
@@ -137,8 +139,8 @@ export function claudeProjectDir(path) {
  * else, the file stays. `/proc/<pid>` existing only proves A process; the
  * starttime (field 22 of /proc/<pid>/stat) proves it is THAT process. The comm
  * field (parenthesised, may itself contain spaces and parens) makes naive
- * whitespace-splitting wrong, so fields are counted from after the LAST ')':
- * the first post-comm field is field 3, which puts starttime at index 19.
+ * whitespace-splitting wrong, so the line is read by procStat.mjs, the one
+ * parser that knows where `comm` ends.
  */
 function pidAlive(pid, procStart) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -174,10 +176,8 @@ function pidAlive(pid, procStart) {
     return false; // /proc is real and has no entry — the process is gone
   }
   if (procStart == null) return true; // nothing recorded to compare against
-  const close = stat.lastIndexOf(')');
-  if (close === -1) return false;
-  const fields = stat.slice(close + 1).trim().split(/\s+/);
-  return fields[19] === String(procStart);
+  const fields = parseProcStat(stat);
+  return fields !== null && String(fields.starttime) === String(procStart);
 }
 
 /**

package/bin/lib/claudeStream.mjs

@@ -12,16 +12,12 @@
 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
-// Write/Edit of a vault page is the "writing" signal. Used by wiki turns to
-// stream exactly which files Claude is touching (daemon console + app cover).
-//
-// The body moved to runtimeEvents.mjs, beside Codex's equivalent, because they are
-// the same job for two vendors and keeping them apart is how the two activity
-// vocabularies drift. Re-exported under its original name: a dozen call sites
-// know it, and none of them care where it lives.
-export const humanizeToolUse = humanizeClaudeTool;
+// One Claude tool_use becomes a compact activity {kind, label}, or null for
+// tools not worth surfacing, through `humanizeClaudeTool` — in runtimeEvents.mjs,
+// beside Codex's equivalent, because they are the same job for two vendors and
+// keeping them apart is how the two activity vocabularies drift. (Its old
+// alias here, `humanizeToolUse`, claimed a dozen call sites; the stream loop
+// below was the only one, and it calls the real name.)
 
 // Collapse whitespace + clip so a narration/thinking snippet is one tidy feed line.
 const oneLine = (s, n = 160) => String(s).replace(/\s+/g, ' ').trim().slice(0, n);
@@ -141,7 +137,7 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
         // the page to read.
         push({ kind: 'say', label: oneLine(b.text), full: b.text });
       } else if (b.type === 'tool_use') {
-        push(humanizeToolUse(b.name, b.input || {}, cwd));
+        push(humanizeClaudeTool(b.name, b.input || {}, cwd));
         // The STRUCTURED form of the same event, for the transcript's tool
         // cards — raw name + input, so the collector can keep what the
         // one-line humanizer drops (an Edit's counts, the plan's items).

package/bin/lib/cliLimit.mjs

@@ -5,7 +5,7 @@
  * which parks on it, and the pre-review, which only skips) and neither owns
  * it: it is a fact about what the CLIs print.
  */
-import { scrub as envScrub } from './uplinkScrub.mjs';
+import { scrubCut } from './uplinkScrub.mjs';
 
 /**
  * DID THE ACCOUNT HIT A LIMIT?
@@ -28,7 +28,7 @@ const LIMIT_PHRASES = [
 export const limitLine = (text) => {
   for (const line of String(text ?? '').split('\n')) {
     const t = line.trim();
-    if (t && LIMIT_PHRASES.some((re) => re.test(t))) return envScrub(t).slice(0, 300);
+    if (t && LIMIT_PHRASES.some((re) => re.test(t))) return scrubCut(t, 300);
   }
   return null;
 };

package/bin/lib/codexHome.mjs

@@ -0,0 +1,17 @@
+/**
+ * WHERE THIS ENVIRONMENT'S CODEX KEEPS ITS FILES (audit 2026-10-10, F126) —
+ * `$CODEX_HOME`, else `~/.codex`, with `~` resolved the way the CLI resolves
+ * it: the environment's own HOME first, the process's home only without one.
+ *
+ * A LEAF: node imports only. The login reader (codexPersonal.mjs), the
+ * rollout reader behind plan limits and "which model ran" (runtimeLimits.mjs),
+ * the offerings readout (runtimeOfferings.mjs) and an agent's isolated home
+ * (projectToolRuntimes.mjs) each spelled this rule, one of them differently;
+ * every one of them is a relay that must look where the CLI wrote.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function codexHome(env = process.env) {
+  return env.CODEX_HOME || join(env.HOME || homedir(), '.codex');
+}

package/bin/lib/codexPersonal.mjs

@@ -55,9 +55,9 @@
  * config read "Not logged in").
  */
 import { readFileSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { toml } from './projectToolRuntimes.mjs';
+import { codexHome } from './codexHome.mjs';
 
 /** Where the login lives and which endpoint it signs into — top-level keys,
  *  each confirmed in codex-cli 0.156.1 (`preferred_auth_method` is not one:
@@ -365,8 +365,7 @@ export function parseCodexToml(text) {
  * not a document this reader can read whole.
  */
 export function readPersonalCodexConfig(env = process.env) {
-  const home = env.CODEX_HOME || join(env.HOME || homedir(), '.codex');
-  const path = join(home, 'config.toml');
+  const path = join(codexHome(env), 'config.toml');
   try {
     if (statSync(path).size > CONFIG_MAX_BYTES) return null;
     return parseCodexToml(readFileSync(path, 'utf8'));
@@ -461,6 +460,48 @@ export function codexPersonalCarry(config, { model = null, effort = null, env: t
   return { args, env };
 }
 
+/**
+ * THE PERSON'S CODEX PROVIDER SECRETS, FOR THE UPLINK SCRUBBER ONLY
+ * (2026-10-10, the audit's F073) — `[{ name, value }]`, never a report.
+ *
+ * The header above says why the turn's own model can read these (`env` lists
+ * the carried literals; the read-only sandbox reads config.toml), and nothing
+ * taught the scrubber any of them, so a turn that printed one relayed it to
+ * every member of the project. The SELECTED provider's
+ * `experimental_bearer_token` and literal `http_headers` values, named as the
+ * carry names them (`CODEX_BEARER_ENV`, `CODEX_HEADER_ENV_PREFIX` + n), plus
+ * the present values of the variables its `env_key` and `env_http_headers`
+ * name, under those names. Whatever the posture: a build turn's Codex reads
+ * the same file. An unreadable or provider-less config gives `[]`, which the
+ * scrubber treats as "nothing new", never as "forget".
+ */
+export function codexSecretsOf(config, env = {}) {
+  const out = [];
+  if (!isTable(config)) return out;
+  const id = config.model_provider;
+  const table = isString(id) && id && isTable(config.model_providers) ? config.model_providers[id] : undefined;
+  if (!isTable(table)) return out;
+  if (nonEmpty(table.experimental_bearer_token)) {
+    out.push({ name: CODEX_BEARER_ENV, value: table.experimental_bearer_token });
+  }
+  if (isTable(table.http_headers)) {
+    let n = 0;
+    for (const literal of Object.values(table.http_headers)) {
+      if (nonEmpty(literal)) out.push({ name: `${CODEX_HEADER_ENV_PREFIX}${n++}`, value: literal });
+    }
+  }
+  const named = [table.env_key, ...(isTable(table.env_http_headers) ? Object.values(table.env_http_headers) : [])];
+  for (const name of named) {
+    if (nonEmpty(name) && nonEmpty(env[name])) out.push({ name, value: env[name] });
+  }
+  return out;
+}
+
+/** `codexSecretsOf` over the config this process's Codex would read. */
+export function readPersonalCodexSecrets(env = process.env) {
+  return codexSecretsOf(readPersonalCodexConfig(env), env);
+}
+
 /** The carry for one turn: the config its Codex would read, reduced. */
 export function codexPersonalTurn({ env = process.env, model = null, effort = null } = {}) {
   return codexPersonalCarry(readPersonalCodexConfig(env), { model, effort, env });

package/bin/lib/codexRelay.mjs

@@ -20,7 +20,7 @@
  * classifier. The sentence names what was measured and the one remedy the
  * machine's own CLI offers; Codex's own words stay beside it.
  */
-import { scrub as envScrub } from './uplinkScrub.mjs';
+import { scrub as envScrub, scrubCut } from './uplinkScrub.mjs';
 import { CODEX_RUNTIME } from './runtimeCodex.mjs';
 
 const NO_LOGIN = /unexpected status 401 Unauthorized: Missing bearer or basic authentication/;
@@ -55,9 +55,25 @@ export function codexApprovalSentence(refused) {
   return `Codex on the machine refused ${n} tool call${n === 1 ? '' : 's'} in this turn${which} — "MCP tool call requires approval, but approval policy is never" — so nothing ${n === 1 ? 'it' : 'they'} would have done was done.`;
 }
 
+/**
+ * WHAT A TERMINAL OR NEW TASK REPLY MAY CARRY BACK (2026-10-10, the audit's
+ * final cleanup; F042's daemon half). The server's `SESSION_ANSWER_MAX`
+ * (shared `fieldCaps.ts`): the settle route (`/fleet/work-turn-done`) cuts an
+ * answer there and the session writer clamps every message to it. The daemon
+ * cuts there too before it sends — `withRelay` below and the plain reply in
+ * `workSessionTurns.mjs` — so nothing past it crosses the wire. It was a bare
+ * `16000` in both; the release gate (`scripts/check-app-parity.mjs`, rule 29)
+ * holds this copy equal to the shared one.
+ */
+export const SESSION_ANSWER_MAX = 16_000;
+
 /** A reply with the sentence first and Codex's own words kept under it,
- *  scrubbed like every reply and cut to the lane's cap. */
-export function withRelay(sentence, raw, cap = 16000) {
-  const words = envScrub(String(raw ?? '')).trim();
-  return (words ? `${sentence}\n\n${words}` : sentence).slice(0, cap);
+ *  scrubbed like every reply and cut to the lane's cap — the words scrubbed
+ *  whole before they are trimmed, and the reply cut only after (`scrubCut`). */
+export function withRelay(sentence, raw, cap = SESSION_ANSWER_MAX) {
+  const reply = (s) => {
+    const words = envScrub(s).trim();
+    return words ? `${sentence}\n\n${words}` : sentence;
+  };
+  return scrubCut(raw, cap, reply);
 }

package/bin/lib/codexResearch.mjs

@@ -0,0 +1,180 @@
+/** Codex research reads a copied view, never the host checkout or login store.
+ * Linux/WSL only: the CLI process retains its login outside its tool sandbox;
+ * tools get root-denied reads, a clean environment and no shell snapshots.
+ * Web search is a CLI tool, not direct shell network access.
+ */
+import { execFileSync } from 'node:child_process';
+import { git } from './git.mjs';
+import { ensureRealSubdir, realDirState } from './ownedDirs.mjs';
+import { closeSync, constants, copyFileSync, existsSync, fstatSync, openSync, readFileSync, readSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+
+const MAX_FILES = 20_000;
+const MAX_BYTES = 128 * 1024 * 1024;
+const omitted = (name) => /^(\.git|\.env.*|\.claude|\.codex|\.mcp\.json|node_modules|credentials(?:\..*)?|auth\.json)$/i.test(name) || /\.(pem|key|p12|pfx)$/i.test(name);
+
+/** Fresh copies also break hardlinks. Symlinks, devices and sockets never ride.
+ * Refuse over the bound instead of presenting a silently incomplete repo.
+ */
+export function copyResearchView(source, destination, budget = { files: 0, bytes: 0 }) {
+  mkdirSync(destination, { recursive: true, mode: 0o700 });
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    if (omitted(entry.name)) continue;
+    const from = join(source, entry.name);
+    const to = join(destination, entry.name);
+    const stat = lstatSync(from);
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) {
+      // Only the card's files and kept library are inputs from .flowviant.
+      if (entry.name === '.flowviant') {
+        for (const input of ['uploads', 'knowledge', 'artifacts']) {
+          const dir = join(from, input);
+          if (realDirState(dir) === 'dir')
+            copyResearchView(dir, join(to, input), budget);
+        }
+      } else copyResearchView(from, to, budget);
+    } else if (stat.isFile()) {
+      budget.files += 1;
+      budget.bytes += stat.size;
+      if (budget.files > MAX_FILES || budget.bytes > MAX_BYTES)
+        throw new Error('The isolated research copy exceeds 20,000 files or 128 MB. Narrow the repository inputs before trying again.');
+      // A file replaced by a symlink between enumeration and copy must not
+      // bring host data into the readable view. Copy through a no-follow fd.
+      const fd = openSync(from, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        if (!fstatSync(fd).isFile()) throw new Error('A research input changed while copying.');
+        copyFileSync(`/proc/self/fd/${fd}`, to);
+      } finally { closeSync(fd); }
+    }
+  }
+}
+
+/** Resolve the actual sandbox helper without granting the person's bin/home.
+ * Support native installs and the npm wrapper's platform package. Unknown
+ * installations refuse; granting the whole home to find a helper is no fence.
+ */
+export function codexResearchHelper(env = process.env) {
+  const command = (env.PATH ?? '').split(':').map((dir) => join(dir, 'codex')).find((file) => existsSync(file));
+  if (!command) throw new Error('Codex is not installed on PATH.');
+  const executable = realpathSync(command);
+  const fd = openSync(executable, 'r');
+  const magic = Buffer.alloc(4);
+  try { readSync(fd, magic, 0, 4, 0); } finally { closeSync(fd); }
+  if (magic.equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46]))) return executable;
+  const target = process.arch === 'arm64' ? 'aarch64-unknown-linux-musl' : 'x86_64-unknown-linux-musl';
+  const platform = `@openai/codex-linux-${process.arch === 'arm64' ? 'arm64' : 'x64'}`;
+  let root;
+  try { root = dirname(createRequire(executable).resolve(`${platform}/package.json`)); }
+  catch { root = resolve(dirname(executable), '..'); }
+  const binary = join(root, 'vendor', target, 'bin', 'codex');
+  if (!existsSync(binary)) throw new Error('This Codex installation has no measured Linux research sandbox helper.');
+  return realpathSync(binary);
+}
+
+/** The research posture's own pairs: the copied view's filesystem table, no
+ * shell network, live web, a clean shell environment. runtimeCodex.mjs ends it
+ * in the shared fenced tail (sub-agents, browser, image generation, the
+ * person's config and rules), with the web left on: it is this posture's tool.
+ */
+export function researchFence({ cwd, helper }) {
+  if (process.platform !== 'linux' || !isAbsolute(cwd ?? '') || !isAbsolute(helper ?? ''))
+    throw new Error('Isolated Codex research requires Linux or WSL and absolute sandbox paths.');
+  const artifacts = join(cwd, '.flowviant/artifacts');
+  const scratch = join(cwd, '.flowviant/tmp');
+  const rules = { ':root': 'deny', ':minimal': 'read', [helper]: 'read', [cwd]: 'read', [artifacts]: 'write', [scratch]: 'write' };
+  const table = '{' + Object.entries(rules).map(([path, access]) => `${JSON.stringify(path)}=${JSON.stringify(access)}`).join(',') + '}';
+  return [
+    '-c', `permissions.flowviantresearch.filesystem=${table}`,
+    '-c', 'permissions.flowviantresearch.network.enabled=false',
+    '-c', 'default_permissions="flowviantresearch"',
+    '-c', 'approval_policy="never"',
+    '-c', 'web_search="live"', '-c', 'tools.web_search=true',
+    '-c', 'features.shell_snapshot=false', '-c', 'allow_login_shell=false',
+    '-c', 'shell_environment_policy.inherit="none"',
+    '-c', `shell_environment_policy.set={PATH="/usr/bin:/bin",HOME=${JSON.stringify(scratch)},TMPDIR=${JSON.stringify(scratch)},BROWSER="none"}`,
+    '--disable', 'view_image',
+    '--skip-git-repo-check',
+  ];
+}
+
+/** Copy only regular Markdown outputs back. Never follow a model-written link,
+ * nor one standing in the worktree: a destination directory must be a real one
+ * or absent (ownedDirs.mjs, the daemon's one link rule), and a file is written
+ * only where nothing or a regular file stands, created exclusively so a link
+ * swapped in after the look is never followed. A write-up already holding
+ * these exact bytes is left alone: the copied view carried it in, and its
+ * mtime is the artifact scan's evidence that the turn did not write it
+ * (artifacts.mjs `writtenSince`), so a turn that wrote nothing delivers
+ * nothing. Artifact publication stays in the original worktree for the
+ * existing uploader.
+ */
+export function publishResearch(source, destination) {
+  if (realDirState(destination) === 'none') mkdirSync(destination, { recursive: true });
+  if (realDirState(destination) !== 'dir') throw new Error('The research artifact destination is not a real directory.');
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    const from = join(source, entry.name);
+    const to = join(destination, entry.name);
+    const stat = lstatSync(from);
+    if (stat.isSymbolicLink()) throw new Error('An isolated research output is a symlink; nothing was accepted through it.');
+    if (stat.isDirectory()) publishResearch(from, to);
+    else if (stat.isFile() && /\.md$/i.test(entry.name)) {
+      if (stat.size > 2 * 1024 * 1024) throw new Error('The research Markdown output exceeds 2 MB.');
+      let there = null;
+      try {
+        there = lstatSync(to);
+      } catch (e) {
+        if (e?.code !== 'ENOENT') throw e;
+      }
+      if (there && !there.isFile()) throw new Error('The research output would overwrite a non-file.');
+      const bytes = readFileSync(from);
+      if (there && there.size === bytes.length && readFileSync(to).equals(bytes)) continue;
+      if (there) unlinkSync(to);
+      writeFileSync(to, bytes, { flag: 'wx' });
+    }
+  }
+}
+
+export async function runIsolatedResearch(opts, run, {
+  resolveHelper = codexResearchHelper,
+  readVersion = (helper) => execFileSync(helper, ['--version'], { encoding: 'utf8', timeout: 10_000 }),
+} = {}) {
+  if (process.platform !== 'linux') throw new Error('Isolated Codex research requires Linux or WSL.');
+  const original = realpathSync(opts.cwd);
+  const helper = resolveHelper();
+  const version = readVersion(helper).match(/codex-cli (\d+)\.(\d+)\.(\d+)/);
+  if (!version || version.slice(1).map(Number).reduce((n, v) => n * 1000 + v, 0) < 159002)
+    throw new Error('Isolated research needs Codex CLI 0.159.2 or newer. Restart after updating Codex.');
+  // Both publication parents must be real directories in this checkout, or
+  // absent — never a link, dangling or not (ownedDirs.mjs).
+  for (const dir of [join(original, '.flowviant'), join(original, '.flowviant/artifacts')])
+    if (realDirState(dir) === 'other')
+      throw new Error('The research artifact destination is not a real directory.');
+  // Kept path across resumes, outside the source tree and separate from Codex's
+  // login/thread home. The caller's agent lock serializes turns in this place.
+  const gitDir = git(['rev-parse', '--absolute-git-dir'], original);
+  const isolation = join(gitDir, 'flowviant-research');
+  if (existsSync(isolation) && lstatSync(isolation).isSymbolicLink()) throw new Error('The research isolation directory is a symlink.');
+  rmSync(isolation, { recursive: true, force: true });
+  const snapshot = join(isolation, 'repo');
+  try {
+    copyResearchView(original, snapshot);
+    let knowledge = null;
+    if (opts.knowledgeDir) {
+      knowledge = join(snapshot, '.flowviant/knowledge');
+      copyResearchView(realpathSync(opts.knowledgeDir), knowledge);
+    }
+    for (const dir of ['artifacts', 'tmp']) mkdirSync(join(snapshot, '.flowviant', dir), { recursive: true, mode: 0o700 });
+    const rewrite = (text) => typeof text === 'string'
+      ? text.replaceAll(original, snapshot).replaceAll(opts.knowledgeDir || '\0', knowledge || '\0') : text;
+    const intro = 'This fresh research turn uses an isolated read-only copy. Prior reports are available under .flowviant/artifacts/; previous CLI conversations are not resumed because they may contain host secrets. Git metadata, .env files, credential files, symlinks and personal CLI settings are omitted. Write the Markdown report only under .flowviant/artifacts/. Web search is available; shell networking is disabled. Use exec_command with shell=/bin/bash and login=false; personal shells are outside the fence.\n\n';
+    const result = await run({ ...opts, resume: false, resumeThreadId: null, resumeConversationId: null, cwd: snapshot, knowledgeDir: knowledge,
+      prompt: intro + rewrite(opts.prompt), system: rewrite(opts.system),
+      researchIsolation: { cwd: snapshot, helper } });
+    // Made, or found, real at publication too: every component checked again.
+    if (!ensureRealSubdir(original, '.flowviant/artifacts'))
+      throw new Error('The research artifact destination is not a real directory.');
+    publishResearch(join(snapshot, '.flowviant/artifacts'), join(original, '.flowviant/artifacts'));
+    return typeof result === 'string' ? result.replaceAll(snapshot, original) : result;
+  } finally { rmSync(isolation, { recursive: true, force: true }); }
+}