flowviant 0.103.0 → 0.104.0

package/bin/lib/machinesCommand.mjs

@@ -0,0 +1,214 @@
+/**
+ * `flowviant machines` — the command's whole body: the scripted verbs
+ * (`--forget`, `--remove`), the listing assembled from each stored
+ * credential's boxes, and, on a terminal, the ↑/↓ menu over this box's own
+ * connections.
+ *
+ * SPLIT OUT OF cli.mjs (SOLID audit 2026-09-26, F053): the entrypoint changed
+ * for terminal dispatch, for this menu, and for the start path's project
+ * binding. The menu is a stateful interaction with its own confirm and its own
+ * re-ask loop, so it lives here and cli.mjs keeps one line that dispatches to
+ * it. Moved verbatim; the imports stay lazy, as they were, so `--forget` still
+ * never loads config.mjs or reaches the network.
+ *
+ * The rules this body is pinned to (machines.test.mjs, tty.test.mjs): the menu
+ * is gated on BOTH `canPrompt()` and `menuSupported()`, `--remove` and the
+ * menu share one `disconnectHere`, the listing is re-asked after a verb, the
+ * keypair is read and never minted, and no prompt carries a time budget.
+ */
+import { terminalCommand } from './launchCommand.mjs';
+
+// ── `flowviant machines` — every project connected on THIS box, and every box
+//    that has polled each of them; and, on a terminal, a menu over them.
+//
+// A THIRD COMMAND, and the owner's ruling it amends is his own: the terminal
+// surface is `npx flowviant` and `npx flowviant login`, full stop — which is
+// what deleted the old terminal flag for moving a machine — and he asked for
+// this one directly ("the CLI gets a command to list connections"). It shipped
+// VIEW-ONLY, and on 2026-09-23 he asked for the rest: "it seems to be only a
+// read cmd but I want to be able to interact with it and use arrow keys to
+// select the machines or to remove them." So: the listing, then — only where a
+// person can drive one — a menu. Its verbs act on THIS BOX'S OWN CONNECTIONS
+// (stop the daemon here, leave the project's list in the app, forget the
+// credential here) and never on another computer's daemon; machineListing.mjs
+// carries the argument.
+//
+// The question is the owner's, verbatim: "is there a way to view ALL the
+// connected flowviants? because im not sure if i have any duplicate or
+// redundant daemons running". It needs the NETWORK, unlike `projects` next
+// door, because the boxes are the server's answer — this box cannot see a
+// daemon running on somebody else's computer, and guessing would be worse than
+// asking.
+//
+// ONE CALL PER STORED CREDENTIAL, because the CLI has NO PERSON IDENTITY: every
+// request it can make is `Bearer <machine token>`, so "all my machines" has to
+// be assembled from the credentials this box holds. That is also the limit the
+// footer states out loud — the app's Home is where the whole account's answer
+// lives.
+//
+// EXIT 0 whatever it finds, including nothing: the listing is the answer the
+// asker came for, and a non-zero code over "you have no projects connected"
+// would make this command unusable in anything that checks one. `--remove`
+// is the one exit that can be 1, when the daemon it had to stop would not.
+export async function runMachinesCommand() {
+  const creds = await import('./credentials.mjs');
+  const machineJson = process.argv.includes('--json');
+  const forgetAt = process.argv.indexOf('--forget');
+  if (forgetAt >= 0) {
+    if (machineJson && !process.argv.includes('--yes')) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: '--yes is required with --json' })}\n`);
+      process.exit(1);
+    }
+    // THE LOCAL-ONLY WRITE. Named explicitly, matched by full id or a ≥6
+    // prefix, and AMBIGUITY REFUSES rather than guessing — this deletes a
+    // credential, and two projects that look alike is the case that produced
+    // the command.
+    const res = creds.forgetStoredProject(process.argv[forgetAt + 1]);
+    if (res.error) {
+      if (machineJson) { process.stdout.write(`${JSON.stringify({ ok: false, error: res.error })}\n`); process.exit(1); }
+      console.error(`error: ${res.error}`);
+      process.exit(1);
+    }
+    if (machineJson) { process.stdout.write(`${JSON.stringify({ ok: true, action: 'forget', projectId: res.entry.projectId })}\n`); process.exit(0); }
+    console.log(
+      `forgot ${creds.projectLabel(res.entry)} (${res.entry.projectId.slice(0, 8)}…) on this box.\n` +
+        `  Nothing was stopped or deleted anywhere else — \`${terminalCommand('login')}\` connects it again.`
+    );
+    process.exit(0);
+  }
+  const { boxesUrlFrom, leaveUrlFrom, fetchBoxesFor } = await import('./machines.mjs');
+  const { renderMachines, MACHINES_FOOTER, MACHINES_FLAGS_FOOTER } = await import('./machineListing.mjs');
+  const { disconnectHere, disconnectShortfall, realDisconnectDeps } = await import('./machineDisconnect.mjs');
+  const { FLEET_URL } = await import('./config.mjs');
+  const removeAt = process.argv.indexOf('--remove');
+  if (removeAt >= 0) {
+    if (machineJson && !process.argv.includes('--yes')) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: '--yes is required with --json' })}\n`);
+      process.exit(1);
+    }
+    // THE SCRIPTED DISCONNECT — the menu's first verb, named by id for a
+    // terminal nobody is sitting at. Same matcher and the same refusal of an
+    // ambiguous prefix as --forget: a name two projects share is exactly the
+    // input this command exists to untangle, and it must not pick one.
+    const m = creds.matchStoredProject(process.argv[removeAt + 1]);
+    if (m.error) {
+      if (machineJson) { process.stdout.write(`${JSON.stringify({ ok: false, error: m.error })}\n`); process.exit(1); }
+      console.error(`error: ${m.error}. \`${terminalCommand('machines')}\` lists what is stored.`);
+      process.exit(1);
+    }
+    const res = await disconnectHere(m.entry, await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL), log: machineJson ? () => {} : undefined }), { log: machineJson ? () => {} : undefined });
+    if (machineJson) {
+      // A refusal keeps its words for the caller (the tray reads stderr when
+      // the exit is nonzero): a daemon finishing a deploy is said, not "failed".
+      const why = res.ok ? null : (disconnectShortfall(res)?.reason ?? 'failed');
+      process.stdout.write(`${JSON.stringify({ ok: res.ok, action: 'disconnect', projectId: m.entry.projectId, ...(why ? { error: why } : {}) })}\n`);
+      if (why) process.stderr.write(`${why}\n`);
+    }
+    process.exit(res.ok ? 0 : 1);
+  }
+
+  let entries = creds.listStoredProjects();
+  if (entries.length === 0) {
+    console.log(`no projects connected on this machine yet — run \`${terminalCommand('login')}\` inside a repo.`);
+    process.exit(0);
+  }
+  // OUR OWN BOX ID, so the listing can mark "← this box".
+  //
+  // READ, NEVER CREATED. This called `ensureKeypair()` until 2026-09-19, which
+  // MINTS a keypair when there is no file — a 0600 write establishing this
+  // machine's durable identity, performed by a command whose entire job is to
+  // print a list. A view-only command is what let a third terminal command
+  // exist at all, and enrolling a box as a side effect of looking at one is not
+  // that. `readStoredPubB64` reads or answers null.
+  //
+  // NULL COSTS ONLY THE MARK, and that is the honest outcome: a box that has
+  // never run a daemon has never polled, so it is not in this listing to be
+  // marked in the first place.
+  let me;
+  try {
+    const env = await import('./boxIdentity.mjs');
+    me = env.readStoredPubB64() ?? undefined;
+  } catch {
+    /* unreadable keypair — nothing is marked, and nothing is claimed */
+  }
+  const url = boxesUrlFrom(FLEET_URL);
+  const listing = async () => {
+    const results = {};
+    // SEQUENTIAL, not a fan-out: this is a handful of credentials on somebody's
+    // laptop, and a parallel burst against the API buys nothing a person
+    // waiting two seconds can perceive.
+    for (const e of entries) {
+      results[e.projectId] = await fetchBoxesFor(e, { url, envpub: me });
+    }
+    console.log('');
+    for (const line of renderMachines(entries, results)) console.log(line);
+    console.log('');
+  };
+  await listing();
+
+  // THE MENU, only where a person can drive one. `canPrompt()` is the same
+  // gate the start path keeps — a backgrounded job or a pipe gets the listing
+  // and the flags, never a prompt that stops the process — and `menuSupported`
+  // is whether ↑/↓ can be read at all. Without both this is the command it was.
+  const { canPrompt, menuSupported, selectMenu, askWithTimeout } = await import('./tty.mjs');
+  if (!(canPrompt() && menuSupported())) {
+    for (const line of MACHINES_FOOTER) console.log(line);
+    for (const line of MACHINES_FLAGS_FOOTER) console.log(line);
+    process.exit(0);
+  }
+  const deps = await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL) });
+  for (;;) {
+    // A ROW PER PROJECT connected on this box — the things this box can act on.
+    // The other computers under each project are printed above for the
+    // duplicate to be visible, and are not rows here: stopping or removing
+    // THEM is the app's verb, and a menu row that answers "not from here" is
+    // a control wired to a refusal.
+    console.log('  projects connected on this box — enter one for what you can do about it:');
+    const rowLabel = (e) => creds.projectRowLabel(e, entries) + (e.repoRoot ? `  — ${e.repoRoot}` : '  — not tied to a repo');
+    const pick = await selectMenu({ options: [...entries.map(rowLabel), 'done'] });
+    if (pick.cancelled || pick.unsupported || pick.index === entries.length) break;
+    const picked = entries[pick.index];
+    const who = creds.projectRowLabel(picked, entries);
+    // TWO VERBS, each row saying its whole consequence — the app's ⋯ menu on a
+    // machine row says the same two things, and a menu whose rows are verbs
+    // with the outcome in a manual somewhere is one you have to be sure about
+    // before you can use it.
+    const action = await selectMenu({
+      options: [
+        `disconnect this box from ${who} — stops its daemon here, removes this box from its machines list in the app, forgets its credential here`,
+        `forget ${who} here only — nothing is stopped; the app keeps listing this box until it goes quiet`,
+        'back',
+      ],
+    });
+    if (action.cancelled || action.unsupported || action.index === 2) continue;
+    // ONE CONFIRM, in words, because both verbs delete a credential and the
+    // arrow keys make a slip cheap. A read that failed (stdin gone) is "no".
+    const verb = action.index === 0 ? 'Disconnect this box from' : 'Forget';
+    const answer = await askWithTimeout(`  ${verb} ${who}? [y/N] `);
+    if (!/^y(es)?$/i.test(answer ?? '')) {
+      console.log('  left as it was.\n');
+      continue;
+    }
+    if (action.index === 0) {
+      await disconnectHere(picked, deps, { log: (m) => console.log(`  ${m}`) });
+    } else {
+      const res = creds.forgetStoredProject(picked.projectId);
+      console.log(
+        res.error
+          ? `  ${res.error}`
+          : `  forgot ${creds.projectLabel(res.entry)} (${res.entry.projectId.slice(0, 8)}…) on this box. Nothing was stopped or deleted anywhere else — \`${terminalCommand('login')}\` connects it again.`
+      );
+    }
+    entries = creds.listStoredProjects();
+    if (entries.length === 0) {
+      console.log('\n  no projects are connected on this box now.\n');
+      break;
+    }
+    // THE LISTING AGAIN, re-asked: the server's rows are the only true account
+    // of what the leave did, and a menu redrawn over a stale listing would be
+    // this command asserting the outcome it hoped for.
+    await listing();
+  }
+  for (const line of MACHINES_FOOTER) console.log(line);
+  process.exit(0);
+}

