flowviant 0.96.0 → 0.99.0

package/bin/lib/deploy.mjs

@@ -64,12 +64,26 @@
 
 
 import { spawn } from 'node:child_process';
-import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT, DAEMON_INSTANCE } from './config.mjs';
 import { c, note, ok, warn } from './ui.mjs';
 import { scrub, myPubB64 } from './env.mjs';
 import { childEnv } from './childEnv.mjs';
-import { git } from './git.mjs';
+import { git, gitNetAsync } from './git.mjs';
 
 const deployUrl = (tail) => FLEET_URL.replace(/\/agents\/?$/, `/${tail}`);
 
@@ -157,24 +171,60 @@ export async function reportDeployConfig(repoRoot, baseRef) {
     o && typeof o === 'object'
       ? Object.fromEntries(Object.entries(o).map(([k, v]) => [k, scrub(String(v ?? ''))]))
       : o;
-  const meta = targets.map((t) => ({
-    id: t.id,
-    label: t.label,
-    provider: t.provider || 'cloudflare',
-    command: scrub(String(t.command ?? '')),
-    build: t.build ? scrub(String(t.build)) : t.build,
-    commands: scrubCmds(t.commands),
-    healthcheck: t.healthcheck,
-    healthStatus: t.healthStatus,
-    pushSecrets: t.pushSecrets,
-    // Deploy-on-merge: the env this target auto-deploys to when commits land
-    // on base. MUST ride this map — a field forgotten here never reaches the
-    // server, and the server is what turns a landed report into the job.
-    ...(typeof t.onMerge === 'string' ? { onMerge: t.onMerge } : {}),
-  }));
+  /**
+   * NORMALIZE BEFORE POSTING (2026-09-24, the audit). `.flowviant/deploy.json`
+   * is a hand-written file; the shared schema treats `healthStatus` /
+   * `healthcheck` / `build` / `label` as display metadata and drops what it
+   * cannot read rather than refusing the whole target — but this file used to
+   * send them through unmodified, so a `"healthStatus": "200"` (which
+   * `verifyHealth` below already coerces with `Number()`) or a `null` label
+   * used to reach the wire looking present-but-unreadable. Send exactly what
+   * the mirror is going to keep instead of what the file happened to spell:
+   * a numeric `healthStatus` when the value is numeric or a numeric string,
+   * and no key at all for `label` / `healthcheck` / `build` when the file's
+   * value is not a non-empty string.
+   */
+  const numOrOmit = (v) => {
+    if (typeof v === 'number' && Number.isFinite(v)) return v;
+    if (typeof v === 'string' && /^\s*\d+\s*$/.test(v)) return Number(v);
+    return undefined;
+  };
+  const strOrOmit = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+  const meta = targets.map((t) => {
+    const label = strOrOmit(t.label);
+    const build = strOrOmit(t.build);
+    const healthcheck = strOrOmit(t.healthcheck);
+    const healthStatus = numOrOmit(t.healthStatus);
+    return {
+      id: t.id,
+      ...(label !== undefined ? { label } : {}),
+      provider: t.provider || 'cloudflare',
+      command: scrub(String(t.command ?? '')),
+      ...(build !== undefined ? { build: scrub(build) } : {}),
+      commands: scrubCmds(t.commands),
+      ...(healthcheck !== undefined ? { healthcheck } : {}),
+      ...(healthStatus !== undefined ? { healthStatus } : {}),
+      pushSecrets: t.pushSecrets,
+      // Deploy-on-merge: the env this target auto-deploys to when commits land
+      // on base. MUST ride this map — a field forgotten here never reaches the
+      // server, and the server is what turns a landed report into the job.
+      ...(typeof t.onMerge === 'string' ? { onMerge: t.onMerge } : {}),
+    };
+  });
   try {
-    await post('deploy-config', { pubkey: myPubB64(), targets: meta });
+    const data = await post('deploy-config', { pubkey: myPubB64(), targets: meta });
+    // Set on any 2xx, rejected targets included — the route now accepts a
+    // report per-target rather than failing the whole thing, so a target it
+    // could not read is not a reason to re-post this same file forever.
     lastConfigJson = json;
+    // THE SERVER NAMES WHAT IT COULD NOT READ. Warned once per CHANGED config —
+    // this function only reaches here when the file did — never once per poll.
+    const rejected = Array.isArray(data?.rejected) ? data.rejected : [];
+    for (const r of rejected) {
+      warn(
+        `deploy: .flowviant/deploy.json target "${r?.id ?? '?'}" was not accepted — ${r?.reason ?? 'invalid'}`
+      );
+    }
   } catch (e) {
     warn(`deploy: could not report config — ${e.message}`);
   }
@@ -323,14 +373,8 @@ export function processDeployJobs(jobs, ctx) {
               }
             });
         }, 60_000);
