flowviant 0.116.0 → 0.124.0

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);
 }
@@ -239,8 +243,8 @@ export function snapshotArtifacts(placeDir) {
 }
 
 /** What the turn wrote: every entry whose (name, size, mtime) is not what the
- *  snapshot held. A deleted file is not reported — the server's copy is
- *  scrollback and goes with the session or the agent. */
+ *  snapshot held. Deletions and replacement relationships are reported by
+ *  artifactIteration.mjs separately from upload bodies. */
 export function changedArtifacts(before, entries) {
   return entries.filter((e) => before?.get(e.name) !== sigOf(e));
 }
@@ -289,6 +293,9 @@ function safeArtifactName(raw) {
   return clean ? cutKeepingExtension(clean) : 'artifact';
 }
 
+/** The stored name is also the key for iteration and queued upload cancellation. */
+export const artifactStoredName = (name) => name.split('/').map(safeArtifactName).join('/');
+
 /**
  * ONE UPLOAD BODY, as data — fields plus optional bytes — so a held body is
  * re-sent exactly as it was first built (scrubbed once, never re-read from a
@@ -299,7 +306,7 @@ export function buildArtifactUpload(entry, { sessionId, agentId, turnId }, scrub
   const fields = {
     ...(sessionId ? { sessionId } : { agentId }),
     ...(turnId ? { turnId } : {}),
-    name: entry.name.split('/').map(safeArtifactName).join('/'),
+    name: artifactStoredName(entry.name),
     bytes: String(entry.size),
   };
   if (!type) return { fields, bytes: null }; // reported by name only

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

@@ -26,8 +26,9 @@
  *    daemon started, so a variable exported weeks ago is still in there long
  *    after it left your shell. A stale one fails in a way a fresh `claude`
  *    never reproduces.
- *  · THE HOME. The CLI reads its store from $HOME. A daemon under systemd, a
- *    different user, or a container has a different one than the shell you
+ *  · THE STORE. The CLI uses $CLAUDE_CONFIG_DIR, else $HOME/.claude. A daemon
+ *    under systemd, a different user, or a container has a different one than
+ *    the shell you
  *    tested in, so "I am logged in" was measured on the wrong file.
  *
  * ── WHAT THIS IS NOT ──
@@ -75,11 +76,19 @@ export const AUTH_ENV_VARS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAU
 /** Claude Code's OAuth store, relative to the HOME the CLI will be handed. */
 const CRED_REL = ['.claude', '.credentials.json'];
 
+/** The same location Claude's personal settings reader uses. */
+export function claudeCredentialPath(env = process.env, home = null) {
+  const root = home ?? env.HOME ?? env.USERPROFILE ?? null;
+  return env.CLAUDE_CONFIG_DIR
+    ? join(env.CLAUDE_CONFIG_DIR, '.credentials.json')
+    : root ? join(root, ...CRED_REL) : null;
+}
+
 
 /**
  * What the CLI on this machine will resolve, as far as it can be seen without
  * spending anything: no process spawned, no request made, no quota touched.
- * Just this process's own environment and one file's metadata.
+ * Just this process's own environment and the CLI-selected file's metadata.
  *
  * `env` and `home` are parameters rather than reads of `process` so the tests
  * can drive every branch — and so the caller passes the SAME environment the
@@ -98,9 +107,10 @@ export function claudeAuthContext({ env = process.env, home = null } = {}) {
   let refreshExpiresAt = null;
   let accessExpiresAt = null;
   let subscriptionType = null;
-  if (HOME) {
+  const credentialPath = claudeCredentialPath(env, HOME);
+  if (credentialPath) {
     try {
-      const raw = readFileSync(join(HOME, ...CRED_REL), 'utf8');
+      const raw = readFileSync(credentialPath, 'utf8');
       const oauth = JSON.parse(raw)?.claudeAiOauth;
       if (oauth && typeof oauth === 'object') {
         hasFile = true;

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)];
 }