package/bin/lib/mcp-cli.mjs

@@ -19,8 +19,9 @@
 
 import { FLEET_TOKEN, USER_AGENT, MCP_URL, FLEET_URL } from './config.mjs';
 import { terminalCommand } from './launchCommand.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
 
-const CLI_TOKEN_URL = FLEET_URL.replace(/\/agents\/?$/, '/cli-token');
+const CLI_TOKEN_URL = fleetEndpoint('cli-token', FLEET_URL);
 
 export async function runMcpCommand(args = []) {
   if (!FLEET_TOKEN) {

package/bin/lib/patchRevert.mjs

@@ -0,0 +1,60 @@
+/**
+ * TAKING A LANDED PATCH BACK — the one live half of what used to be
+ * `patch.mjs`.
+ *
+ * `patch.mjs` held two lifecycles: patch PLACEMENT (cherry-picking a
+ * teammate's agent commit into the owner's checkout after a dirty-path
+ * collision check, plus a commit-history reader for the retired
+ * `report_commits` path) and patch REVERT. Nothing in the daemon has called
+ * placement or the history reader since the dispatch lane was deleted — the
+ * roster still carries `patchRevertJobs` for a patch that landed before then,
+ * and fleetJobs.mjs is the only caller of what is left. So the revert moved here
+ * under its own name and the uncalled half was deleted rather than kept as a
+ * second, stale commit-record parser nobody tests (SOLID audit 2026-09-26,
+ * F167). Git history has the placement code if a new argument ever wants it.
+ *
+ * One revert at a time per daemon: `withPatchLock` serialises every write this
+ * lane makes to the owner's tree, so two jobs cannot race in one checkout.
+ */
+
+import { git, isValidSha } from './git.mjs';
+
+/** Serialises reverts within this process. */
+let patchChain = Promise.resolve();
+
+export function withPatchLock(fn) {
+  const run = patchChain.then(fn, fn);
+  // Keep the chain alive regardless of outcome, but don't swallow the result.
+  patchChain = run.then(
+    () => {},
+    () => {}
+  );
+  return run;
+}
+
+/**
+ * Undo a landed patch. `git revert` rather than `reset` on purpose: the owner
+ * has almost certainly committed or edited on top by now, and rewriting their
+ * history to take something back would be far worse than the patch was.
+ */
+export function revertPatch({ repoRoot, shas }) {
+  // These arrive over the roster and go straight into git argv. Anything that
+  // isn't a bare object id — a revision range, a leading-dash option — is
+  // refused here rather than trusted because the server said so.
+  const clean = (shas ?? []).filter(isValidSha);
+  if (clean.length === 0 || clean.length !== (shas ?? []).length) {
+    return { ok: false, error: 'refused: patch revert carried a non-sha value' };
+  }
+  const ordered = [...clean].reverse(); // newest first
+  try {
+    for (const sha of ordered) git(['revert', '--no-edit', sha], repoRoot);
+    return { ok: true };
+  } catch (e) {
+    try {
+      git(['revert', '--abort'], repoRoot);
+    } catch {
+      /* nothing in progress */
+    }
+    return { ok: false, error: e?.message ?? String(e) };
+  }
+}

package/bin/lib/prWorkflow.mjs

@@ -0,0 +1,157 @@
+/**
+ * THE GITHUB PULL-REQUEST RULES both merge paths share — adopt only an OPEN PR
+ * into the project's base, create one with `--fill`, merge with `--merge`, and
+ * believe "merged" only once the tip is measured on base.
+ *
+ * ── WHY ONE FILE (SOLID audit 2026-09-26, F040) ──
+ *
+ * The session PR lane (`workPullRequests.mjs`) and the agent approve path
+ * (`workAgentMerges.mjs`) each spelled these rules, forty lines apart in
+ * spirit and two files apart in fact, and they had already drifted once: the
+ * session copy adopted a PR into `staging` for months after the agent copy
+ * learned to refuse it, and it went without `gh` timeouts until 0.77.1. What
+ * is theirs stays theirs — which branch is pushed and how, the lease, the
+ * sentences each settles with, the job and the report — and everything that
+ * is a fact about GitHub lives here once:
+ *
+ *  - ADOPT ONLY AN OPEN PR. gh's branch finder falls back to the most recent
+ *    MERGED/CLOSED PR when no open one exists, and adopting a dead PR turns
+ *    every later delivery on a long-lived branch into a silent black hole.
+ *  - …AND ONLY ONE THAT TARGETS THE PROJECT'S BASE. A PR somebody opened by
+ *    hand into another branch would be merged INTO that branch. Refused only
+ *    on a MEASURED mismatch: an absent or empty `baseRefName` adopts as
+ *    before. (The agent copy refused an empty string; the session copy
+ *    adopted it. GitHub never sends one, and "measured" is the rule both
+ *    copies stated, so the session spelling won.)
+ *  - `--fill` titles a created PR from the branch's own commits — no model
+ *    call, nothing invented — and the base is `baseBranchName`, never a
+ *    remote-tracking name gh 422s on.
+ *  - `--merge`, never squash and never rebase: the cards' receipts are commit
+ *    shas, and a squash rewrites them off base, orphaning every receipt and
+ *    blinding the landed walk's trailer read. "Already merged" is a success.
+ *  - VERIFY before claiming merged: modern gh exits 0 on an already-MERGED PR
+ *    and on a merge queue it exits 0 after ENQUEUEING. The tip being an
+ *    ancestor of base is the fact "merged" claims — measured after a fetch,
+ *    with one short retry for the fetch racing GitHub's merge commit.
+ *
+ * EVERY `gh` CALL IS TIMED OUT. `execFileSync` blocks the daemon's whole event
+ * loop, and the agent path runs inside the place writer lock — a `gh` that
+ * hangs (an expired token prompting, a network black hole, a hung credential
+ * helper) would stop every turn on the machine.
+ *
+ * `gh`, the fetch and the sleep are injectable so the rules are provable
+ * without GitHub; nothing in the daemon passes them except the fetch.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { git } from './git.mjs';
+
+/** gh's own first line of complaint, capped — the words a failure relays. */
+export const ghFirstLine = (e) =>
+  ((e?.stderr?.toString?.() || e?.message || 'failed').split('\n').find((l) => l.trim()) ||
+    'failed')
+    .slice(0, 400);
+
+/** A pull request URL worth storing. Anything else gh printed is not one. */
+export const PR_URL_RE = /^https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+$/;
+
+const runGh = (args, opts) => execFileSync('gh', args, { stdio: ['ignore', 'pipe', 'pipe'], ...opts });
+
+/**
+ * Is `gh` installed and signed in? null when it is; otherwise
+ * `{ missing, error }` — `missing` when the binary is absent, so each caller
+ * can say "not installed" and "not signed in" in its own words.
+ */
+export function ghReady({ gh = runGh } = {}) {
+  try {
+    gh(['auth', 'status'], { timeout: 20_000 });
+    return null;
+  } catch (e) {
+    return { missing: e?.code === 'ENOENT', error: ghFirstLine(e) };
+  }
+}
+
+/** The OPEN pull request for `head`, as `{ url, base }` — or null when there
+ *  is none, or only a merged/closed one. `base` is null when gh did not say. */
+export function findOpenPr(head, { cwd, gh = runGh } = {}) {
+  try {
+    const j = JSON.parse(gh(['pr', 'view', head, '--json', 'url,state,baseRefName'], { cwd, timeout: 30_000 }).toString());
+    if (j?.state !== 'OPEN' || typeof j?.url !== 'string') return null;
+    return { url: j.url.trim(), base: typeof j?.baseRefName === 'string' ? j.baseRefName : null };
+  } catch {
+    return null; // no PR for the branch at all
+  }
+}
+
+/** The branch an open PR targets when it is MEASURED to be not `base`, else
+ *  null — the one refusal condition for adopting it. */
+export function prTargetsOtherBase(pr, base) {
+  return pr && pr.base && pr.base !== base ? pr.base : null;
+}
+
+/**
+ * THE OPEN PR FOR `head` INTO `base`: adopt one already open (a re-delivery,
+ * or one somebody opened by hand), or create it. Answers
+ *   `{ url, adopted }`   — url may be null if gh printed nothing usable
+ *   `{ wrongBase }`      — an open PR targets another branch; nothing created
+ *   `{ error }`          — gh's own words from a failed create
+ */
+export function ensureOpenPr(head, base, { cwd, gh = runGh } = {}) {
+  const existing = findOpenPr(head, { cwd, gh });
+  const wrongBase = prTargetsOtherBase(existing, base);
+  if (wrongBase) return { wrongBase };
+  if (existing?.url) return { url: existing.url, adopted: true };
+  try {
+    const out = gh(['pr', 'create', '--head', head, '--base', base, '--fill'], { cwd, timeout: 60_000 })
+      .toString()
+      .trim();
+    return { url: out.split('\n').filter(Boolean).pop() ?? null, adopted: false };
+  } catch (e) {
+    return { error: ghFirstLine(e) };
+  }
+}
+
+/**
+ * Is `tip` on `baseRef` yet? Fetch, then ask git; once more after a short
+ * pause if not, for the fetch racing GitHub's merge commit. An offline fetch
+ * answers from what the box already has. A null tip is never on base.
+ */
+export async function tipReachedBase({ tip, baseRef, repoRoot, fetchOrigin, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), gitImpl = git }) {
+  if (!tip) return false;
+  const onBase = () => {
+    try {
+      gitImpl(['merge-base', '--is-ancestor', tip, baseRef()], repoRoot);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt > 0) await sleep(2000);
+    try {
+      fetchOrigin();
+    } catch {
+      /* offline — the check below answers from what we have */
+    }
+    if (onBase()) return true;
+  }
+  return false;
+}
+
+/**
+ * MERGE `head`'s PR with a merge commit and VERIFY the tip reached base.
+ * Answers `{ ok: true }`, `{ error }` (gh refused, in its own words — an
+ * "already merged" is not a refusal), or `{ notOnBase: true }` (gh said yes
+ * and base does not have the tip: an older PR merged, or a queue holds it).
+ * The push that must precede it is the caller's: GitHub merges the REMOTE tip.
+ */
+export async function mergeAndVerifyTip(head, { cwd, tip, baseRef, repoRoot, fetchOrigin, gh = runGh, sleep, gitImpl }) {
+  try {
+    gh(['pr', 'merge', head, '--merge'], { cwd, timeout: 120_000 });
+  } catch (e) {
+    const line = ghFirstLine(e);
+    if (!/already merged/i.test(line)) return { error: line };
+  }
+  const landed = await tipReachedBase({ tip, baseRef, repoRoot, fetchOrigin, sleep, gitImpl });
+  return landed ? { ok: true } : { notOnBase: true };
+}

package/bin/lib/preflight.mjs

@@ -7,7 +7,8 @@
 import { execFileSync } from 'node:child_process';
 import { ok, warn, info, c } from './ui.mjs';
 import { addLocalBinToPath, promptYesNo, installClaude, installGh } from './install.mjs';
-import { RUNTIMES, detectRuntimes, mediatedSafeGap } from './runtimes.mjs';
+import { RUNTIMES, mediatedSafeGap } from './runtimes.mjs';
+import { detectRuntimes } from './runtimeDetection.mjs';
 import { terminalCommand } from './launchCommand.mjs';
 
 function present(cmd) {

package/bin/lib/pressurePolicy.mjs

@@ -0,0 +1,104 @@
+/**
+ * THE PRESSURE GUARD'S DECISION — pure, and nothing else (2026-09-26, SOLID
+ * F050).
+ *
+ * Split out of resources.mjs, which MEASURES the box. The verdict used to read
+ * `FLOWVIANT_NO_PRESSURE_GUARD` and the three numeric overrides out of
+ * `process.env` itself while deciding from a measurement it was handed, so one
+ * measurement could yield two answers depending on ambient state, and every
+ * test of a threshold had to mutate the process's global environment.
+ *
+ * Now the thresholds are an ARGUMENT. `readPressureThresholds(env)` is the one
+ * adapter from an environment to them, and admission.mjs calls it per decision
+ * (never once at import), so an operator's override is still true of the
+ * environment the daemon is in RIGHT NOW rather than the one it booted in.
+ *
+ * Why the guard exists, and why it is a runaway bound and never a headroom
+ * meter, is argued at the top of resources.mjs.
+ */
+
+const MiB = 1024 * 1024;
+const GiB = 1024 * MiB;
+
+/** What a box that nobody tuned is judged against. */
+export const DEFAULT_PRESSURE_THRESHOLDS = Object.freeze({
+  off: false,
+  criticalFreeBytes: 400 * MiB,
+  minFreeBytes: 1024 * MiB,
+  maxLoadPerCore: 4,
+});
+
+/** An operator's override, or the default. Positive finite numbers only: a
+ *  typo'd `FLOWVIANT_MIN_FREE_MB=lots` must fall back to the default rather
+ *  than turning every comparison into NaN, which compares false and would
+ *  silently disable the guard it was trying to tune. */
+const envNum = (env, name, fallback) => {
+  const n = Number(env?.[name]);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+
+/**
+ * The thresholds an environment states. `FLOWVIANT_NO_PRESSURE_GUARD=1` is the
+ * escape hatch for a box whose operator knows better than the thresholds;
+ * absence and `'0'` both mean the guard is on. The default parameter is
+ * evaluated per CALL, so a caller that passes nothing reads the live
+ * `process.env`.
+ */
+export function readPressureThresholds(env = process.env) {
+  const d = DEFAULT_PRESSURE_THRESHOLDS;
+  return {
+    off: env?.FLOWVIANT_NO_PRESSURE_GUARD === '1',
+    criticalFreeBytes: envNum(env, 'FLOWVIANT_CRITICAL_FREE_MB', d.criticalFreeBytes / MiB) * MiB,
+    minFreeBytes: envNum(env, 'FLOWVIANT_MIN_FREE_MB', d.minFreeBytes / MiB) * MiB,
+    maxLoadPerCore: envNum(env, 'FLOWVIANT_MAX_LOAD_PER_CORE', d.maxLoadPerCore),
+  };
+}
+
+const sizeWord = (n) =>
+  n >= GiB ? `${(n / GiB).toFixed(1)} GB` : `${Math.round(n / MiB)} MB`;
+
+/**
+ * IS THIS A MOMENT TO START ANOTHER CLI? — null when there is nothing to say.
+ *
+ * TWO LEVELS, because the two lanes are not the same promise. `churn` is the
+ * unattended work — agent turns, a Deploy press's planner, the wiki
+ * cartographer — which nobody is sitting in front of and which the server will
+ * cheerfully re-offer next poll, so it yields early and generously. A session
+ * turn is `interactive`: somebody is watching a composer they just pressed
+ * enter in, and deferring that is a visible stall, so it holds out until the
+ * box is genuinely about to fall over.
+ *
+ * THE REASON IS MEASURED WORDS AND NOTHING ELSE. No adjectives about the
+ * machine, no advice, no "try again in a few minutes" — a sentence naming the
+ * number that fired, which is the only thing this side actually knows.
+ *
+ * An unreadable measurement contributes NO verdict: memory that could not be
+ * read cannot refuse, and a load average this platform does not publish cannot
+ * either. A missing measurement altogether is the same ignorance. Ignorance
+ * never withholds.
+ */
+export function pressureVerdict(level, measured, thresholds = DEFAULT_PRESSURE_THRESHOLDS) {
+  const t = { ...DEFAULT_PRESSURE_THRESHOLDS, ...(thresholds ?? {}) };
+  if (t.off) return null;
+  const m = measured ?? null;
+  const avail = Number.isFinite(m?.memAvailable) ? m.memAvailable : null;
+  if (level === 'interactive') {
+    if (avail !== null && avail < t.criticalFreeBytes)
+      return { reason: `nearly out of memory — ${sizeWord(avail)} available` };
+    return null;
+  }
+  const total = Number.isFinite(m?.memTotal) && m.memTotal > 0 ? m.memTotal : 0;
+  // A fixed floor AND a proportional one, whichever is larger: 1 GB is the
+  // right reserve on a laptop and is nothing on a 256 GB box, where six per
+  // cent is the honest "the page cache is already being squeezed" line.
+  const floor = Math.max(t.minFreeBytes, Math.round(total * 0.06));
+  if (avail !== null && avail < floor)
+    return { reason: `low memory — ${sizeWord(avail)} of ${sizeWord(total)} available` };
+  const cores = Number.isFinite(m?.cores) && m.cores > 0 ? m.cores : null;
+  const load = Number.isFinite(m?.load1) ? m.load1 : null;
+  if (load !== null && cores !== null && load > cores * t.maxLoadPerCore)
+    return {
+      reason: `cpu overloaded — load ${load.toFixed(1)} on ${cores} core${cores === 1 ? '' : 's'}`,
+    };
+  return null;
+}