flowviant 0.116.0 → 0.117.0

package/bin/lib/artifactPreview.mjs

@@ -9,35 +9,108 @@
  * that never launches a browser.
  *
  * It renders the SCRUBBED bytes, never the checkout's source, under the
- * artifact box's own network fence (`PREVIEW_CSP`) placed before any
- * model-written markup executes. A failed measurement is explicit
- * (`renderState: 'unavailable'`); a daemon older than this simply sends no
- * `renderState`, which the server reads as unmeasured.
+ * artifact box's own network fence (`PREVIEW_CSP`). A failed measurement is
+ * explicit (`renderState: 'unavailable'`); a daemon older than this simply
+ * sends no `renderState`, which the server reads as unmeasured.
+ *
+ * MODEL-WRITTEN HTML IS NEVER A TOP-LEVEL `file://` DOCUMENT (audit
+ * 2026-10-10, F657/F756). It used to be: the bytes went to a temp file and
+ * Chrome opened that file, and a file page may navigate to any other file —
+ * so a meta refresh to `~/.flowviant/credentials.json` turned the uploaded
+ * PNG into a picture of every machine credential on the box. The page is now
+ * served once, over loopback http, from a listener on 127.0.0.1 at a random
+ * port and an unguessable path, with the fence as a response header (Chrome
+ * refuses an http page's navigation to `file://`), and the capture
+ * (`pinnedCapture.mjs`) refuses every navigation away from that URL. A render
+ * whose final document is not the served page is 'unavailable', and no
+ * preview is uploaded. The listener closes when the capture is done.
+ *
+ * `PREVIEW_CSP` is the served `ARTIFACT_CSP_BASE` (apps/api
+ * artifactDelivery.ts) minus `navigate-to` and `webrtc`, which Chrome does
+ * not enforce, so the thumbnail renders what the app renders:
+ * the same sandbox, and blob workers (`worker-src blob:`, added 2026-10-10 —
+ * a three.js/DRACO page rendered blank here and whole in the app). Exported
+ * for the release parity gate.
  */
 
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { pathToFileURL } from 'node:url';
-import { captureScreenshot } from './shot.mjs';
+import { capturePinnedPage } from './pinnedCapture.mjs';
 
 export const DESIGN_PREVIEW_MAX_BYTES = 2 * 1024 * 1024;
-const PREVIEW_CSP = "default-src 'none'; script-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com; style-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com https://fonts.googleapis.com; img-src data: blob:; font-src data: https://fonts.gstatic.com; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+export const PREVIEW_CSP = "sandbox allow-scripts; default-src 'none'; script-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com; style-src 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/npm/ https://unpkg.com https://fonts.googleapis.com; img-src data: blob:; font-src data: https://fonts.gstatic.com; connect-src 'none'; worker-src blob:; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+
+/** The https sources PREVIEW_CSP names — the only hosts a subresource of the
+ *  page may come from, read from the policy so the two cannot drift. */
+const CSP_SOURCES = [...new Set(PREVIEW_CSP.match(/https:\/\/[^\s;]+/g) ?? [])].map((s) => new URL(s));
+
+/** CSP host-source matching for the sources above: the same host over https,
+ *  and a path ending in `/` is a prefix while any other path is exact. */
+export function previewSubresourceAllowed(raw) {
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== 'https:') return false;
+  return CSP_SOURCES.some((s) =>
+    s.host === u.host &&
+    (s.pathname === '/' || (s.pathname.endsWith('/') ? u.pathname.startsWith(s.pathname) : u.pathname === s.pathname)));
+}
+
+/** Serve `bytes` at one random path on 127.0.0.1, with the fence as a
+ *  header. Resolves `{ url, close }`. */
+function servePage(bytes) {
+  const path = `/${randomBytes(16).toString('hex')}.html`;
+  const server = createServer((req, res) => {
+    if ((req.method === 'GET' || req.method === 'HEAD') && req.url === path) {
+      res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Security-Policy': PREVIEW_CSP,
+        'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff',
+      });
+      res.end(req.method === 'HEAD' ? undefined : bytes);
+      return;
+    }
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end();
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolve({
+        url: `http://127.0.0.1:${port}${path}`,
+        close: () => {
+          server.closeAllConnections?.();
+          server.close();
+        },
+      });
+    });
+  });
+}
 
 /** Render the scrubbed HTML, never the checkout's unsanitized source. A
- * failed browser measurement is explicit; older daemon reports are absent. */
-export async function renderDesignPreview(bytes, capture = captureScreenshot) {
+ *  failed browser measurement is explicit; older daemon reports are absent. */
+export async function renderDesignPreview(bytes, capture = capturePinnedPage) {
   const dir = mkdtempSync(join(tmpdir(), 'flowviant-design-'));
+  let page = null;
   try {
-    const html = join(dir, 'design.html');
     const png = join(dir, 'design.png');
-    // A fresh Chrome profile has no Flowviant credentials. Put the artifact
-    // box's network fence before any model-written markup executes.
-    writeFileSync(html, Buffer.concat([
-      Buffer.from(`<meta http-equiv="Content-Security-Policy" content="${PREVIEW_CSP}">`),
-      bytes,
-    ]));
-    const result = await capture({ url: pathToFileURL(html).href, out: png, width: 720, height: 450, timeoutMs: 15_000 });
+    page = await servePage(bytes);
+    const result = await capture({
+      url: page.url,
+      out: png,
+      width: 720,
+      height: 450,
+      timeoutMs: 15_000,
+      allowSubresource: previewSubresourceAllowed,
+    });
     if (!result.ok) return { renderState: 'unavailable' };
     const image = readFileSync(png);
     if (image.byteLength > DESIGN_PREVIEW_MAX_BYTES || !image.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) {
@@ -47,6 +120,7 @@ export async function renderDesignPreview(bytes, capture = captureScreenshot) {
   } catch {
     return { renderState: 'unavailable' };
   } finally {
+    page?.close();
     rmSync(dir, { recursive: true, force: true });
   }
 }

package/bin/lib/artifactReporter.mjs

@@ -12,10 +12,16 @@
  *
  * ── DELIVERY ──
  *
- * A 2xx is delivered. A 4xx (other than 408/429) is TREATED AS DELIVERED — an
- * older SERVER 404s the whole route, and holding bodies it will refuse forever
- * would be the trace relay's wedge wearing a retry's clothes; a refusal of one
- * file (ended session, wrong owner) is equally permanent. A 5xx, 408, 429 or a
+ * A 2xx is delivered. A considered 4xx (fleetWire.mjs's `isConsideredRefusal`:
+ * other than 408/429) is TREATED AS DELIVERED — an older SERVER 404s the whole
+ * route, and holding bodies it will refuse forever would be the trace relay's
+ * wedge wearing a retry's clothes; a refusal of one file (ended session, wrong
+ * owner) is equally permanent. EXCEPT 401 AND 403, which are a "later"
+ * (2026-10-10 ruling, audit F071): a credential blip — a rotation, a box that
+ * is momentarily not the holder — or an edge 403 (Cloudflare's WAF on a large
+ * HTML mockup, authReject.mjs's whole subject) says nothing about this BODY,
+ * and settling on one lost the artifact for good. The same argument as
+ * fleetReports.mjs's `envReportIsPermanent`. A 5xx, 408, 429, 401, 403 or a
  * network error keeps the STORED BODY — the fields and the bytes as they were
  * scrubbed — and retries it on the next report beat, the settle's shape, at
  * most `MAX_TRIES` times; a newer copy of the same file replaces a held one.
@@ -24,7 +30,7 @@
  * `renderState: 'unavailable'` and no preview, the renderer's explicit answer.
  */
 
-import { fleetEndpoint } from './fleetWire.mjs';
+import { fleetEndpoint, isConsideredRefusal } from './fleetWire.mjs';
 
 /** A held upload is tried this many times in all, then dropped with a line. */
 const MAX_TRIES = 4;
@@ -65,9 +71,11 @@ export function createArtifactReporter({
         signal: AbortSignal.timeout(30_000),
         body: form,
       });
-      return (
-        res.ok || (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429)
-      );
+      if (res.ok) return true;
+      // A credential blip or an edge page is a "later", bounded by MAX_TRIES
+      // (2026-10-10 ruling — see the header).
+      if (res.status === 401 || res.status === 403) return false;
+      return isConsideredRefusal(res.status);
     } catch {
       return false;
     }

package/bin/lib/artifacts.mjs

@@ -78,6 +78,7 @@ import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readdi
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { cutKeepingExtension } from './safeFileName.mjs';
+import { ensureRealSubdir, flowviantParentState, realDirState } from './ownedDirs.mjs';
 import {
   ARTIFACT_BINARY_MODEL_EXTS,
   ARTIFACT_BINARY_MODEL_MAX_BYTES,
@@ -119,23 +120,9 @@ export const ARTIFACT_MAX_FILES = ARTIFACT_MAX_PER_OWNER;
  * refuses the turn in words.
  */
 export function ensureArtifactDir(placeDir) {
-  const parent = join(placeDir, '.flowviant');
-  const dir = join(placeDir, ARTIFACT_DIR);
-  const real = (p) => {
-    try {
-      const st = lstatSync(p);
-      return st.isDirectory() && !st.isSymbolicLink() ? true : false;
-    } catch (e) {
-      return e?.code === 'ENOENT' ? null : false;
-    }
-  };
-  if (real(parent) === false || real(dir) === false) return false;
-  try {
-    mkdirSync(dir, { recursive: true });
-  } catch {
-    return false;
-  }
-  return real(parent) === true && real(dir) === true;
+  // The rule's one home since 2026-10-10 (ownedDirs.mjs, the audit's F100):
+  // refused, never replaced, and both components checked again after the make.
+  return ensureRealSubdir(placeDir, ARTIFACT_DIR);
 }
 
 /**
@@ -159,25 +146,16 @@ export function ensureArtifactDir(placeDir) {
  */
 export const FENCE_TMP_DIR = '.flowviant/tmp';
 export function ensureFenceScratch(placeDir) {
-  const parent = join(placeDir, '.flowviant');
   const dir = join(placeDir, FENCE_TMP_DIR);
-  const kind = (p) => {
-    try {
-      const st = lstatSync(p);
-      return st.isDirectory() && !st.isSymbolicLink() ? 'dir' : 'other';
-    } catch (e) {
-      return e?.code === 'ENOENT' ? 'none' : 'other';
-    }
-  };
-  if (kind(parent) !== 'dir' || kind(dir) === 'other') return false;
+  if (flowviantParentState(placeDir) !== 'dir' || realDirState(dir) === 'other') return false;
   try {
     // A real directory (checked above): its contents go, never through a link.
-    if (kind(dir) === 'dir') rmSync(dir, { recursive: true, force: true });
+    if (realDirState(dir) === 'dir') rmSync(dir, { recursive: true, force: true });
     mkdirSync(dir);
   } catch {
     return false;
   }
-  return kind(parent) === 'dir' && kind(dir) === 'dir';
+  return flowviantParentState(placeDir) === 'dir' && realDirState(dir) === 'dir';
 }
 
 export function artifactTypeFor(name) {
@@ -187,46 +165,72 @@ export function artifactTypeFor(name) {
 }
 
 /**
- * The directory's regular files, newest first, at most `ARTIFACT_MAX_FILES`.
- * `[]` for a directory that does not exist, is not a directory, or is a
- * symlink — nothing to report is the only honest reading of any of those.
+ * HOW DEEP A BUNDLE GOES: files are listed to depth four (a path of up to five
+ * components), so a directory found AT depth four is never looked inside.
  */
-export function scanArtifacts(placeDir) {
+export const ARTIFACT_MAX_DEPTH = 4;
+
+/**
+ * THE ONE WALK OF THE ARTIFACTS DIRECTORY (2026-10-10, the audit's F067) —
+ * what the scan lists and what the check's fence keeps are read off the same
+ * entries, so the two cannot disagree about what an artifact is again. They
+ * did: the scan learned folders in 0.99.0 (a bundle's sidecars, the 3D-model
+ * page's `<name>/index.html`) and the fence went on removing every
+ * subdirectory whole, so a model agent whose repo declared a check lost its
+ * page the moment its queue emptied — and a send-back turn that did not
+ * rewrite it settled "nothing".
+ *
+ * `visit({ name, path, kind, st })` is called for every entry, depth first.
+ * `name` is the relative path; `kind` is one of:
+ *   'dir'    — a real directory within depth: walked next
+ *   'file'   — a regular file (any type: the allowlist is each caller's)
+ *   'hidden' — a dot-name, whatever it is; never looked at further
+ *   'deep'   — a real directory past the depth: nothing in it is ever listed
+ *   'other'  — a symlink, a fifo, a socket, a device: never followed or read
+ *
+ * `lstat` and never followed, and BOTH components checked first — `lstat` on
+ * `.flowviant/artifacts` refuses a symlink AT that name, but it resolves
+ * THROUGH a symlinked `.flowviant`, and git commits symlinks: a cloned repo
+ * carrying `.flowviant -> /some/dir` once had the scan listing, reading and
+ * uploading `/some/dir/artifacts/*` (2026-09-23). False, having visited
+ * nothing, when either is not a real directory.
+ */
+export function walkArtifactDir(placeDir, visit) {
   const dir = join(placeDir, ARTIFACT_DIR);
-  /**
-   * BOTH components are checked, not only the last (2026-09-23). `lstat` on
-   * `.flowviant/artifacts` refuses a symlink AT that name, but it resolves
-   * THROUGH a symlinked `.flowviant` — and git commits symlinks, so a cloned
-   * repo carrying `.flowviant -> /some/dir` would have had this scan listing,
-   * reading and uploading `/some/dir/artifacts/*`, a directory outside the
-   * place the turn stood in. The knowledge sync already refuses a `.flowviant`
-   * that is not a real directory (`flowviantDirOk`); this is the same check on
-   * the read side.
-   */
-  try {
-    const parent = lstatSync(join(placeDir, '.flowviant'));
-    if (parent.isSymbolicLink() || !parent.isDirectory()) return [];
-    if (!lstatSync(dir).isDirectory()) return [];
-  } catch {
-    return [];
-  }
-  const out = [];
-  const walk = (at, prefix = '', depth = 0) => {
-    if (depth > 4) return;
+  if (flowviantParentState(placeDir) !== 'dir' || realDirState(dir) !== 'dir') return false;
+  const walk = (at, prefix, depth) => {
     let names;
     try { names = readdirSync(at); } catch { return; }
     for (const part of names) {
-      if (part.startsWith('.')) continue;
       const name = prefix ? `${prefix}/${part}` : part;
       const path = join(at, part);
-      try {
-        const st = lstatSync(path);
-        if (st.isDirectory() && !st.isSymbolicLink()) walk(path, name, depth + 1);
-        else if (st.isFile() && !st.isSymbolicLink()) out.push({ name, path, size: st.size, mtimeMs: st.mtimeMs });
-      } catch { /* vanished */ }
+      let st = null;
+      let kind = 'hidden';
+      if (!part.startsWith('.')) {
+        try { st = lstatSync(path); } catch { continue; /* vanished */ }
+        kind = st.isSymbolicLink() ? 'other'
+          : st.isDirectory() ? (depth < ARTIFACT_MAX_DEPTH ? 'dir' : 'deep')
+          : st.isFile() ? 'file'
+          : 'other';
+      }
+      visit({ name, path, kind, st });
+      if (kind === 'dir') walk(path, name, depth + 1);
     }
   };
-  walk(dir);
+  walk(dir, '', 0);
+  return true;
+}
+
+/**
+ * The directory's regular files, newest first, at most `ARTIFACT_MAX_FILES`.
+ * `[]` for a directory that does not exist, is not a directory, or is a
+ * symlink — nothing to report is the only honest reading of any of those.
+ */
+export function scanArtifacts(placeDir) {
+  const out = [];
+  walkArtifactDir(placeDir, ({ name, path, kind, st }) => {
+    if (kind === 'file') out.push({ name, path, size: st.size, mtimeMs: st.mtimeMs });
+  });
   out.sort((a, b) => b.mtimeMs - a.mtimeMs || a.name.localeCompare(b.name));
   return out.slice(0, ARTIFACT_MAX_FILES);
 }

package/bin/lib/authproxy.mjs

@@ -230,7 +230,8 @@ export function startAuthProxy({
       return;
     }
     // 4. The grant is a cookie, and a cookie can be ridden (header rule 4a's
-    // backstop). Never a bounce — the caller HAS a credential; the request
+    // backstop) — and so can a cached Basic password, by a cross-site write
+    // (2026-10-10). Never a bounce — the caller HAS a credential; the request
     // SHAPE is what is refused.
     if (verdict === 'cross-site') {
       res.writeHead(403, { 'Content-Type': 'text/plain', ...noStore });

package/bin/lib/childEnv.mjs

@@ -28,6 +28,9 @@
  * surface may describe anything here as "sandboxed" or "isolated".
  */
 import { MACHINE_CREDENTIAL_ENV } from './machineEnv.mjs';
+// The variables that can carry Claude's auth in from the environment — the
+// one list claudeAuth.mjs reads presence from (2026-10-10, the audit's F073).
+import { AUTH_ENV_VARS } from './claudeAuth.mjs';
 
 /**
  * The complete kept set. Two groups, and both are here for a reason that bit
@@ -203,7 +206,8 @@ export const DEPLOY_KEEP_NAMES = [...DEPLOY_KEEP];
  * other half. Deriving it FROM that array is what makes forgetting impossible,
  * and it is why the merge happens inside `learnSecrets` rather than at a
  * call site somebody has to remember. The dependency direction is the only one
- * that is acyclic besides: this module imports nothing at all.
+ * that is acyclic besides: this module imports only two leaves (the name lists
+ * in machineEnv.mjs and claudeAuth.mjs), neither of which imports back.
  *
  * TWO NAMES ARE HERE THAT ARE NOT IN `DEPLOY_KEEP`, and the asymmetry is the
  * point. `CF_API_TOKEN` and `CF_ACCOUNT_ID` are wrangler's older spellings — it
@@ -249,9 +253,10 @@ const REDACT_ONLY = [
   // of (machineEnv.mjs): a name removed from children is redacted by
   // construction, never by a second hand-kept copy.
   ...MACHINE_CREDENTIAL_ENV,
-  'ANTHROPIC_API_KEY',
-  'ANTHROPIC_AUTH_TOKEN',
-  'CLAUDE_CODE_OAUTH_TOKEN',
+  // Every Claude auth variable, from the list claudeAuth.mjs reports presence
+  // from — derived, not re-listed, for the same reason as the line above
+  // (2026-10-10, the audit's F073).
+  ...AUTH_ENV_VARS,
   'OPENAI_API_KEY',
   'GH_TOKEN',
   'GITHUB_TOKEN',

package/bin/lib/claude.mjs

@@ -1,9 +1,8 @@
 /**
  * The Flowviant side of driving a coding CLI that is not a posture, a stream
- * or a process: the sentinel protocol (a line the contract prompts require a
- * turn to end on) and the hand-over of the flowviant MCP server to whichever
- * runtime runs the turn. The hard rule baked into the prompts: there is no
- * interactive user — the only channel to a human is the blocker loop.
+ * or a process: the sentinel protocol (a line the wiki prompts require a turn
+ * to end on — WIKI_DONE, REGROUND_DONE) and the hand-over of the flowviant MCP
+ * server to whichever runtime runs the turn.
  *
  * This file used to hold everything about a turn. It was split by reason to
  * change (SOLID 2026-09-26): the contract prompts live in prompts.mjs, the
@@ -11,22 +10,21 @@
  * claudeStream.mjs, and the spawn-and-supervise of one turn in runTurn.mjs.
  * The argv, the binary and the event shape of each vendor come from each
  * CLI's registry row (runtime{Claude,Codex,Antigravity}.mjs, assembled in
- * runtimes.mjs; the stream's meaning in runtimeEvents.mjs).
+ * runtimes.mjs; the stream's meaning in runtimeEvents.mjs). The generic
+ * `sleep` that used to live here is a leaf of its own (sleep.mjs, 2026-10-10):
+ * importing it from here loaded the whole runtime registry into `login`.
  */
 
 import { runtimeById } from './runtimes.mjs';
 
-export const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
-
 // Sentinels must appear on their OWN line (the prompts require it). Substring
 // matching falsely fired when an agent merely *mentioned* the word in prose
-// (e.g. "I won't fabricate a BLOCKED:<id> line"), trapping the worker in a fake
-// blocked loop. Anchor to a full line instead.
+// (e.g. "I won't print WIKI_DONE until the pages are written"), ending a turn
+// that had not finished. Anchor to a full line instead.
 //
 // LINE-SPLIT, NEVER A `^...$` REGEX WITH A `\s*` ON BOTH ENDS (audit
-// 2026-09-24). `new RegExp('^\\s*NAME\\s*$', 'm')` and
-// `/^\s*BLOCKED:(\S+)\s*$/m` are QUADRATIC against a long run of
-// whitespace on one line — the same shape `taskIdsFromMessage` already had
+// 2026-09-24). `new RegExp('^\\s*NAME\\s*$', 'm')` is QUADRATIC against a
+// long run of whitespace on one line — the same shape `taskIdsFromMessage` already had
 // to fix, measured ~0.5s at 40KB here — and a CLI's own stdout is exactly
 // the kind of text a stray control sequence or a pasted blob can grow past
 // that. A length cap first, then plain string work, same as there.
@@ -35,14 +33,6 @@ export const sawSentinel = (out, name) =>
   String(out ?? '')
     .split('\n')
     .some((l) => l.length < SENTINEL_MAX_LINE && l.trim() === name);
-export const blockedId = (out) => {
-  for (const l of String(out ?? '').split('\n')) {
-    if (l.length > SENTINEL_MAX_LINE) continue;
-    const t = l.trim();
-    if (t.startsWith('BLOCKED:') && /^BLOCKED:\S+$/.test(t)) return t.slice(8);
-  }
-  return null;
-};
 
 /**
  * Hand a runtime the flowviant MCP server, however that runtime wants it.

package/bin/lib/claudePersonal.mjs

@@ -33,10 +33,22 @@
  * later CLI adds — a sandbox auto-allow, a permission mode — never rides by
  * default. It rides INSIDE the posture's own `--settings`, because the CLI
  * reads one: given two, only the last one's hook fired (measured).
+ *
+ * …AND NEVER ON THE COMMAND LINE (2026-10-10, the audit). What is kept is
+ * exactly where a person puts ANTHROPIC_API_KEY, an auth token or Bedrock's
+ * AWS keys (`env`, `apiKeyHelper`), and argv is every local user's to read
+ * (`ps`, /proc/<pid>/cmdline) for the life of the turn. So the merged object
+ * is written to a file only this user can read — 0600, in a 0700
+ * `~/.flowviant/run/` — and `--settings` names its path, which the CLI reads
+ * as a settings file ("--settings <file-or-json>"). Still exactly one
+ * `--settings`. The file goes when the turn settles (runTurn.mjs asks the
+ * adapter's `releaseArgs`), and a leftover from a process that is gone is
+ * swept on the next write.
  */
-import { readFileSync, statSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { MACHINE_CREDENTIAL_ENV } from './machineEnv.mjs';
 import { WINDOW_ENV_REMOVED, withoutWindows } from './noWindowEnv.mjs';
 
@@ -129,17 +141,70 @@ export function personalClaudeSettings(env = process.env) {
   return out;
 }
 
+/** Where a fenced turn's settings file lives — the daemon's own state
+ *  directory, private to this user. */
+export const turnSettingsDir = () => join(homedir(), '.flowviant', 'run');
+/** A settings file of ours: the writing process's pid, then a random tag. */
+const TURN_SETTINGS_FILE = /^settings-(\d+)-[0-9a-f]{16}\.json$/;
+
+const pidAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+};
+
+/**
+ * Write `settings` to a fresh 0600 file in the run directory and return its
+ * path. The directory is made 0700 (and tightened if it was not), and must be
+ * a real directory — a link standing there is refused, never written through.
+ * A file another process left behind is removed first if that process is gone;
+ * this process's own files are live turns'. THROWS when it cannot write: the
+ * turn then fails in words rather than carrying the person's settings on argv.
+ */
+export function writeTurnSettings(settings, { dir = turnSettingsDir() } = {}) {
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!lstatSync(dir).isDirectory()) throw new Error(`${dir} is not a directory`);
+    chmodSync(dir, 0o700);
+    for (const name of readdirSync(dir)) {
+      const m = TURN_SETTINGS_FILE.exec(name);
+      if (!m || Number(m[1]) === process.pid || pidAlive(Number(m[1]))) continue;
+      rmSync(join(dir, name), { force: true });
+    }
+    const path = join(dir, `settings-${process.pid}-${randomBytes(8).toString('hex')}.json`);
+    writeFileSync(path, JSON.stringify(settings), { mode: 0o600, flag: 'wx' });
+    return path;
+  } catch (error) {
+    throw new Error(`cannot write this turn's Claude settings file under ${dir} (${error?.message ?? error}) — the person's settings never ride the command line`);
+  }
+}
+
+/** Remove the settings file a turn's argv names, when it is one of ours. */
+export function releaseTurnSettings(args, { dir = turnSettingsDir() } = {}) {
+  if (!Array.isArray(args)) return;
+  args.forEach((a, i) => {
+    if (i === 0 || args[i - 1] !== '--settings' || typeof a !== 'string') return;
+    if (dirname(a) !== dir || !TURN_SETTINGS_FILE.test(basename(a))) return;
+    rmSync(a, { force: true });
+  });
+}
+
 /**
  * `perm` with `kept` folded into its `--settings` — the posture's keys win, so
  * a kept key a posture ever names is the fence's word. A posture with no
  * `--settings` gets one before its lists (`--allowedTools` is variadic). With
- * nothing kept, `perm` is returned as it was.
+ * nothing kept, `perm` is returned as it was (the posture's own read guard
+ * names no secret). With something kept, the one `--settings` names the
+ * merged object's file (`write`, writeTurnSettings) and never carries it.
  */
-export function withPersonalSettings(perm, kept) {
+export function withPersonalSettings(perm, kept, { write = writeTurnSettings } = {}) {
   const personal = kept && typeof kept === 'object' && !Array.isArray(kept) ? kept : {};
   if (!Object.keys(personal).length) return [...perm];
   const at = perm.indexOf('--settings');
-  if (at < 0) return ['--settings', JSON.stringify(personal), ...perm];
+  if (at < 0) return ['--settings', write(personal), ...perm];
   const posture = JSON.parse(perm[at + 1]);
-  return [...perm.slice(0, at), '--settings', JSON.stringify({ ...personal, ...posture }), ...perm.slice(at + 2)];
+  return [...perm.slice(0, at), '--settings', write({ ...personal, ...posture }), ...perm.slice(at + 2)];
 }