flowviant 0.82.0 → 0.84.0

package/README.md

@@ -66,6 +66,19 @@ The daemon never executes anything the repository declares. An earlier version r
 | _(stored login)_ or `FLOWVIANT_FLEET` | **the daemon** — the project's machine, serving its sessions |
 | `FLOWVIANT_SAFE=1` | restrict the toolset instead of running unattended |
 
+## Not freezing the box
+
+Since 0.83.0 the daemon looks at the machine before it starts another CLI. It counts the turns it is already running against `FLOWVIANT_MAX_CONCURRENT` (default: what the box's memory and cores can hold), and reads free memory and load. When either says no it simply does not spawn — the job stays queued server-side and is offered again on the next poll, and the app is told the machine's own measured reason ("low memory — 612 MB of 16.0 GB available") at whatever is waiting. Nothing is ever killed, and nothing is parked; pressure clears on its own.
+
+Unattended work (agent turns, a Deploy plan, the wiki sweep) yields first. A Workbench turn — somebody watching a composer — holds out until the box is genuinely about to fall over.
+
+| Env | Default | What it does |
+| --- | --- | --- |
+| `FLOWVIANT_MIN_FREE_MB` | `1024` | free memory below this (or below 6% of total, whichever is larger) defers unattended work |
+| `FLOWVIANT_MAX_LOAD_PER_CORE` | `4` | 1-minute load above `cores × this` defers unattended work |
+| `FLOWVIANT_CRITICAL_FREE_MB` | `400` | free memory below this defers a session turn too |
+| `FLOWVIANT_NO_PRESSURE_GUARD=1` | — | turn the memory/load guard off entirely (the concurrency ceiling still holds) |
+
 ## Security posture
 
 Every project member with edit access can run turns on this machine — a

package/bin/lib/admission.mjs

@@ -0,0 +1,116 @@
+/**
+ * MAY THIS MACHINE START ONE MORE CLI RIGHT NOW?
+ *
+ * One question, asked at every spawn point, answering `null` (go ahead) or
+ * `{ reason }` — the machine's own measured sentence, relayed at the thing that
+ * is waiting and nowhere else.
+ *
+ * ── WHY THIS EXISTS ──
+ *
+ * Flowviant froze somebody's computer. Three separate holes, all of them the
+ * same shape — a bound that had been written down and then stopped being
+ * enforced:
+ *
+ *   · `MAX_CONCURRENT` (config.mjs) is computed from the box's real memory and
+ *     cores, sent to the server on every poll, and was enforced NOWHERE. Its
+ *     local enforcement lived in the dispatch lane and was deleted with it; the
+ *     comment claiming otherwise outlived the code by a month.
+ *   · `processWorkTurns` had no slice, so every session turn the roster offered
+ *     started in one tick.
+ *   · agent turns start four per tick, forever, and nothing looked at memory
+ *     before spawning a process that routinely holds gigabytes.
+ *
+ * ── WHAT THIS IS NOT ──
+ *
+ * It is not a capacity meter: nothing is published ahead of the decision, and
+ * the only time anyone hears about it is the moment it actually fires. It does
+ * not kill anything — no signal is sent on Flowviant's initiative, ever. It
+ * does not park an agent: a park needs a human gesture to lift, and pressure
+ * clears on its own, so a deferral is simply a spawn that did not happen this
+ * tick. And it never settles the job it defers — the server re-offers on the
+ * next poll, which is the whole reason declining is safe.
+ *
+ * ── ORDER, AND WHY CAPACITY IS ASKED FIRST ──
+ *
+ * The count is ours and exact; the pressure reading is the box's and a couple
+ * of seconds old. When both would refuse, the exact one is the honest sentence.
+ *
+ * The capacity reason DOES ride the roster's `pr` relay, and the clause here
+ * used to say it must not — "four turns are running is activity, which the
+ * board already shows". The board shows AGENTS; it has never shown a Workbench
+ * turn or the wiki cartographer, both of which hold this ceiling, and the law
+ * those words come from says the opposite of what they were used for: queueing
+ * is said "AT THE THING THAT IS WAITING, in the moment, never budgeted for in
+ * advance on a global chip". The sentence below names ACTIVITY and never the
+ * ceiling, and it is relayed to exactly one place — the row that is stalled.
+ * Withholding it meant the poll sent `pr=-`, i.e. MEASURED AND FINE, at the
+ * precise moment the machine was refusing everything.
+ *
+ * ── THE COUNT MUST NOT GO STALE INSIDE A TICK ──
+ *
+ * Every spawn in this daemon is ASYNCHRONOUS and every lane loop is not: the
+ * session-turn loop runs `inPlace(...)` per job without awaiting it, so the
+ * child does not reach `workChildren` until a later microtask, and the loop
+ * asked `liveTurnCount()` again on the very next line. The number could not
+ * move, so `0 >= 1` was false eight times in a row and a box with a ceiling of
+ * one started eight session turns, four agent turns, the planner and the wiki
+ * sweep in a single reconcile — the guard biting only on the NEXT tick, after
+ * the box was already loaded. That is the freeze this file exists to prevent,
+ * re-armed and still open.
+ *
+ * A RESERVATION closes it. `admit.reserve()` is taken the moment a job is
+ * admitted and released when its child registers (or when the job ends without
+ * one), so the very next `admit` in the same tick counts the spawn that has
+ * been decided on but not yet happened. It is the count made honest about the
+ * future it has already committed to — not a queue, not a budget, and never
+ * published: nothing outside this module can read the number.
+ *
+ * A LEAKED RESERVATION WOULD SHRINK THE CEILING FOREVER, so every caller
+ * releases in a `finally` as well as at the spawn, and the release is
+ * idempotent so doing both is the normal case rather than a bug.
+ */
+
+import { MAX_CONCURRENT } from './config.mjs';
+import { pressureVerdict } from './resources.mjs';
+
+export function createAdmission({
+  liveTurnCount,
+  maxConcurrent = MAX_CONCURRENT,
+  verdict = pressureVerdict,
+} = {}) {
+  /** Slots taken by a decision whose process does not exist yet. A Set of
+   *  tokens rather than a counter: a double release then costs nothing, which
+   *  is what lets a caller release at the spawn AND in its `finally`. */
+  const holding = new Set();
+
+  /** `level` is 'churn' (unattended lanes) or 'interactive' (a session turn
+   *  somebody is watching). See pressureVerdict for why the two differ. */
+  function admit(level) {
+    const counted = Number(liveTurnCount?.() ?? 0);
+    const live = (Number.isFinite(counted) ? counted : 0) + holding.size;
+    if (live >= maxConcurrent)
+      return {
+        reason: `the machine is already running ${live} CLI turn${live === 1 ? '' : 's'}`,
+      };
+    return verdict(level) ?? null;
+  }
+
+  /**
+   * TAKE THE SLOT THIS ADMISSION JUST GRANTED, and hand back the release.
+   *
+   * Called only after `admit` has answered null, by every caller that then goes
+   * on to spawn. It is deliberately a second call rather than something `admit`
+   * returns: `admit` answers a QUESTION and several of its callers ask it in
+   * places where nothing is about to be started.
+   */
+  admit.reserve = () => {
+    const token = {};
+    holding.add(token);
+    return () => holding.delete(token);
+  };
+
+  /** For tests: slots taken and not yet released. Never relayed anywhere. */
+  admit.reserved = () => holding.size;
+
+  return admit;
+}

package/bin/lib/config.mjs

@@ -4,7 +4,7 @@ import { randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { cpus, totalmem } from 'node:os';
+import { cpus, hostname, totalmem } from 'node:os';
 
 // Read the daemon's version from its OWN package.json (always shipped in the npm
 // tarball) — never hardcode it. The hardcoded constant drifted: it sat at
@@ -118,9 +118,27 @@ export const MACHINE = machineLimits();
  * tests want, and this process is the only party that can see the cores, the
  * RAM and the fan.
  *
- * Sent to the server on every roster poll so it can grow lanes to meet waiting
- * work UNDER this ceiling, and enforced locally besides — the roster can carry
- * more lanes than this, and a ceiling that only exists as a request is not one.
+ * Sent to the server on every roster poll so it can pace what it offers UNDER
+ * this ceiling, and ENFORCED LOCALLY BESIDES — a ceiling that only exists as a
+ * request is not one, and the roster can always offer more than this.
+ *
+ * That second clause was FALSE for a month and this comment went on asserting
+ * it (found 2026-09-14, after the daemon froze somebody's computer). The local
+ * enforcement lived in the dispatch lane's claim path and was deleted with
+ * dispatch on 2026-08-19; nothing replaced it, so every lane that spawns a CLI
+ * — session turns with no slice at all, four agent turns a tick, the planner,
+ * the cartographer — started whatever it was handed. It is true again:
+ * `admission.mjs` counts the live CLI children across every lane and refuses a
+ * new spawn at this number, deferring the job rather than settling it. A stale
+ * comment describing a guard that is not there reads, to the next person,
+ * exactly like a guard that holds — which is how this survived so long.
+ *
+ * AND IT BINDS WITHIN ONE TICK, which the first cut did not. Every lane loop is
+ * synchronous while every spawn under it is not, so the child registry could
+ * not grow between iterations and a single reconcile still admitted everything
+ * it was offered against the count it started with — a ceiling that only bit on
+ * the NEXT tick, after the box was already loaded. `admission.mjs` reserves the
+ * slot at the decision; the reservation argument lives there.
  *
  * MEMORY is the bound, not cores. Cores oversubscribe gracefully (everything
  * gets slower); memory does not (something dies, and not necessarily the
@@ -181,6 +199,28 @@ export const USER_AGENT = `flowviant/${VERSION}`;
  */
 export const DAEMON_INSTANCE = randomBytes(12).toString('hex');
 
+/**
+ * WHICH BOX, in words a person recognises — and nothing else.
+ *
+ * Identity for arbitration is the env keypair's public key (`envpub`), which is
+ * durable per box and already on every poll. This is the LABEL beside it: the
+ * app has to be able to say "your machine is mac-mini" rather than "your machine
+ * is a base64 string", and a box that cannot be named is the one thing a
+ * standby daemon's whole sentence is about.
+ *
+ * Capped like every other bounded write that leaves this process — a query
+ * string is not a log — and null rather than '' when the host has no name, so
+ * the param is ABSENT and reads as an older daemon instead of as a box called
+ * nothing.
+ */
+export const MACHINE_HOST = (() => {
+  try {
+    return String(hostname() || '').trim().slice(0, 64) || null;
+  } catch {
+    return null;
+  }
+})();
+
 // The ONE credential. `tokens` (FLOWVIANT_TOKEN / FLOWVIANT_TOKENS / --token /
 // --tokens) stood beside it and carried WORKER tokens into the pre-daemon loop;
 // that principal owns zero tools since dispatch was deleted, and the kind can no

package/bin/lib/env.mjs

@@ -98,15 +98,36 @@ export function pubkeyEmoji(pubkeyB64) {
 export async function ensureKeypair() {
   await sodium.ready;
   if (keypair) return keypair;
+  let raw = null;
   try {
-    const stored = JSON.parse(readFileSync(KEYPAIR_PATH, 'utf8'));
+    raw = readFileSync(KEYPAIR_PATH, 'utf8');
+  } catch (e) {
+    /**
+     * ONLY "THERE IS NO FILE" IS A FIRST RUN, and the bare catch that used to
+     * stand here said every failure was one.
+     *
+     * This keypair is the box's DURABLE IDENTITY — it is what the project's
+     * private key is sealed to, and since 2026-09-14 it is also what tells two
+     * computers apart when the server decides which of them is this project's
+     * machine. Regenerating it on a truncated file or an unreadable one
+     * OVERWRITES that identity: the wraps stop opening, and the box arrives at
+     * the roster as a stranger and stands itself down as a standby of itself.
+     *
+     * A file we cannot read is not a file we may replace. Rethrown, the caller
+     * that can survive it does: `envQueryParams` is wrapped, so the poll simply
+     * carries no `envpub`, and a poll with no envpub is EXEMPT from arbitration
+     * — the documented fail-open arm, reached honestly instead of by minting a
+     * new box every restart.
+     */
+    if (e?.code !== 'ENOENT') throw e;
+  }
+  if (raw !== null) {
+    const stored = JSON.parse(raw);
     keypair = {
       publicKey: sodium.from_base64(stored.pub, B64()),
       privateKey: sodium.from_base64(stored.priv, B64()),
     };
     return keypair;
-  } catch {
-    /* first run */
   }
   keypair = sodium.crypto_box_keypair();
   mkdirSync(dirname(KEYPAIR_PATH), { recursive: true });