flowviant 0.125.5 → 0.125.6

package/bin/lib/claudeSubagentProgress.mjs

@@ -6,11 +6,11 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { claudeProjectDir } from './claudeSessions.mjs';
 import { CLAUDE_SESSION_RE } from './conversationIds.mjs';
+import { followJsonl, newTail } from './jsonlTail.mjs';
 
-const MAX_READ = 4 * 1024 * 1024;
-const LINE_MAX = 256 * 1024;
 export function createClaudeSubagentProgress({ cwd, since = Date.now(), env = process.env, onLine }) {
-  let file, offset = null, rest = Buffer.alloc(0), skip = false, timer;
+  const tail = newTail();
+  let file, timer;
   let chain = Promise.resolve();
   const flush = () => {
     chain = chain.then(async () => {
@@ -18,31 +18,15 @@ export function createClaudeSubagentProgress({ cwd, since = Date.now(), env = pr
       let fh;
       try {
         fh = await open(file, 'r');
-        const { size } = await fh.stat();
-        if (offset === null) { offset = Math.max(0, size - MAX_READ); skip = offset > 0; }
-        if (size < offset) { offset = 0; rest = Buffer.alloc(0); }
-        const end = Math.min(size, offset + MAX_READ);
-        while (offset < end) {
-          const buf = Buffer.alloc(Math.min(LINE_MAX, end - offset));
-          const { bytesRead } = await fh.read(buf, 0, buf.length, offset);
-          if (!bytesRead) break;
-          offset += bytesRead;
-          const data = Buffer.concat([rest, buf.subarray(0, bytesRead)]);
-          let start = 0, nl;
-          while ((nl = data.indexOf(10, start)) >= 0) {
-            const line = data.subarray(start, nl).toString('utf8'); start = nl + 1;
-            if (skip) { skip = false; continue; }
-            try {
-              const ev = JSON.parse(line);
-              if (ev.type !== 'progress' || ev.data?.type !== 'agent_progress' || !ev.parentToolUseID) continue;
-              const at = Date.parse(ev.timestamp ?? '');
-              if (!Number.isFinite(at) || at < since) continue;
-              onLine(line);
-            } catch { /* torn or unknown native row */ }
-          }
-          rest = data.subarray(start);
-          if (rest.length > LINE_MAX) { rest = Buffer.alloc(0); skip = true; }
-        }
+        await followJsonl(fh, tail, line => {
+          try {
+            const ev = JSON.parse(line);
+            if (ev.type !== 'progress' || ev.data?.type !== 'agent_progress' || !ev.parentToolUseID) return;
+            const at = Date.parse(ev.timestamp ?? '');
+            if (!Number.isFinite(at) || at < since) return;
+            onLine(line);
+          } catch { /* torn or unknown native row */ }
+        });
       } catch { /* the transcript can appear after init */ }
       finally { await fh?.close().catch(() => {}); }
     }).catch(() => {});

package/bin/lib/claudeSubagents.mjs

@@ -1,3 +1,5 @@
+import { NATIVE_AGENT_TOOLS } from './nativeAgentTools.mjs';
+
 /** Native tool-use ids are stable for the lifetime of an Agent/Task call. */
 export function createClaudeSubagents(report = () => {}) {
   const calls = new Map();
@@ -29,12 +31,12 @@ export function createClaudeSubagents(report = () => {}) {
       const agentId = identify(ev);
       if (ev.type === 'assistant') {
         for (const b of ev.message?.content ?? []) {
-          if (b.type === 'tool_use' && b.name === 'AskUserQuestion' && agentId) {
+          if (b.type === 'tool_use' && NATIVE_AGENT_TOOLS.claude.ask.includes(b.name) && agentId) {
             questions.set(b.id, agentId);
             if (questions.size > 128) questions.delete(questions.keys().next().value);
             report({ id: agentId, status: 'asked' });
           }
-          if (b.type !== 'tool_use' || !['Agent', 'Task'].includes(b.name) || !b.id) continue;
+          if (b.type !== 'tool_use' || !NATIVE_AGENT_TOOLS.claude.spawn.includes(b.name) || !b.id) continue;
           const input = b.input ?? {};
           const id = aliases.get(input.resume) ?? b.id;
           calls.set(b.id, { id, input });

package/bin/lib/codexFencedMount.mjs

@@ -0,0 +1,275 @@
+/**
+ * THE MCP SERVERS ON A FENCED CODEX TURN, AS `-c` PAIRS — the project's and
+ * the machine's own (`codexFencedMount`, below). Split out of
+ * projectToolRuntimes.mjs (2026-10-17), whose table row hands it out as
+ * `fencedMount`; the build's config.toml stays there.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { codexHome } from './codexHome.mjs';
+import { parseCodexToml, TomlRaw, toml, tomlValue } from './codexToml.mjs';
+
+/** The environment names a fenced Codex turn's MCP header values ride under,
+ *  one per header (`codexFencedMount`). */
+export const MCP_HEADER_ENV_PREFIX = 'FLOWVIANT_MCP_HEADER_';
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const SERVER_NAME = /^[A-Za-z0-9_-]{1,80}$/;
+const expands = (value) => /\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(String(value));
+/**
+ * Names this machine's Codex, or the shell and tools under it, read for
+ * themselves. A server's env value rides in the CLI's own environment
+ * (`env_vars` forwards it), so a name the machine does not already set to that
+ * value would change how the CLI itself runs — a proxy, a CA bundle, a
+ * provider key. Such a server is left unmounted, in words.
+ */
+const CLI_ENV =
+  /^(PATH|HOME|SHELL|USER|LOGNAME|PWD|TMPDIR|TMP|TEMP|TERM|LANG|LANGUAGE|DISPLAY|WAYLAND_DISPLAY|BROWSER|NODE_OPTIONS|NODE_PATH|NODE_EXTRA_CA_CERTS|SSL_CERT_FILE|SSL_CERT_DIR|REQUESTS_CA_BUNDLE|RUST_LOG|RUST_BACKTRACE|HTTPS?_PROXY|ALL_PROXY|NO_PROXY|https?_proxy|all_proxy|no_proxy)$|^(LC|XDG|LD|DYLD|OPENAI|CODEX|AZURE_OPENAI|FLOWVIANT)_/;
+
+/** This machine's own Codex servers: its config.toml's `[mcp_servers.*]`,
+ *  read the way codexPersonal.mjs reads the login (bounded; a file that does
+ *  not parse carries nothing). `[]` when there is no file, NULL when there is
+ *  one this cannot read (2026-10-17: unknown, never "none"). */
+function machineCodexServers(machineEnv) {
+  let text;
+  try {
+    const path = join(resolve(codexHome(machineEnv)), 'config.toml');
+    const st = statSync(path);
+    if (!st.isFile() || st.size > 1024 * 1024) return null;
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    return error?.code === 'ENOENT' ? [] : null;
+  }
+  try {
+    const servers = parseCodexToml(text)?.mcp_servers;
+    if (servers === undefined) return [];
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return null;
+    return Object.entries(servers).filter(([, v]) => v && typeof v === 'object' && !Array.isArray(v));
+  } catch {
+    return null;
+  }
+}
+const APPROVAL_MODES = new Set(['auto', 'prompt', 'writes', 'approve']);
+const tomlScalar = (v) => (v instanceof TomlRaw ? v.text : typeof v === 'number' && Number.isFinite(v) ? String(v) : null);
+const words = (v) => (Array.isArray(v) && v.every((x) => typeof x === 'string') ? v : null);
+const table = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+
+/**
+ * THE MCP SERVERS ON A FENCED CODEX TURN — the project's and, since 2026-10-11,
+ * the machine's own (the owner: "the server that is running flowviant's claude
+ * HAS these MCPs yet the agents are not using them"). A Codex build reads both
+ * from the agent's config.toml (`isolatedCodexHome`: the person's own tables
+ * kept, the repo's beside them). Every fenced posture — write-up, mockup,
+ * 3D model, deck, image — passes `--ignore-user-config`, which drops that
+ * file, and a `-p` profile layered beside the flag was measured to load no
+ * server either (codex-cli 0.159.2, artifactProjectMcp.test.mjs). So these
+ * turns take the servers as `-c` pairs, the way codexPersonal.mjs carries a
+ * login back, under the same rule: A LITERAL SECRET NEVER RIDES ARGV.
+ *
+ *  · A stdio server's command and arguments ride as written: they are the
+ *    server process's own command line once Codex starts it, so `-c` adds no
+ *    reader. A project server whose command or arguments expand a `${VAR}`
+ *    is still left unmounted (the 2026-10-10 audit took expanded values off
+ *    argv, and this keeps that line).
+ *  · Every env value rides in the turn's ENVIRONMENT under its own name,
+ *    forwarded by Codex's `env_vars` — except a project value with no `${VAR}`,
+ *    which is text of the reviewed file and rides as written. Refused (the
+ *    server is left unmounted, with the reason) when the name is the
+ *    daemon's own (`FLOWVIANT_*`, `CODEX_HOME`), when this machine already
+ *    sets it to something else, or when it is one the CLI reads itself
+ *    (`CLI_ENV`) and the machine does not set it.
+ *  · Every header value rides in the environment, named by
+ *    `env_http_headers`. A machine server's own `env_http_headers`,
+ *    `bearer_token_env_var` and `env_vars` are names, and ride as written.
+ *  · A URL that expands a `${VAR}`, or carries a query, fragment or
+ *    credentials, has no indirection in Codex's config: left unmounted.
+ *  · A machine server keeps its own `cwd`, timeouts, tool lists, header
+ *    helper (a command, riding as written, as a stdio command does), OAuth
+ *    scopes, resource and settings — all but `oauth.client_secret`, which
+ *    stays off argv and is said; it is skipped where the person turned it
+ *    off (`enabled = false`), and a project server of the same name replaces
+ *    it, as on the build. The person's own `flowviant` rides too: a card
+ *    mints no Flowviant server of its own (hooks/mcpAllow.mjs, 2026-10-17).
+ *  · Each mounted server's tools are approved by name: an unannotated tool
+ *    under a fenced posture failed "MCP tool call requires approval, but
+ *    approval policy is never" (measured, 0.159.2) — never a blanket
+ *    approval policy. A machine server keeps the person's own modes, its
+ *    default and each tool's (2026-10-17: an unconditional approval
+ *    overrode a person's "prompt"), and is approved only where they set
+ *    none; one that asks before every call is left unmounted, and one with
+ *    tools that ask is mounted and said (`partial`), since nobody can
+ *    approve on this turn (measured, 0.163.0: a tool's mode beats its
+ *    server's, and "auto", "writes" and "prompt" each refuse an unannotated
+ *    tool there).
+ *
+ * `usable` is the base snapshot's ready entries, `turnServers` the card's
+ * own (prepareAgentTools); `expand` reads a value the
+ * way projectTools.mjs does; `machineEnv` is the caller's own (what the child
+ * would inherit). Returns `{ args, env, mounted, machine, unmounted }`:
+ * `mounted` the project servers, `machine` the machine's own (null when its
+ * config.toml could not be read), and
+ * `unmounted` `[{ name, reason, source: 'project' | 'machine', partial? }]`.
+ */
+export function codexFencedMount(usable, expand, machineEnv, turnServers = {}) {
+  const args = [];
+  const childEnv = {};
+  const mounted = [];
+  const machine = [];
+  const unmounted = [];
+  let header = 0;
+  /** A refusal sentence, or null with the value staged in `extra`. */
+  const forward = (key, value, extra) => {
+    if (key.startsWith('FLOWVIANT_') || key === 'CODEX_HOME') return `its env ${key} is a name this daemon keeps for itself`;
+    const has = machineEnv[key];
+    if (has !== undefined) return has === value ? null : `its env ${key} would replace this machine's own ${key}, which a fenced Codex turn cannot do`;
+    if (CLI_ENV.test(key)) return `its env ${key} is one this machine's Codex reads itself, which a fenced Codex turn cannot set`;
+    const staged = childEnv[key] ?? extra[key];
+    if (staged !== undefined && staged !== value) return `its env ${key} would replace another server's ${key}`;
+    extra[key] = value;
+    return null;
+  };
+  const headerEnv = (headers, extra) =>
+    Object.entries(headers).map(([key, value]) => {
+      const envName = `${MCP_HEADER_ENV_PREFIX}${header++}`;
+      extra[envName] = value;
+      return `${toml(key)}=${toml(envName)}`;
+    });
+  const approve = (name) => ['-c', `mcp_servers.${name}.default_tools_approval_mode="approve"`];
+  const accept = (name, pairs, extra, list, approval = approve(name)) => {
+    args.push(...pairs, ...approval);
+    Object.assign(childEnv, extra);
+    list.push(name);
+  };
+
+  // THE CARD'S OWN SERVERS (2026-10-17) — `card_repositories` on a
+  // multi-repository card — which rode only the home's config.toml, ignored
+  // here. The daemon's words; their env by name (the values are the turn's
+  // environment already), and no project or machine server of their name.
+  const owned = Object.entries(turnServers ?? {}).filter(([name, c]) => SERVER_NAME.test(name) && typeof c?.command === 'string');
+  for (const [name, config] of owned) {
+    const keys = Object.keys(config.env ?? {}).filter((k) => ENV_NAME.test(k));
+    const pairs = ['-c', `mcp_servers.${name}.command=${toml(config.command)}`, '-c', `mcp_servers.${name}.args=[${(Array.isArray(config.args) ? config.args : []).map((v) => toml(String(v))).join(',')}]`];
+    if (keys.length) pairs.push('-c', `mcp_servers.${name}.env_vars=[${keys.map(toml).join(',')}]`);
+    accept(name, pairs, Object.fromEntries(keys.map((k) => [k, String(config.env[k])])), []);
+  }
+  const ownNames = new Set(owned.map(([name]) => name));
+
+  for (const { name, config } of usable) {
+    if (ownNames.has(name)) continue;
+    const pairs = [];
+    const extra = {};
+    let refused = null;
+    if (typeof config.command === 'string') {
+      const rawArgs = Array.isArray(config.args) ? config.args : [];
+      if (expands(config.command) || rawArgs.some(expands)) {
+        refused = 'its command or arguments name a ${VAR}, which a fenced Codex turn would put on the command line';
+      } else {
+        pairs.push('-c', `mcp_servers.${name}.command=${toml(String(config.command))}`);
+        pairs.push('-c', `mcp_servers.${name}.args=[${rawArgs.map((v) => toml(String(v))).join(',')}]`);
+        const forwarded = [];
+        for (const [key, value] of Object.entries(config.env ?? {})) {
+          if (!ENV_NAME.test(key)) continue;
+          if (!expands(value)) {
+            pairs.push('-c', `mcp_servers.${name}.env.${key}=${toml(String(value))}`);
+            continue;
+          }
+          refused = forward(key, expand(value), extra);
+          if (refused) break;
+          forwarded.push(key);
+        }
+        if (forwarded.length) pairs.push('-c', `mcp_servers.${name}.env_vars=[${forwarded.map(toml).join(',')}]`);
+      }
+    } else if (typeof config.url === 'string') {
+      if (expands(config.url)) {
+        refused = 'its URL names a ${VAR}, which a fenced Codex turn would put on the command line';
+      } else {
+        pairs.push('-c', `mcp_servers.${name}.url=${toml(String(config.url))}`);
+        const named = headerEnv(Object.fromEntries(Object.entries(config.headers ?? {}).map(([k, v]) => [k, expand(v)])), extra);
+        if (named.length) pairs.push('-c', `mcp_servers.${name}.env_http_headers={${named.join(',')}}`);
+      }
+    } else continue;
+    if (refused) unmounted.push({ name, reason: refused, source: 'project' });
+    else accept(name, pairs, extra, mounted);
+  }
+
+  const projectNames = new Set([...usable.map((t) => t.name), ...ownNames]);
+  const personal = machineCodexServers(machineEnv);
+  for (const [name, server] of personal ?? []) {
+    if (projectNames.has(name) || server.enabled === false) continue;
+    if (typeof server.command !== 'string' && typeof server.url !== 'string') continue;
+    const pairs = [];
+    const extra = {};
+    const partial = [];
+    let refused = SERVER_NAME.test(name) ? null : 'its name cannot be spelled as a command-line setting';
+    if (!refused && typeof server.command === 'string') {
+      const rawArgs = server.args === undefined ? [] : words(server.args);
+      if (!rawArgs) refused = 'its args are not a list of words';
+      else {
+        pairs.push('-c', `mcp_servers.${name}.command=${toml(server.command)}`);
+        pairs.push('-c', `mcp_servers.${name}.args=[${rawArgs.map(toml).join(',')}]`);
+        const forwarded = [...(words(server.env_vars) ?? []).filter((k) => ENV_NAME.test(k))];
+        for (const [key, value] of Object.entries(table(server.env))) {
+          if (!ENV_NAME.test(key) || typeof value !== 'string') {
+            refused = `its env ${String(key).slice(0, 40)} is not a name and text`;
+            break;
+          }
+          refused = forward(key, value, extra);
+          if (refused) break;
+          if (!forwarded.includes(key)) forwarded.push(key);
+        }
+        if (forwarded.length) pairs.push('-c', `mcp_servers.${name}.env_vars=[${forwarded.map(toml).join(',')}]`);
+        if (typeof server.cwd === 'string') pairs.push('-c', `mcp_servers.${name}.cwd=${toml(server.cwd)}`);
+      }
+    } else if (!refused) {
+      let url = null;
+      try { url = new URL(server.url); } catch { /* refused below */ }
+      if (!url || url.search || url.hash || url.username || url.password) {
+        refused = 'its URL carries a query, fragment or credentials, which a fenced Codex turn would put on the command line';
+      } else {
+        pairs.push('-c', `mcp_servers.${name}.url=${toml(server.url)}`);
+        if (typeof server.bearer_token_env_var === 'string' && ENV_NAME.test(server.bearer_token_env_var))
+          pairs.push('-c', `mcp_servers.${name}.bearer_token_env_var=${toml(server.bearer_token_env_var)}`);
+        const literal = table(server.http_headers);
+        const byName = table(server.env_http_headers);
+        if (Object.values(literal).some((v) => typeof v !== 'string') || Object.values(byName).some((v) => typeof v !== 'string' || !ENV_NAME.test(v))) {
+          refused = 'its headers are not text';
+        } else {
+          const named = [...headerEnv(literal, extra), ...Object.entries(byName).map(([key, envName]) => `${toml(key)}=${toml(envName)}`)];
+          if (named.length) pairs.push('-c', `mcp_servers.${name}.env_http_headers={${named.join(',')}}`);
+          if (typeof server.http_headers_helper === 'string') pairs.push('-c', `mcp_servers.${name}.http_headers_helper=${toml(server.http_headers_helper)}`);
+          if (words(server.scopes)) pairs.push('-c', `mcp_servers.${name}.scopes=[${server.scopes.map(toml).join(',')}]`);
+          if (typeof server.oauth_resource === 'string') pairs.push('-c', `mcp_servers.${name}.oauth_resource=${toml(server.oauth_resource)}`);
+          const oauth = Object.entries(table(server.oauth)).filter(([key, v]) => key !== 'client_secret' && (typeof v === 'string' || typeof v === 'boolean' || tomlScalar(v) != null));
+          if (oauth.length) pairs.push('-c', `mcp_servers.${name}.oauth=${tomlValue(Object.fromEntries(oauth))}`);
+          if (Object.hasOwn(table(server.oauth), 'client_secret')) partial.push('its OAuth client secret stays off this turn’s command line, so a sign-in or refresh that needs it fails');
+        }
+      }
+    }
+    // The person's approval modes, as written; approved where they set none.
+    const mode = APPROVAL_MODES.has(server.default_tools_approval_mode) ? server.default_tools_approval_mode : null;
+    const tools = Object.entries(table(server.tools)).filter(([, v]) => APPROVAL_MODES.has(table(v).approval_mode));
+    const approval = ['-c', `mcp_servers.${name}.default_tools_approval_mode=${toml(mode ?? 'approve')}`];
+    if (tools.length) approval.push('-c', `mcp_servers.${name}.tools=${tomlValue(Object.fromEntries(tools.map(([tool, v]) => [tool, { approval_mode: v.approval_mode }])))}`);
+    if (!refused && mode === 'prompt' && !tools.some(([, v]) => v.approval_mode === 'approve')) {
+      refused = 'it asks for approval before every tool call (default_tools_approval_mode = "prompt"), and nobody can approve one on this turn';
+    }
+    const asking = tools.filter(([, v]) => v.approval_mode !== 'approve').map(([tool]) => tool);
+    if (mode && mode !== 'approve') partial.unshift(`its tools ask for approval (default_tools_approval_mode = "${mode}"), and a call that asks fails here, where nobody can approve one`);
+    else if (asking.length) partial.unshift(`its tools ${asking.join(', ')} ask for approval, and a call to one fails here, where nobody can approve one`);
+    if (!refused) {
+      for (const key of ['startup_timeout_sec', 'startup_timeout_ms', 'tool_timeout_sec']) {
+        const v = tomlScalar(server[key]);
+        if (v != null && /^[0-9_.]+$/.test(v)) pairs.push('-c', `mcp_servers.${name}.${key}=${v}`);
+      }
+      for (const key of ['enabled_tools', 'disabled_tools']) {
+        const list = words(server[key]);
+        if (list) pairs.push('-c', `mcp_servers.${name}.${key}=[${list.map(toml).join(',')}]`);
+      }
+    }
+    if (refused) unmounted.push({ name, reason: refused, source: 'machine' });
+    else {
+      accept(name, pairs, extra, machine, approval);
+      if (partial.length) unmounted.push({ name, reason: partial.join('; '), source: 'machine', partial: true });
+    }
+  }
+  return { args, env: childEnv, mounted, machine: personal == null ? null : machine, unmounted };
+}

package/bin/lib/codexPersonal.mjs

@@ -56,7 +56,7 @@
  */
 import { readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { toml } from './projectToolRuntimes.mjs';
+import { isTable, newTable, parseCodexToml, tomlValue } from './codexToml.mjs';
 import { codexHome } from './codexHome.mjs';
 
 /** Where the login lives and which endpoint it signs into — top-level keys,
@@ -104,259 +104,6 @@ export const CODEX_HEADER_ENV_PREFIX = 'FLOWVIANT_CODEX_SECRET_HEADER_';
 
 /** Far past any real config.toml; a bigger one is not read. */
 const CONFIG_MAX_BYTES = 1024 * 1024;
-/** Arrays and inline tables nest no deeper than this in a file we read. */
-const MAX_DEPTH = 32;
-
-/** A number, date or time, kept as written so it is carried as written. */
-export class TomlRaw {
-  constructor(text) {
-    this.text = text;
-  }
-}
-const newTable = () => Object.create(null);
-const isTable = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof TomlRaw);
-
-const BARE = /[A-Za-z0-9_-]+/y;
-// First match wins, so the forms that begin like an integer come first.
-const SCALAR =
-  /[+-]?(?:inf|nan)|0x[0-9A-Fa-f](?:_?[0-9A-Fa-f])*|0o[0-7](?:_?[0-7])*|0b[01](?:_?[01])*|\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:[Zz]|[+-]\d{2}:\d{2})?)?|\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?|[+-]?\d(?:_?\d)*(?:\.\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?/y;
-
-/**
- * A BOUNDED TOML READER — the repo carries no TOML library, and the one file
- * it reads is Codex's own config. Whole documents: tables, arrays of tables
- * (the daemon's own `[[skills.config]]` in an agent's home), dotted and quoted
- * keys, the four string forms, arrays, inline tables, booleans, and numbers,
- * dates and times kept as written. Anything else throws, and the caller
- * carries nothing — a partial read is never a license to guess.
- */
-export function parseCodexToml(text) {
-  const src = String(text).replace(/^/, '');
-  const n = src.length;
-  let i = 0;
-  const fail = (why) => {
-    throw new Error(`config.toml: ${why} at offset ${i}`);
-  };
-  const ws = () => {
-    while (i < n && (src[i] === ' ' || src[i] === '\t')) i++;
-  };
-  const comment = () => {
-    if (src[i] === '#') while (i < n && src[i] !== '\n') i++;
-  };
-  const newline = () => {
-    if (src[i] === '\n') return (i += 1), true;
-    if (src[i] === '\r' && src[i + 1] === '\n') return (i += 2), true;
-    return false;
-  };
-  /** Blank lines, comments and whitespace, as between array items. */
-  const gap = () => {
-    for (;;) {
-      ws();
-      comment();
-      if (!newline()) return;
-    }
-  };
-  const endOfLine = () => {
-    ws();
-    comment();
-    if (i < n && !newline()) fail('expected the end of the line');
-  };
-  const hexChar = (len) => {
-    const h = src.slice(i, i + len);
-    if (h.length !== len || !/^[0-9A-Fa-f]+$/.test(h)) fail('bad escape');
-    i += len;
-    const cp = parseInt(h, 16);
-    if (cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff)) fail('bad escape');
-    return String.fromCodePoint(cp);
-  };
-  const escape = () => {
-    const e = src[i + 1];
-    i += 2;
-    switch (e) {
-      case 'b': return '\b';
-      case 't': return '\t';
-      case 'n': return '\n';
-      case 'f': return '\f';
-      case 'r': return '\r';
-      case 'e': return '\x1b';
-      case '"': return '"';
-      case '\\': return '\\';
-      case 'x': return hexChar(2);
-      case 'u': return hexChar(4);
-      case 'U': return hexChar(8);
-      default: return fail('bad escape');
-    }
-  };
-  const basicString = () => {
-    i += 1;
-    let s = '';
-    for (;;) {
-      if (i >= n) fail('unterminated string');
-      const ch = src[i];
-      if (ch === '"') return (i += 1), s;
-      if (ch === '\n' || ch === '\r') fail('newline in a string');
-      if (ch === '\\') s += escape();
-      else (s += ch), (i += 1);
-    }
-  };
-  const literalString = () => {
-    const end = src.indexOf("'", i + 1);
-    if (end < 0) fail('unterminated string');
-    const s = src.slice(i + 1, end);
-    if (/[\r\n]/.test(s)) fail('newline in a string');
-    i = end + 1;
-    return s;
-  };
-  const LINE_END_BACKSLASH = /\\[ \t]*\r?\n/y;
-  const multiline = (quote, escapes) => {
-    i += 3;
-    newline(); // a newline straight after the opening quotes is not content
-    let s = '';
-    for (;;) {
-      if (i >= n) fail('unterminated string');
-      if (src.startsWith(quote.repeat(3), i)) {
-        let q = 3;
-        while (q < 5 && src[i + q] === quote) q++; // up to two belong to the content
-        s += quote.repeat(q - 3);
-        i += q;
-        return s;
-      }
-      if (escapes && src[i] === '\\') {
-        LINE_END_BACKSLASH.lastIndex = i;
-        if (LINE_END_BACKSLASH.test(src)) {
-          i = LINE_END_BACKSLASH.lastIndex;
-          while (i < n && /[ \t\r\n]/.test(src[i])) i++;
-        } else s += escape();
-      } else (s += src[i]), (i += 1);
-    }
-  };
-  const key = () => {
-    const parts = [];
-    for (;;) {
-      ws();
-      if (src[i] === '"') {
-        if (src.startsWith('"""', i)) fail('a multi-line key');
-        parts.push(basicString());
-      } else if (src[i] === "'") {
-        if (src.startsWith("'''", i)) fail('a multi-line key');
-        parts.push(literalString());
-      } else {
-        BARE.lastIndex = i;
-        const m = BARE.exec(src);
-        if (!m) fail('expected a key');
-        parts.push(m[0]);
-        i = BARE.lastIndex;
-      }
-      ws();
-      if (src[i] !== '.') return parts;
-      i += 1;
-    }
-  };
-  const assign = (target, path, v) => {
-    let t = target;
-    for (const k of path.slice(0, -1)) {
-      if (!Object.hasOwn(t, k)) t[k] = newTable();
-      else if (!isTable(t[k])) fail(`"${k}" is not a table`);
-      t = t[k];
-    }
-    const last = path.at(-1);
-    if (Object.hasOwn(t, last)) fail(`"${last}" is defined twice`);
-    t[last] = v;
-  };
-  let depth = 0;
-  const nested = (open) => {
-    if (++depth > MAX_DEPTH) fail('nested too deep');
-    try {
-      return open();
-    } finally {
-      depth -= 1;
-    }
-  };
-  const array = () => {
-    i += 1;
-    const out = [];
-    for (;;) {
-      gap();
-      if (src[i] === ']') return (i += 1), out;
-      out.push(value());
-      gap();
-      if (src[i] === ',') i += 1;
-      else if (src[i] === ']') return (i += 1), out;
-      else fail('expected , or ]');
-    }
-  };
-  const inlineTable = () => {
-    i += 1;
-    const t = newTable();
-    for (;;) {
-      gap();
-      if (src[i] === '}') return (i += 1), t;
-      keyValue(t);
-      gap();
-      if (src[i] === ',') i += 1;
-      else if (src[i] === '}') return (i += 1), t;
-      else fail('expected , or }');
-    }
-  };
-  const word = (w) => src.startsWith(w, i) && !/[A-Za-z0-9_-]/.test(src[i + w.length] ?? '');
-  const value = () => {
-    const ch = src[i];
-    if (ch === '"') return src.startsWith('"""', i) ? multiline('"', true) : basicString();
-    if (ch === "'") return src.startsWith("'''", i) ? multiline("'", false) : literalString();
-    if (ch === '[') return nested(array);
-    if (ch === '{') return nested(inlineTable);
-    if (word('true')) return (i += 4), true;
-    if (word('false')) return (i += 5), false;
-    SCALAR.lastIndex = i;
-    const m = SCALAR.exec(src);
-    if (!m) fail('a value this reader does not know');
-    i = SCALAR.lastIndex;
-    if (/[A-Za-z0-9_.:+-]/.test(src[i] ?? '')) fail('a value this reader does not know');
-    return new TomlRaw(m[0]);
-  };
-  const keyValue = (target) => {
-    const path = key();
-    if (src[i] !== '=') fail('expected =');
-    i += 1;
-    ws();
-    assign(target, path, value());
-  };
-
-  const root = newTable();
-  let current = root;
-  for (;;) {
-    gap();
-    if (i >= n) return root;
-    if (src[i] !== '[') {
-      keyValue(current);
-      endOfLine();
-      continue;
-    }
-    const many = src[i + 1] === '[';
-    i += many ? 2 : 1;
-    const path = key();
-    if (many ? !src.startsWith(']]', i) : src[i] !== ']') fail('an unclosed table header');
-    i += many ? 2 : 1;
-    endOfLine();
-    let t = root;
-    for (const k of path.slice(0, -1)) {
-      if (!Object.hasOwn(t, k)) t[k] = newTable();
-      const v = Array.isArray(t[k]) ? t[k].at(-1) : t[k];
-      if (!isTable(v)) fail(`"${k}" is not a table`);
-      t = v;
-    }
-    const last = path.at(-1);
-    if (many) {
-      if (!Object.hasOwn(t, last)) t[last] = [];
-      if (!Array.isArray(t[last])) fail(`"${last}" is not an array of tables`);
-      current = newTable();
-      t[last].push(current);
-    } else {
-      if (!Object.hasOwn(t, last)) t[last] = newTable();
-      else if (!isTable(t[last])) fail(`"${last}" is not a table`);
-      current = t[last];
-    }
-  }
-}
 
 /**
  * The person's config.toml, where the turn's Codex would look —
@@ -374,17 +121,6 @@ export function readPersonalCodexConfig(env = process.env) {
   }
 }
 
-/** One value as TOML, as a `-c` override's value is parsed. */
-const bareKeyOr = (k) => (/^[A-Za-z0-9_-]+$/.test(k) ? k : toml(k));
-export function tomlValue(v) {
-  if (typeof v === 'string') return toml(v);
-  if (typeof v === 'boolean') return String(v);
-  if (v instanceof TomlRaw) return v.text;
-  if (Array.isArray(v)) return `[${v.map(tomlValue).join(',')}]`;
-  if (isTable(v)) return `{${Object.keys(v).map((k) => `${bareKeyOr(k)}=${tomlValue(v[k])}`).join(',')}}`;
-  throw new Error('not a TOML value');
-}
-
 const isString = (v) => typeof v === 'string';
 const isStringList = (v) => Array.isArray(v) && v.every(isString);
 const nonEmpty = (v) => typeof v === 'string' && v.trim() !== '';

package/bin/lib/codexProjectRead.mjs

@@ -6,16 +6,17 @@ import { execFileSync } from 'node:child_process';
 import { lstatSync, readdirSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, dirname } from 'node:path';
 import { git } from './git.mjs';
-import { codexResearchHelper } from './codexResearch.mjs';
+import { CODEX_HELPER_MIN, codexResearchHelper } from './codexResearch.mjs';
+import { versionAtLeast } from './versionOrder.mjs';
 import { unattendedEnv } from './noWindowEnv.mjs';
 
 export function projectReadBoundary({ cwd, knowledgeDir, env = process.env }) {
   if (process.platform !== 'linux') throw new Error('Project-scoped Codex reads require Linux or WSL.');
   if (!isAbsolute(cwd ?? '')) throw new Error('Project-scoped Codex reads require an absolute project directory.');
   const helper = codexResearchHelper(env);
-  const version = execFileSync(helper, ['--version'], { encoding: 'utf8', timeout: 10000, env: unattendedEnv(env) }).match(/^codex-cli (\d+)\.(\d+)\.(\d+)/);
-  if (!version || version.slice(1).map(Number).reduce((n, v) => n * 1000 + v, 0) < 159002)
-    throw new Error('Project-scoped reads need Codex CLI 0.159.2 or newer. Update Codex before retrying.');
+  const version = execFileSync(helper, ['--version'], { encoding: 'utf8', timeout: 10000, env: unattendedEnv(env) }).match(/^codex-cli (\d+\.\d+\.\d+)/);
+  if (!version || !versionAtLeast(version[1], CODEX_HELPER_MIN))
+    throw new Error(`Project-scoped reads need Codex CLI ${CODEX_HELPER_MIN} or newer. Update Codex before retrying.`);
   const project = realpathSync(cwd);
   // Resolve both: linked worktrees have their own HEAD/index and shared
   // objects/refs in the common directory. Never grant the parent checkout.