-        const targets = readDeployConfig(ctx.repoRoot, ctx.baseRef);
-        const target = targets.find((t) => t.id === job.targetId);
-        if (!target) {
-          await report(job, ctx, { ok: false, message: `target "${job.targetId}" not in .flowviant/deploy.json` });
-          return;
-        }
         note(`${c.cyan('deploy')} ${c.dim(`— ${job.kind} ${job.targetId} → ${job.env}…`)}`);
-        const outcome = await runDeploy(job, target, ctx);
+        const outcome = await runDeploy(job, ctx);
         // From here the work is DONE. Whatever the report does, this job must
         // never run again in this process.
         ran.add(job.id);
@@ -351,7 +395,271 @@ export function processDeployJobs(jobs, ctx) {
   }
 }
 
-async function runDeploy(job, target, ctx) {
+/**
+ * A DEPLOY BUILDS THE BASE COMMIT, NEVER THE OPERATOR'S WORKING TREE
+ * (audit 2026-09-24).
+ *
+ * `readDeployConfig` reads the TARGET off base so that authoring a command
+ * requires landing it — and then every command ran with `cwd: repoRoot`, the
+ * operator's own checkout, on whatever branch they left it with whatever they
+ * had not committed. So `npm run build` and `wrangler deploy` read the
+ * package.json scripts, wrangler.toml and source of that working tree:
+ * deploy-on-merge (queued by a teammate's ship, a PR merge or an agent merge,
+ * none of which moves the checkout) shipped code WITHOUT the merge that
+ * triggered it, and a co-owner's "deploy it to prod" shipped the operator's
+ * half-finished branch. Reproduced: a checkout on `feature` with an
+ * uncommitted edit deployed the edit.
+ *
+ * So a deploy runs in a THROWAWAY DETACHED WORKTREE at the base tip — the
+ * shipMerge shape — and the config is read from THAT SHA, so the command and
+ * the code it builds are one commit. The directory dies in a `finally`.
+ *
+ * What a fresh worktree does not have is what git does not track: installed
+ * dependencies and the operator's env files. Those are the checkout's
+ * ENVIRONMENT, not its code, so for every directory base tracks (three levels
+ * deep) a `node_modules` in the checkout is re-created as a directory of links
+ * to its entries — a WORKSPACE package's link re-pointed at base's own copy of
+ * that package, never the checkout's working tree — and a `.env` / `.env.*` /
+ * `.dev.vars` the base commit does not carry is COPIED in. Stated residual:
+ * installed third-party packages and those env files are still the checkout's,
+ * so a dependency installed for a feature branch, or an untracked env file an
+ * agent edited, reaches the build; so does a workspace package's untracked
+ * build output (`dist/`), which is simply absent here and fails the build
+ * loudly rather than shipping the checkout's. A `.bin` shim is linked whole, so
+ * a workspace package's own CLI still runs from the checkout. Submodules are
+ * not initialised. The code and the commands no longer come from the checkout.
+ */
+const ENV_FILE_RE = /^(?:\.env(?:\..+)?|\.dev\.vars)$/;
+const lexists = (p) => {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Bring the checkout's untracked environment into a deploy worktree. Returns
+ *  every path it created, so the cleanup can unlink them BEFORE the worktree
+ *  is removed (a recursive delete must never be handed a symlink into the
+ *  operator's own node_modules). */
+export function linkCheckoutEnvironment(repoRoot, dir) {
+  const made = [];
+  let realRoot = repoRoot;
+  try {
+    realRoot = realpathSync(repoRoot);
+  } catch {
+    /* compared as given */
+  }
+  /**
+   * A node_modules is a REAL directory of per-entry links, not one link to the
+   * checkout's (review, audit 2026-09-24). A workspace package — npm, yarn and
+   * pnpm all install one as a link like `node_modules/@x/shared ->
+   * ../../packages/shared` — resolves THROUGH the checkout's node_modules into
+   * the checkout's WORKING TREE, so a whole-directory link had every bundler
+   * import the operator's uncommitted `packages/shared/src` into a deploy of
+   * base. An entry whose real path is inside the checkout but outside any
+   * node_modules is re-pointed at the SAME path in this worktree (base's copy);
+   * one base does not carry is left out, since base cannot import what it does
+   * not have. Every other entry links to the checkout's own, as before.
+   */
+  const linkNodeModules = (src, dst, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(src, { withFileTypes: true });
+      mkdirSync(dst);
+      made.push(dst);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const s = join(src, e.name);
+      const d = join(dst, e.name);
+      // A scope directory holds packages, not a package: one level down.
+      if (depth === 0 && e.name.startsWith('@') && e.isDirectory()) {
+        linkNodeModules(s, d, 1);
+        continue;
+      }
+      let target = s;
+      if (e.isSymbolicLink()) {
+        let real;
+        try {
+          real = realpathSync(s);
+        } catch {
+          continue; // a dangling link — nothing to bring
+        }
+        const rel = relative(realRoot, real);
+        const inCheckout = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+        if (inCheckout && !rel.split(sep).includes('node_modules')) {
+          if (!existsSync(join(dir, rel))) continue;
+          target = join(dir, rel);
+        }
+      }
+      try {
+        symlinkSync(target, d);
+        made.push(d);
+      } catch {
+        /* the build says so if it needed it */
+      }
+    }
+  };
+  const walk = (rel, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(join(repoRoot, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const src = join(repoRoot, rel, e.name);
+      const dst = join(dir, rel, e.name);
+      if (e.name === '.git') continue;
+      if (e.name === 'node_modules') {
+        if (e.isDirectory() && !lexists(dst)) linkNodeModules(src, dst, 0);
+        continue;
+      }
+      if (e.isFile() && ENV_FILE_RE.test(e.name)) {
+        if (!lexists(dst)) {
+          try {
+            copyFileSync(src, dst);
+            made.push(dst);
+          } catch {
+            /* unreadable — the build says so if it needed it */
+          }
+        }
+        continue;
+      }
+      // Recurse only into directories BASE tracks — an untracked `dist/` or a
+      // cache is neither code nor environment, and walking it costs a scan.
+      if (e.isDirectory() && depth < 3 && existsSync(dst) && !lexists(join(dst, '.git'))) {
+        walk(join(rel, e.name), depth + 1);
+      }
+    }
+  };
+  walk('', 0);
+  return made;
+}
+
+/**
+ * Cut the deploy worktree at the base tip. Returns `{ dir, sha, cleanup }`, or
+ * throws with a sentence when base does not resolve. `worktreeDir` defaults to
+ * the daemon's own worktree home for this repo (fleet.mjs keys it the same
+ * way); the job id is hashed into the path, never joined raw — it is a
+ * server-named string.
+ */
+export async function openDeployCheckout({ repoRoot, baseRef, jobId, worktreeDir }) {
+  if (!baseRef) throw new Error('no base branch resolved, so there is nothing to deploy from');
+  try {
+    // A NETWORK call, so timed, non-interactive and off the event loop — a
+    // bare `git fetch` here is `execFileSync` with no timeout, and a remote
+    // that prompts or a half-open connection froze every poll and lease on
+    // the machine until it returned.
+    await gitNetAsync(['fetch', 'origin', '--quiet'], repoRoot);
+  } catch {
+    /* offline — deploy the base this box last saw, and say which */
+  }
+  let sha;
+  try {
+    sha = git(['rev-parse', '--verify', `${baseRef}^{commit}`], repoRoot);
+  } catch {
+    throw new Error(`the base branch ${baseRef} does not resolve on this machine`);
+  }
+  const home =
+    worktreeDir ??
+    join(
+      homedir(),
+      '.flowviant',
+      'worktrees',
+      `${basename(repoRoot)}-${createHash('sha256').update(repoRoot).digest('hex').slice(0, 8)}`
+    );
+  const dir = join(home, 'deploy', createHash('sha256').update(String(jobId)).digest('hex').slice(0, 16));
+  mkdirSync(join(home, 'deploy'), { recursive: true });
+  const drop = (made = [], target = dir) => {
+    // Newest first, so a node_modules directory we made is empty of our links
+    // by the time it is removed.
+    for (const p of [...made].reverse()) {
+      try {
+        unlinkSync(p);
+      } catch {
+        try {
+          rmdirSync(p);
+        } catch {
+          /* already gone */
+        }
+      }
+    }
+    try {
+      git(['worktree', 'remove', '--force', target], repoRoot);
+    } catch {
+      /* not registered */
+    }
+    // Every symlink we made is already unlinked, and `rmSync` unlinks a
+    // symlink rather than descending it, so this can only delete our own copy.
+    try {
+      rmSync(target, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+    try {
+      git(['worktree', 'prune'], repoRoot);
+    } catch {
+      /* best-effort */
+    }
+  };
+  drop(); // a corpse from a crashed deploy of the same job
+  // …and any other job's corpse old enough that no deploy can still be running
+  // in it (two commands at most, 30 minutes each), so a daemon killed
+  // mid-deploy does not leave a checkout on disk for ever.
+  try {
+    const cutoff = Date.now() - 3 * 60 * 60 * 1000;
+    for (const name of readdirSync(join(home, 'deploy'))) {
+      const p = join(home, 'deploy', name);
+      try {
+        if (p !== dir && lstatSync(p).mtimeMs < cutoff) drop([], p);
+      } catch {
+        /* gone meanwhile */
+      }
+    }
+  } catch {
+    /* nothing to sweep */
+  }
+  git(['worktree', 'add', '--detach', dir, sha], repoRoot);
+  let made = [];
+  try {
+    made = linkCheckoutEnvironment(repoRoot, dir);
+  } catch {
+    /* the build says so if it needed any of it */
+  }
+  return { dir, sha, cleanup: () => drop(made) };
+}
+
+export async function runDeploy(job, ctx) {
+  let checkout;
+  try {
+    checkout = await openDeployCheckout({
+      repoRoot: ctx.repoRoot,
+      baseRef: ctx.baseRef,
+      jobId: job.id,
+      worktreeDir: ctx.worktreeDir,
+    });
+  } catch (e) {
+    return { ok: false, message: `deploy not run — ${e.message}`, logs: [] };
+  }
+  try {
+    const targets = readDeployConfig(ctx.repoRoot, checkout.sha);
+    const target = targets.find((t) => t.id === job.targetId);
+    if (!target) {
+      return { ok: false, message: `target "${job.targetId}" not in .flowviant/deploy.json`, logs: [] };
+    }
+    const outcome = await runDeployIn(job, target, checkout.dir);
+    const short = checkout.sha.slice(0, 12);
+    return { ...outcome, sha: checkout.sha, message: `${outcome.message} (${short})` };
+  } finally {
+    checkout.cleanup();
+  }
+}
+
+async function runDeployIn(job, target, cwd) {
   // AN ALLOWLIST, not `{...process.env}` minus names. What stood here was
   //
   //     const env = { ...process.env, ...deployCreds() };
@@ -369,18 +677,44 @@ async function runDeploy(job, target, ctx) {
   // nothing else. It replaced `extra: deployCreds()` when the vault was deleted
   // — the credentials are the OPERATOR's now, in the shell they started the
   // daemon in, rather than values Flowviant decrypted onto the box.
-  const env = childEnv({ cwd: ctx.repoRoot, deploy: true }); // infra creds; never a file
+  const env = childEnv({ cwd, deploy: true }); // infra creds; never a file
   const logs = [];
+  /**
+   * THE ENV-ISOLATION GUARD, RE-APPLIED HERE (2026-09-24, the audit).
+   *
+   * The server already refuses a non-prod trigger whose target declares no
+   * per-env override — `createDeployJob`'s own comment names the same
+   * fallback this file resolves, `commands?.[env] || command`, as the reason:
+   * the base `command` (and the bare `npx wrangler rollback` default) is the
+   * PROD command, so a dev/preview trigger with no override would silently
+   * run production. But that check reads the SERVER'S MIRROR
+   * (`reportDeployConfig`'s last post), and this function reads the file OFF
+   * THE COMMIT it is about to build and run — a window the trigger-time check
+   * cannot close: the file on base changed after the last report, or this
+   * daemon has not reported yet. So the same rule is asked again here,
+   * against the only copy that is about to matter, and prod is the one env
+   * this never touches.
+   */
+  if (job.env !== 'prod') {
+    const key = job.kind === 'rollback' ? `rollback:${job.env}` : job.env;
+    if (!target.commands?.[key]) {
+      return {
+        ok: false,
+        message: `target declares no ${job.env} command — refusing to fall back to the prod command`,
+        logs,
+      };
+    }
+  }
   // Rollback is a single wrangler command; deploy is build → secrets → deploy.
   if (job.kind === 'rollback') {
     const cmd = target.commands?.[`rollback:${job.env}`] || `npx wrangler rollback`;
-    const r = await run(cmd, { cwd: ctx.repoRoot, env });
+    const r = await run(cmd, { cwd, env });
     logs.push(...tailLines(r.out));
     return { ok: r.ok, message: r.ok ? 'rolled back' : logs.slice(-6).join('\n'), logs };
   }
 
   if (target.build) {
-    const b = await run(target.build, { cwd: ctx.repoRoot, env });
+    const b = await run(target.build, { cwd, env });
     logs.push(...tailLines(b.out));
     if (!b.ok) return { ok: false, message: `build failed:\n${logs.slice(-6).join('\n')}`, logs };
   }
@@ -397,7 +731,7 @@ async function runDeploy(job, target, ctx) {
   // values belong there. `target.pushSecrets` stays parsed and reported, which
   // is what every retired key in this product does.
   const cmd = target.commands?.[job.env] || target.command;
-  const d = await run(cmd, { cwd: ctx.repoRoot, env });
+  const d = await run(cmd, { cwd, env });
   logs.push(...tailLines(d.out));
   if (!d.ok) return { ok: false, message: `deploy failed:\n${logs.slice(-8).join('\n')}`, logs };
 

package/bin/lib/env.mjs

@@ -69,8 +69,19 @@
  * caller.
  */
 
-import { readdirSync, readFileSync, writeFileSync, mkdirSync, lstatSync } from 'node:fs';
-import { createHash } from 'node:crypto';
+import {
+  readdirSync,
+  readFileSync,
+  mkdirSync,
+  lstatSync,
+  openSync,
+  writeSync,
+  fsyncSync,
+  closeSync,
+  linkSync,
+  unlinkSync,
+} from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 // STILL SUMO, and deliberately not narrowed to the standard build in the same
@@ -170,7 +181,17 @@ function characterClasses(value) {
 }
 function worthRedacting(value) {
   if (typeof value !== 'string' || value.length < SCRUB_MIN_LENGTH) return false;
-  if (SCRUB_PLAIN_RE.test(value)) return false;
+  // THE PLAIN-IDENTIFIER EXEMPTION DOES NOT COVER A CASE-AND-DIGIT MIX
+  // (2026-09-24, the audit). It was checked first and alone, so a generated
+  // password — `Tq8vZ2mKp4Lx9RbN`, the `pwgen -s 16` shape, or a twelve-
+  // character `Hx93kPq2Lm7w` — starts with a letter, fits sixteen characters of
+  // [A-Za-z0-9] and was left in plain text everywhere this daemon posts, against
+  // this block's own promise that "a case mix" is redacted. A word, a hostname,
+  // a region or a version string does not draw on upper, lower AND digits at
+  // once; a minted secret almost always does.
+  if (SCRUB_PLAIN_RE.test(value) && !(/[a-z]/.test(value) && /[A-Z]/.test(value) && /[0-9]/.test(value))) {
+    return false;
+  }
   if (value.length < 12 && characterClasses(value) < 3) return false;
   return true;
 }
@@ -277,19 +298,87 @@ export async function ensureKeypair() {
     };
     return keypair;
   }
-  keypair = sodium.crypto_box_keypair();
-  mkdirSync(dirname(KEYPAIR_PATH), { recursive: true });
-  writeFileSync(
+  const minted = sodium.crypto_box_keypair();
+  const winner = mintKeypairFile(
     KEYPAIR_PATH,
     JSON.stringify({
-      pub: sodium.to_base64(keypair.publicKey, B64()),
-      priv: sodium.to_base64(keypair.privateKey, B64()),
-    }),
-    { mode: 0o600 }
+      pub: sodium.to_base64(minted.publicKey, B64()),
+      priv: sodium.to_base64(minted.privateKey, B64()),
+    })
   );
+  keypair = {
+    publicKey: sodium.from_base64(winner.pub, B64()),
+    privateKey: sodium.from_base64(winner.priv, B64()),
+  };
   return keypair;
 }
 
+/**
+ * WRITE THE BOX'S IDENTITY ONCE, ATOMICALLY, AND LET THE FIRST WRITER WIN
+ * (2026-09-24, the audit). Returns the `{ pub, priv }` that is ON DISK after
+ * the call — ours, or the one a concurrent first start got there with.
+ *
+ * It was a plain `writeFileSync` reached by every process that saw ENOENT, so
+ * two daemons starting together on a fresh box (two projects, two units at
+ * boot) each minted a key and the LAST writer won: the first kept a key in
+ * memory the disk no longer held and arrived, after its next re-exec, as a
+ * different box. And a crash inside the write left a torn file that every later
+ * start refuses to read — the only-ENOENT-mints rule doing its job over a file
+ * nothing can fix.
+ *
+ * So the key goes to a private temp file, is fsync'd, and is LINKED into place:
+ * `link` fails with EEXIST instead of replacing, so exactly one identity is ever
+ * published and every loser reads the winner's. The file at the real path is
+ * either absent or complete — never half of one.
+ */
+export function mintKeypairFile(path, body) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  try {
+    const fd = openSync(tmp, 'wx', 0o600);
+    try {
+      writeSync(fd, body);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    try {
+      linkSync(tmp, path);
+      return JSON.parse(body);
+    } catch (e) {
+      if (e?.code === 'EEXIST') {
+        // Somebody else published first. Theirs is the identity; ours is dropped.
+        return JSON.parse(readFileSync(path, 'utf8'));
+      }
+      // A filesystem with no hard links (some network and FUSE mounts answer
+      // EPERM/ENOTSUP) must not cost the box its identity — the plain write
+      // this replaced worked there. Fall back to an EXCLUSIVE create: still
+      // first-writer-wins, only without the torn-write guarantee.
+      if (!['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV'].includes(e?.code)) throw e;
+      let fd2;
+      try {
+        fd2 = openSync(path, 'wx', 0o600);
+      } catch (e2) {
+        if (e2?.code !== 'EEXIST') throw e2;
+        return JSON.parse(readFileSync(path, 'utf8'));
+      }
+      try {
+        writeSync(fd2, body);
+        fsyncSync(fd2);
+      } finally {
+        closeSync(fd2);
+      }
+      return JSON.parse(body);
+    }
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
 export function myPubB64() {
   return keypair ? sodium.to_base64(keypair.publicKey, B64()) : null;
 }
@@ -720,8 +809,53 @@ export function scanEnvForScrub(repoRoot, salt = PROJECT_ID) {
  *  ordinary word, a short flag and anything under the length floor are simply
  *  not in it. */
 export function scrub(text) {
-  if (typeof text !== 'string' || !text || !values.length) return text;
+  if (typeof text !== 'string' || !text) return text;
   let out = text;
   for (const v of values) out = out.split(v.value).join(`[REDACTED:${v.name}]`);
-  return out;
+  return out.replace(FLOWVIANT_TOKEN_RE, `[REDACTED:${FLOWVIANT_TOKEN_NAME}]`);
+}
+
+/**
+ * EVERY FLOWVIANT CREDENTIAL, CAUGHT BY SHAPE (2026-09-24, the audit).
+ *
+ * The value lists above are the CHECKOUT'S secrets and the process
+ * environment's, and neither holds the one secret that costs the project
+ * itself: the MACHINE CREDENTIAL. It sits in `~/.flowviant/credentials.json` —
+ * for EVERY project connected on this box, 0600 and readable by every turn,
+ * since a turn runs as this uid — and the server mints more of the same shape
+ * per turn (the work and capture tokens a tab's MCP server carries). A turn
+ * that read the store and wrote it into an artifact, a trace or an answer
+ * shipped it verbatim, because `scrub` had no value to match; and a design
+ * artifact runs scripts in a frame that may navigate itself, so the page that
+ * held it could carry it anywhere.
+ *
+ * Every one of them is `fva_` + 40 characters of nanoid (the server's
+ * `AGENT_TOKEN_PREFIX`), so a SHAPE catches them all, including ones this
+ * process never saw, with no store read and nothing to keep in sync. Twenty is
+ * the floor so the 12-character prefix the app shows for identification
+ * (`fva_` + 8) still reads as itself.
+ */
+const FLOWVIANT_TOKEN_RE = /fva_[A-Za-z0-9_-]{20,}/g;
+const FLOWVIANT_TOKEN_NAME = 'FLOWVIANT_TOKEN';
+
+/**
+ * The NAME of the first known secret whose value appears in `bytes` as an
+ * exact byte substring, or null. For the payloads `scrub` cannot touch: a
+ * binary artifact (a PNG's text chunk, a PDF's uncompressed stream, a zip's
+ * stored entry) is not text to rewrite — replacing bytes inside one corrupts
+ * it — so the caller WITHHOLDS a hit rather than redacting it. The same list,
+ * already filtered by `worthRedacting`, so the two can never disagree about
+ * what counts as a secret. It sees only what is stored plainly: a value inside
+ * a deflated stream is not a substring of the file, and that is stated where
+ * it is used (artifacts.mjs).
+ */
+export function secretIn(bytes) {
+  if (!Buffer.isBuffer(bytes) || !bytes.length) return null;
+  for (const v of values) if (bytes.includes(v.value, 0, 'utf8')) return v.name;
+  // The token SHAPE too (see `scrub`). `latin1` maps every byte to one
+  // character, so the ASCII pattern matches exactly where the bytes do.
+  if (bytes.includes('fva_') && new RegExp(FLOWVIANT_TOKEN_RE.source).test(bytes.toString('latin1'))) {
+    return FLOWVIANT_TOKEN_NAME;
+  }
+  return null;
 }