flowviant 0.116.0 → 0.124.0

package/bin/lib/runtimeLimits.mjs

@@ -40,12 +40,14 @@
  */
 
 import { readdir, open, stat } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { isoFromStamp } from './isoStamp.mjs';
 import { claudeAuthContext } from './claudeAuth.mjs';
 import { detectRuntimes } from './runtimeDetection.mjs';
-import { CODEX_THREAD_RE } from './workSessionRuntime.mjs';
+// Both from leaves (audit 2026-10-10, F126): this machine report sits on
+// runTurn's import path, below the work lanes, and imports none of them.
+import { CODEX_THREAD_RE } from './conversationIds.mjs';
+import { codexHome } from './codexHome.mjs';
 
 /** Claude's `utilization` is a fraction (0.03 = 3%) — MEASURED, see above. */
 export const CLAUDE_UTILIZATION_SCALE = 100;
@@ -254,7 +256,7 @@ export async function learnCodexLimits(threadId, { env = process.env, now } = {}
 export async function codexRolloutFile(threadId, { env = process.env } = {}) {
   try {
     if (typeof threadId !== 'string' || !CODEX_THREAD_RE.test(threadId)) return null;
-    const root = join(env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
+    const root = join(codexHome(env), 'sessions');
     const key = `${root}\0${threadId}`;
     let file = rolloutPaths.get(key) ?? null;
     if (file) {
@@ -294,9 +296,6 @@ export function claudePlanReading(now = Date.now()) {
   planMemo = { plan, readAt: now };
   return planMemo;
 }
-export function claudePlan() {
-  return claudePlanReading().plan;
-}
 
 const windowOrder = (a, b) =>
   (a.minutes ?? Infinity) - (b.minutes ?? Infinity) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);

package/bin/lib/runtimeOfferings.mjs

@@ -1,26 +1,37 @@
 /** Local, bounded Codex readouts. No agent turn is started for these reports. */
 import { execFileSync } from 'node:child_process';
-import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { accessSync, constants, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, delimiter, isAbsolute, join } from 'node:path';
 import { readBaseTools } from './projectTools.mjs';
 import { mcpRefusal } from './projectToolRuntimes.mjs';
+import { CODEX_MCP_NAME, normalizeMcpReport } from './runtimeCapabilities.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { codexHome } from './codexHome.mjs';
 
 const TTL = 5 * 60_000;
 let cachedAt = 0;
 let cached = null;
 let repoCached = null;
-const home = (env) => env.CODEX_HOME || join(homedir(), '.codex');
 const nameOk = (name) => typeof name === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(name) && name !== 'flowviant';
+// An unattended CLI child like any other (noWindowEnv.mjs, 2026-10-10): `codex
+// mcp list` may start the person's configured servers, and none of them is
+// handed the machine credential or a display.
 const run = (args, env) => execFileSync('codex', args, {
   encoding: 'utf8', timeout: 5000, maxBuffer: 128 * 1024,
-  stdio: ['ignore', 'pipe', 'ignore'], env,
+  stdio: ['ignore', 'pipe', 'ignore'], env: unattendedEnv(env),
 });
+/**
+ * THE `rtp.codex` REPORT, IN THE ONE SHAPE (runtimeCapabilities.mjs
+ * `normalizeMcpReport`, 2026-10-10): the server's charset, names clipped to
+ * its 60 rather than dropped past 80, sorted, at most its 40 — before, names
+ * of 61–80 characters and rows 41–80 were cut silently at the boundary.
+ */
+const codexMcpReport = (entries) => normalizeMcpReport(entries, { charset: CODEX_MCP_NAME });
 
 export function localCodexOfferings({ env = process.env, runCodex = run, read = readFileSync, list = readdirSync } = {}) {
   const result = {};
   try {
-    const cachePath = join(home(env), 'models_cache.json');
+    const cachePath = join(codexHome(env), 'models_cache.json');
     if (read === readFileSync && statSync(cachePath).size > 2 * 1024 * 1024) throw Error('model cache too large');
     const data = JSON.parse(read(cachePath, 'utf8'));
     if (Array.isArray(data.models)) result.models = data.models
@@ -35,27 +46,98 @@ export function localCodexOfferings({ env = process.env, runCodex = run, read =
     result.capabilities = lines.some((line) => /^image_generation\s+\S+\s+true\s*$/.test(line)) ? ['image'] : [];
   } catch { /* a failed local probe is unknown */ }
   try {
-    result.skills = list(join(home(env), 'skills'), { withFileTypes: true })
+    result.skills = list(join(codexHome(env), 'skills'), { withFileTypes: true })
       .filter((entry) => entry.isDirectory() && nameOk(entry.name))
       .map((entry) => entry.name).slice(0, 80);
   } catch (error) { if (error?.code === 'ENOENT') result.skills = []; }
   try {
     const servers = JSON.parse(runCodex(['mcp', 'list', '--json'], env));
-    if (Array.isArray(servers)) result.mcp = servers
+    if (Array.isArray(servers)) result.servers = codexServerRows(servers, env);
+    if (Array.isArray(servers)) result.mcp = codexMcpReport(servers
       // Unknown/unsupported auth is not proof of disconnection. Keep their
       // names local, just as connected servers stay local.
-      .filter((s) => nameOk(s?.name) && ['needs_auth', 'failed'].includes(s.auth_status))
-      .slice(0, 80)
-      .map((s) => ({ n: s.name, s: s.auth_status === 'needs_auth' ? 'needs-auth' : 'failed' }));
+      .filter((s) => typeof s?.name === 'string' && ['needs_auth', 'failed'].includes(s.auth_status))
+      .map((s) => ({ name: s.name, status: s.auth_status === 'needs_auth' ? 'needs-auth' : 'failed' })));
   } catch { /* no read is unknown */ }
   return result;
 }
 
-export function runtimeOfferings(repoRoot, baseRef, { refresh = false } = {}) {
+/** A bare command found on PATH, or an absolute one that is executable. */
+function commandFound(command, env) {
+  if (isAbsolute(command)) {
+    try { accessSync(command, constants.X_OK); return true; } catch { return false; }
+  }
+  if (command.includes('/')) return null; // relative to a cwd Codex picks: unknown
+  return (env.PATH ?? '').split(delimiter).some((dir) => {
+    try { accessSync(join(dir, command), constants.X_OK); return true; } catch { return false; }
+  });
+}
+
+/**
+ * EVERY SERVER IN THIS MACHINE'S CODEX CONFIG, AS `codex mcp list --json`
+ * NAMES IT (2026-10-13) — `[{ name, status, reason }]` for the box's MCP
+ * inventory (mcpInventory.mjs). Codex reports no connection state without
+ * starting a server, so a server it would start reads `configured`; what
+ * this daemon can tell cheaply is said instead: `disabled` (Codex's own
+ * `enabled = false`), `needs-auth` (its OAuth status says not logged in),
+ * `failed` with the reason when a stdio command is not found or an env
+ * variable it reads a token or header from is unset. MEASURED on codex-cli
+ * 0.159.2: entries carry `name`, `enabled`, `disabled_reason`, `transport`
+ * (`stdio` with `command`; `streamable_http` with `bearer_token_env_var` and
+ * `env_http_headers`) and `auth_status` (`unsupported` for both kinds). A
+ * reason names a command (its basename) or a variable, never a value, a path
+ * or a URL.
+ */
+export function codexServerRows(servers, env = process.env) {
+  const rows = [];
+  for (const s of servers) {
+    if (!s || typeof s.name !== 'string' || !nameOk(s.name)) continue;
+    const t = s.transport && typeof s.transport === 'object' ? s.transport : {};
+    const auth = typeof s.auth_status === 'string' ? s.auth_status : '';
+    let status = 'configured';
+    let reason = null;
+    const unset = [
+      ...(typeof t.bearer_token_env_var === 'string' ? [t.bearer_token_env_var] : []),
+      ...(t.env_http_headers && typeof t.env_http_headers === 'object' ? Object.values(t.env_http_headers).filter((v) => typeof v === 'string') : []),
+    ].filter((name) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !env[name]);
+    if (s.enabled === false) {
+      status = 'disabled';
+      reason = typeof s.disabled_reason === 'string' ? s.disabled_reason.slice(0, 200) : null;
+    } else if (typeof t.command === 'string' && commandFound(t.command, env) === false) {
+      status = 'failed';
+      reason = `command ${basename(t.command).slice(0, 60)} not found`;
+    } else if (unset.length) {
+      status = 'failed';
+      reason = `env ${[...new Set(unset)].sort().join(', ')} unset`;
+    } else if (['needs_auth', 'not_logged_in', 'notLoggedIn'].includes(auth)) {
+      status = 'needs-auth';
+    } else if (auth === 'failed') {
+      status = 'failed';
+    }
+    rows.push({ name: s.name, status, reason });
+  }
+  return rows;
+}
+
+function codexOfferings(refresh = false) {
   if (!cached || refresh || Date.now() - cachedAt >= TTL) {
     cached = localCodexOfferings();
     cachedAt = Date.now();
   }
+  return cached;
+}
+
+/** This machine's Codex servers for the inventory, or null when the local
+ *  read failed (unknown). Shares the offerings' five-minute cache. */
+export function codexMcpServers({ refresh = false } = {}) {
+  return codexOfferings(refresh).servers ?? null;
+}
+
+/** Existing model evidence only: a brief never probes another CLI or vendor. */
+export function knownCodexModels() { return cached?.models ?? []; }
+
+export function runtimeOfferings(repoRoot, baseRef, { refresh = false } = {}) {
+  codexOfferings(refresh);
   const out = { rtm: {}, rtc: {}, rts: {}, rtp: {} };
   if (cached.models) out.rtm.codex = cached.models;
   if (cached.capabilities) out.rtc.codex = cached.capabilities;
@@ -68,11 +150,14 @@ export function runtimeOfferings(repoRoot, baseRef, { refresh = false } = {}) {
     }
     const snapshot = repoCached.snapshot;
     if (out.rts.codex) out.rts.codex = [...new Set([...out.rts.codex, ...snapshot.skills.map((s) => s.path.split('/')[2])])].slice(0, 80);
-    if (out.rtp.codex) out.rtp.codex = [...new Map([...out.rtp.codex, ...snapshot.tools
+    // The repo's rows FIRST: a name both report reads as the repo's word, as
+    // the merge it replaced kept (its last write won).
+    if (out.rtp.codex) out.rtp.codex = codexMcpReport([...snapshot.tools
       // A repo server Codex refuses (projectToolRuntimes.mjs owns which) is
       // one this machine cannot connect for Codex, like a broken one.
       .filter((t) => t.state !== 'ready' || mcpRefusal('codex', t.config) != null)
-      .map((t) => ({ n: t.name, s: 'failed' }))].map((server) => [server.n, server])).values()].slice(0, 80);
+      .map((t) => ({ name: t.name, status: 'failed' })),
+    ...out.rtp.codex.map((r) => ({ name: r.n, status: r.s }))]);
   } catch { /* keep local measurements */ }
   return out;
 }

package/bin/lib/runtimes.mjs

@@ -101,6 +101,16 @@ export const RUNTIMES = {
  */
 export const runtimeById = (id) => (typeof id === 'string' && Object.hasOwn(RUNTIMES, id) ? RUNTIMES[id] : null);
 
+/**
+ * The name a sentence uses for a runtime id: its label when this daemon
+ * declares it, else the id as given — an unknown id is relayed, never renamed.
+ * Through `runtimeById`, so an id off the wire or a marker file that happens
+ * to name a prototype key (`constructor`, `__proto__`) reads as the unknown
+ * string it is (audit 2026-10-10, F125). Every lookup of a runtime by id goes
+ * through these two; the registry is subscripted nowhere else.
+ */
+export const runtimeLabel = (id) => runtimeById(id)?.label ?? String(id);
+
 /**
  * Can the worker this daemon is running actually DRIVE this runtime right now?
  *

package/bin/lib/shipSweep.mjs

@@ -1,4 +1,4 @@
-import { baseBranchName } from './git.mjs';
+import { baseBranchName, isSafePathSegment, sessionBranch } from './git.mjs';
 
 /**
  * RETIRE A BRANCH FLOWVIANT MADE AND FLOWVIANT MERGED.
@@ -40,10 +40,12 @@ import { baseBranchName } from './git.mjs';
  * nothing to clean on a remote.
  */
 export function sweepMergedBranch(sessionId, { git, repoRoot, baseRef, note, isReportPending }) {
-  if (!/^[A-Za-z0-9_-]{1,128}$/.test(String(sessionId ?? ''))) return false;
+  // The NAME is git.mjs's one definition, behind the same segment rule every
+  // place passes (audit 2026-10-10, F122) — not a second spelling of either.
+  if (!isSafePathSegment(sessionId)) return false;
   // The report has not landed. See ORDERING above.
   if (isReportPending?.(sessionId)) return false;
-  const name = `session/${sessionId}`;
+  const name = sessionBranch(sessionId);
   try {
     git(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`], repoRoot);
   } catch {

package/bin/lib/shot.mjs

@@ -20,12 +20,25 @@
  *   - A bare VM with no browser AND no system libs: probing/render fails →
  *     graceful text-evidence fallback with an `apt install chromium` hint.
  *   - FLOWVIANT_CHROME / CHROME_PATH override wins over all discovery.
+ *
+ * THE SANDBOX STAYS ON, AND CHROME NEVER HOLDS THE MACHINE CREDENTIAL
+ * (audit 2026-10-10, F081/F135). Every page this file opens is one somebody
+ * else wrote: a design artifact the model authored from a member's card, or
+ * the URL an agent passed to `flowviant shot`. `--no-sandbox` used to ride
+ * every launch "because root and some VMs need it", which turned any renderer
+ * bug into code execution as the operator. It is now passed only where it is
+ * needed: as root (Chrome refuses to start sandboxed there),
+ * `FLOWVIANT_CHROME_NO_SANDBOX=1` (the operator's own call for a box whose
+ * sandbox cannot start), or ONE retry after a launch whose own stderr says the
+ * sandbox could not start — a measured failure, never a guess. The browser's
+ * environment is the daemon's minus the machine credential (`machineEnv.mjs`).
  */
 
 import { spawn, execFileSync } from 'node:child_process';
 import { existsSync, statSync, readFileSync, mkdtempSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir, platform } from 'node:os';
+import { withoutMachineCredentials } from './machineEnv.mjs';
 
 // ── Browser discovery ───────────────────────────────────────────────────────
 
@@ -99,13 +112,51 @@ export function resolveBrowser() {
   return null;
 }
 
+// ── Launch policy ─────────────────────────────────────────────────────────
+
+/** The operator's opt-out for a box whose sandbox cannot start (a container
+ *  without user namespaces). Exactly '1'; anything else keeps it on. */
+export const NO_SANDBOX_ENV = 'FLOWVIANT_CHROME_NO_SANDBOX';
+
+/** Chrome's own words when its sandbox cannot start: the zygote's "No usable
+ *  sandbox!", the setuid helper's complaint, the root refusal, and a namespace
+ *  the kernel would not grant. Only a launch that FAILED is read for these. */
+export const SANDBOX_FAILURE_RE =
+  /No usable sandbox|SUID sandbox helper|without --no-sandbox|Failed to move to new namespace/i;
+
+/** True when Chrome must start without its sandbox before anything is
+ *  measured: as root (Chrome refuses to start sandboxed), or on the operator's
+ *  explicit `FLOWVIANT_CHROME_NO_SANDBOX=1`. */
+export function sandboxOff({ uid = process.getuid?.(), env = process.env } = {}) {
+  return uid === 0 || env?.[NO_SANDBOX_ENV] === '1';
+}
+
+/** The environment every Chrome this daemon starts runs in. */
+export const chromeEnv = (env = process.env) => withoutMachineCredentials(env);
+
+/** The flags every launch shares. `--no-sandbox` only when `noSandbox`. */
+export function chromeFlags({ headlessFlag, noSandbox, userDataDir, width, height }) {
+  return [
+    headlessFlag,
+    '--disable-gpu',
+    ...(noSandbox ? ['--no-sandbox'] : []),
+    '--disable-dev-shm-usage', // small /dev/shm in containers/VMs crashes Chrome otherwise
+    '--hide-scrollbars',
+    '--force-color-profile=srgb',
+    '--no-first-run',
+    '--disable-extensions',
+    `--user-data-dir=${userDataDir}`,
+    `--window-size=${width},${height}`,
+  ];
+}
+
 // ── Capture ─────────────────────────────────────────────────────────────────
 
 function toWinPath(p) {
   return execFileSync('wslpath', ['-w', p], { encoding: 'utf8' }).trim();
 }
 
-function runChrome(browser, { url, out, width, height, headlessFlag, timeoutMs }) {
+function runChrome(browser, { url, out, width, height, headlessFlag, timeoutMs, noSandbox }, { spawnImpl, env }) {
   return new Promise((resolve) => {
     const userDataDir = mkdtempSync(join(tmpdir(), 'flowviant-shot-'));
     const cleanup = () => { try { rmSync(userDataDir, { recursive: true, force: true }); } catch { /* best effort */ } };
@@ -124,14 +175,7 @@ function runChrome(browser, { url, out, width, height, headlessFlag, timeoutMs }
     }
 
     const args = [
-      headlessFlag,
-      '--disable-gpu',
-      '--no-sandbox',            // required as root / in many VMs + containers
-      '--disable-dev-shm-usage', // small /dev/shm in containers/VMs crashes Chrome otherwise
-      '--hide-scrollbars',
-      '--force-color-profile=srgb',
-      `--user-data-dir=${udArg}`,
-      `--window-size=${width},${height}`,
+      ...chromeFlags({ headlessFlag, noSandbox, userDataDir: udArg, width, height }),
       '--virtual-time-budget=5000', // let fonts/JS settle before capture (SPAs)
       `--screenshot=${outArg}`,
       url,
@@ -140,7 +184,7 @@ function runChrome(browser, { url, out, width, height, headlessFlag, timeoutMs }
     let err = '';
     let child;
     try {
-      child = spawn(browser.bin, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+      child = spawnImpl(browser.bin, args, { stdio: ['ignore', 'ignore', 'pipe'], env: chromeEnv(env) });
     } catch (e) {
       cleanup();
       return resolve({ ok: false, reason: 'spawn', message: e.message });
@@ -157,15 +201,34 @@ function runChrome(browser, { url, out, width, height, headlessFlag, timeoutMs }
       cleanup();
       if (existsSync(out) && statSync(out).size > 0) return resolve({ ok: true, path: out });
       const tail = err.trim().split('\n').slice(-2).join(' ');
-      resolve({ ok: false, reason: 'render', message: `Chrome exited (code ${code}) without an image.${tail ? ' ' + tail : ''}` });
+      resolve({
+        ok: false,
+        reason: 'render',
+        message: `Chrome exited (code ${code}) without an image.${tail ? ' ' + tail : ''}`,
+        sandboxFailed: !noSandbox && SANDBOX_FAILURE_RE.test(err),
+      });
     });
   });
 }
 
 /** Capture `url` to a PNG at `out`. Tries new headless, then classic headless
- *  (older Chromium). Resolves { ok, path } or { ok:false, reason, message }. */
-export async function captureScreenshot({ url, out, width = 1440, height = 900, timeoutMs = 60_000 }) {
-  const browser = resolveBrowser();
+ *  (older Chromium), sandboxed unless `sandboxOff` — and at most ONE launch
+ *  without it, after a sandboxed launch that said its sandbox could not start.
+ *  Resolves { ok, path } or { ok:false, reason, message }.
+ *
+ *  `browser`, `spawn`, `uid` and `env` are injectable so the launch policy is
+ *  provable without a browser; nothing in the daemon passes them. */
+export async function captureScreenshot({
+  url,
+  out,
+  width = 1440,
+  height = 900,
+  timeoutMs = 60_000,
+  browser = resolveBrowser(),
+  spawn: spawnImpl = spawn,
+  uid = process.getuid?.(),
+  env = process.env,
+}) {
   if (!browser) {
     return {
       ok: false,
@@ -173,12 +236,23 @@ export async function captureScreenshot({ url, out, width = 1440, height = 900,
       message: 'No Chrome/Chromium/Edge found. Install one (Linux: `sudo apt install chromium`) to capture screenshot evidence.',
     };
   }
-  let r = await runChrome(browser, { url, out, width, height, headlessFlag: '--headless=new', timeoutMs });
+  let noSandbox = sandboxOff({ uid, env });
+  const attempt = async (headlessFlag) => {
+    const run = () => runChrome(browser, { url, out, width, height, headlessFlag, timeoutMs, noSandbox }, { spawnImpl, env });
+    let r = await run();
+    if (!r.ok && r.sandboxFailed) {
+      noSandbox = true; // sticky: the one retry this capture gets
+      r = await run();
+    }
+    return r;
+  };
+  let r = await attempt('--headless=new');
   if (!r.ok && r.reason === 'render') {
     // Older Chromium rejects `--headless=new` — retry with classic headless.
-    r = await runChrome(browser, { url, out, width, height, headlessFlag: '--headless', timeoutMs });
+    r = await attempt('--headless');
   }
-  return r;
+  const { sandboxFailed: _measured, ...result } = r;
+  return result;
 }
 
 // ── CLI ───────────────────────────────────────────────────────────────────

package/bin/lib/sleep.mjs

@@ -0,0 +1,11 @@
+/**
+ * WAIT N SECONDS — a leaf with no imports (2026-10-10, the audit).
+ *
+ * It lived in claude.mjs, the module that hands a coding CLI its MCP server,
+ * which imports the runtime registry (runtimes.mjs) and through it every
+ * vendor's adapter. So `flowviant login`, the one command that has to work on
+ * a fresh box, loaded every runtime module just to wait between two polls, and
+ * a fault importing any of them could break it. login.mjs, fleet.mjs and
+ * holder.mjs import it from here; nothing here may import anything.
+ */
+export const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));

package/bin/lib/startProject.mjs

@@ -17,18 +17,18 @@
  */
 import { FLEET_TOKEN, CREDENTIAL, adoptStoredCredential } from './config.mjs';
 import { runLogin } from './login.mjs';
-import { terminalCommand } from './launchCommand.mjs';
+import { relaunchSelf, selfArgv, terminalCommand } from './launchCommand.mjs';
 import { canPrompt, askWithTimeout, selectMenu, menuSupported } from './tty.mjs';
 
 /** Re-exec a plain `flowviant` after an inline login — the login command's own
  *  pattern: config.mjs read the store at IMPORT time, before the credential
- *  existed, so this process cannot serve; the child can. */
+ *  existed, so this process cannot serve; the child can. Through the one
+ *  relaunch proxy (launchCommand.mjs), which passes signals on and reads a
+ *  child killed by one as a failure. */
 async function reexecAfterLogin() {
   const login = await runLogin({ thenStart: false });
   if (!login?.saved) process.exit(1); // refused: the directory already serves another project
-  const { spawn } = await import('node:child_process');
-  const child = spawn(process.execPath, process.argv[1]?.startsWith('/$bunfs/') ? [] : [process.argv[1]], { stdio: 'inherit', env: process.env });
-  process.exit(await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0))));
+  await relaunchSelf({ argv: selfArgv(), env: process.env });
 }
 
 // TWO ROWS THAT READ ALIKE ARE NOT A CHOICE. `projectRowLabel` adds the id and

package/bin/lib/statePaths.mjs

@@ -0,0 +1,40 @@
+/**
+ * WHERE THE DAEMON KEEPS A CHECKOUT'S WORKTREES — one derivation (audit
+ * 2026-10-10, F075).
+ *
+ * The per-checkout worktree home, `~/.flowviant/worktrees/<basename>-<8 hex
+ * of sha256(repoRoot)>`, was written twice — fleetStartup.worktreeHome and
+ * deployCheckout's fallback — and its parent a third time in `flowviant
+ * clean`. Two copies of a key can drift silently, and a drift here is a
+ * deploy checkout landing somewhere the startup reap and the machine's disk
+ * line never look, while `clean` still sweeps the parent. So every reader
+ * asks this leaf.
+ *
+ * A LEAF: node built-ins only, so a command that must stay light (`clean`)
+ * can import it without the daemon's config. Nothing here makes a directory —
+ * the caller that needs one (worktreeHome) makes it. `homedir()` is read AT
+ * CALL TIME, so a test (or anything else) that sets HOME after import is
+ * heard.
+ *
+ * THE KEY IS NOT TO BE CHANGED casually: a different key strands every
+ * persisted worktree and deploy scratch under the old one, outside the reap.
+ */
+
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+/** `~/.flowviant/worktrees` — the parent of every checkout's worktree home. */
+export function worktreesRoot() {
+  return join(homedir(), '.flowviant', 'worktrees');
+}
+
+/** `<basename>-<first 8 hex of sha256(repoRoot)>` — the checkout's key. */
+export function worktreeHomeKey(repoRoot) {
+  return `${basename(repoRoot)}-${createHash('sha256').update(repoRoot).digest('hex').slice(0, 8)}`;
+}
+
+/** The checkout's worktree home, NOT created. */
+export function worktreeHomeDir(repoRoot) {
+  return join(worktreesRoot(), worktreeHomeKey(repoRoot));
+}

package/bin/lib/tty.mjs

@@ -44,16 +44,20 @@
  * they are what keeps a backgrounded job from freezing.
  */
 
-import { readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
+import { procStat } from './procStat.mjs';
 
 /**
- * Is this process in the controlling terminal's foreground process group?
+ * WHERE THIS PROCESS STANDS ON ITS TERMINAL: `true` measured in the
+ * controlling terminal's foreground process group, `false` measured in the
+ * background, `null` when there is no controlling terminal or it could not be
+ * read. `inForeground` folds the two non-answers into "foreground"; the
+ * relaunch proxy (launchCommand.mjs) needs them apart.
  *
  * Linux: BOTH numbers come out of one `/proc/self/stat` read — field 5 is our
  * own `pgrp` and field 8 is `tpgid`, the foreground group of our controlling
- * terminal. Parsed from AFTER the last ')' because field 2 is the executable
- * name and may itself contain spaces and parentheses.
+ * terminal — through procStat.mjs, because field 2 is the executable name and
+ * may itself contain spaces and parentheses.
  *
  * NOT `process.getpgrp()`: it DOES NOT EXIST in Node (verified on 24.16 — it
  * throws `TypeError: process.getpgrp is not a function`). The first cut of this
@@ -64,18 +68,15 @@ import { execFileSync } from 'node:child_process';
  * isolation on a real pty; nothing else would have shown it, because the
  * fallback it degraded to still behaves acceptably.
  *
- * Elsewhere: ask `ps` for both. Unknown: assume foreground (see the header).
+ * Elsewhere: ask `ps` for both.
  */
-export function inForeground() {
+export function terminalForeground() {
   try {
     if (process.platform === 'linux') {
-      const stat = readFileSync('/proc/self/stat', 'utf8');
-      const after = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
-      const pgrp = Number(after[2]); // state ppid PGRP session tty_nr tpgid
-      const tpgid = Number(after[5]);
-      if (!Number.isFinite(tpgid) || !Number.isFinite(pgrp)) return true;
-      if (tpgid <= 0) return true; // no controlling terminal — nothing to be behind
-      return tpgid === pgrp;
+      const stat = procStat('self');
+      if (!stat) return null;
+      if (stat.tpgid <= 0) return null; // no controlling terminal — nothing to be behind
+      return stat.tpgid === stat.pgrp;
     }
     const out = execFileSync('ps', ['-o', 'tpgid=,pgid=', '-p', String(process.pid)], {
       encoding: 'utf8',
@@ -84,13 +85,22 @@ export function inForeground() {
     }).trim().split(/\s+/);
     const tpgid = Number(out[0]);
     const pgrp = Number(out[1]);
-    if (!Number.isFinite(tpgid) || !Number.isFinite(pgrp) || tpgid <= 0) return true;
+    if (!Number.isFinite(tpgid) || !Number.isFinite(pgrp) || tpgid <= 0) return null;
     return tpgid === pgrp;
   } catch {
-    return true;
+    return null;
   }
 }
 
+/**
+ * Is this process in the controlling terminal's foreground process group?
+ * No controlling terminal has nothing to be behind, and unknown assumes
+ * foreground (see the header): only a MEASURED background answers false.
+ */
+export function inForeground() {
+  return terminalForeground() !== false;
+}
+
 /** A human is at this terminal AND can actually be reached by a question. */
 export function canPrompt() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY) && inForeground();

package/bin/lib/turnDiagnostics.mjs

@@ -0,0 +1,93 @@
+/** Local, correlated CLI lifecycle evidence. No prompts, answers, argv, token
+ * values or token fingerprints are logged. Credential metadata is remeasured
+ * at close so a refresh/rotation can be distinguished from a stale environment.
+ * Logging is best effort and rides the daemon's existing bounded private log.
+ */
+import { randomUUID } from 'node:crypto';
+import { accessSync, constants, readFileSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, isAbsolute, resolve } from 'node:path';
+import { AUTH_ENV_VARS, claudeAuthContext, claudeCredentialPath } from './claudeAuth.mjs';
+import { scrub } from './uplinkScrub.mjs';
+import { printableText } from './printable.mjs';
+import { measuredRuntimeVersion } from './runtimeDetection.mjs';
+
+let active = 0;
+const authNames = (env) => AUTH_ENV_VARS.filter((name) =>
+  typeof env[name] === 'string' && env[name].trim() !== '');
+function executableFor(bin, env, cwd) {
+  const candidates = isAbsolute(bin) || bin.includes('/')
+    ? [resolve(cwd, bin)]
+    : (env.PATH ?? '').split(delimiter).map((dir) => resolve(cwd, dir, bin));
+  for (const candidate of candidates) {
+    try { accessSync(candidate, constants.X_OK); return realpathSync(candidate); } catch { /* next */ }
+  }
+  return null;
+}
+function authFor(env) {
+  const context = claudeAuthContext({ env });
+  const credentialPath = claudeCredentialPath(env);
+  let file = null;
+  try {
+    const stat = statSync(credentialPath);
+    file = { modifiedAt: new Date(stat.mtimeMs).toISOString(), inode: stat.ino };
+  } catch { /* absent or keychain: unknown */ }
+  return { ...context, configDir: env.CLAUDE_CONFIG_DIR || null, credentialPath, file };
+}
+
+export function startTurnDiagnostics(options) {
+  try { return createTurnDiagnostics(options); }
+  catch { return () => {}; }
+}
+
+function createTurnDiagnostics({ runtime, bin, env, cwd = process.cwd(), profile,
+  planId = null, args = [], version, write = (row) => console.info(`[cli-turn] ${JSON.stringify(row)}`) }) {
+  const startedAt = Date.now();
+  const turnId = randomUUID();
+  const executable = executableFor(bin, env, cwd);
+  let settingsEnv = {};
+  if (runtime === 'claude') {
+    const at = args.indexOf('--settings');
+    if (at >= 0) {
+      try {
+        const input = args[at + 1];
+        const settings = JSON.parse(input.startsWith('{') ? input : readFileSync(input, 'utf8'));
+        if (settings.env && typeof settings.env === 'object' && !Array.isArray(settings.env)) {
+          for (const [key, value] of Object.entries(settings.env))
+            if (typeof value === 'string') settingsEnv[key] = value;
+        }
+      } catch { /* CLI settings unavailable */ }
+    }
+  }
+  const base = { turnId, runtime, profile, planId, cwd, daemonPid: process.pid,
+    uid: process.getuid?.() ?? null, platform: process.platform,
+    nodeVersion: process.version, executable, version: version ?? null,
+    runtimeMeasurement: measuredRuntimeVersion(runtime) };
+  const auth = () => {
+    try {
+      return runtime === 'claude' ? { ...authFor({ ...env, ...settingsEnv }),
+        inheritedAuthVars: authNames(env),
+        settingsAuthVars: authNames(settingsEnv) } : null;
+    } catch { return null; }
+  };
+  const emit = (row) => {
+    try {
+      // Scrub strings even in the allowlisted metadata: paths/user names are
+      // operator supplied. No environment object or error body reaches here.
+      write(JSON.parse(scrub(printableText(JSON.stringify(row)))));
+    } catch { /* diagnostics never fail a turn */ }
+  };
+  active++;
+  emit({ ...base, phase: 'start', at: new Date(startedAt).toISOString(), activeTurns: active, auth: auth() });
+  let finished = false;
+  return ({ code = null, signal = null, pid = null, output = '', spawnError = null, cliFailed = false } = {}) => {
+    if (finished) return;
+    finished = true;
+    active--;
+    const failed = cliFailed || (code !== null && code !== 0);
+    emit({ ...base, phase: 'end', at: new Date().toISOString(), durationMs: Date.now() - startedAt,
+      pid, code, signal, spawnError, activeTurns: active, auth: auth(),
+      failureKind: failed && /OAuth session expired and could not be refreshed/i.test(output)
+        ? 'oauth_refresh' : failed && /Failed to authenticate/i.test(output) ? 'authentication'
+          : spawnError ? 'spawn' : code !== null && code !== 0 ? 'cli_exit' : null });
+  };
+}