flowviant 0.82.0 → 0.85.0

package/bin/lib/resources.mjs

@@ -14,12 +14,44 @@
  * run 2 more tasks" is the capacity dial wearing a lab coat, and that is dead.
  * The only surface for this is project settings, whose audience is whoever
  * administers the box.
+ *
+ * ── AND SINCE 2026-09-14 THERE IS A SECOND READER, WHICH IS NOT TELEMETRY ──
+ *
+ * The paragraph above is about the SNAPSHOT and stands unchanged. What is added
+ * below — `memAvailableBytes` and `pressureVerdict` — is read at the moment
+ * this machine is about to spawn one more CLI, and it exists because it froze
+ * somebody's computer: `MAX_CONCURRENT` had been enforced nowhere since
+ * dispatch was deleted, the session-turn lane had no slice at all, and nothing
+ * anywhere looked at memory before starting a process that routinely holds
+ * gigabytes.
+ *
+ * It is a RUNAWAY BOUND ON A MACHINE, in the same family as the open-tab
+ * ceiling and the card-write budget, and the distinction from a headroom meter
+ * is exact and worth stating because the two look alike from a distance:
+ *
+ *   · a HEADROOM METER is read AHEAD of the decision, by the person making it,
+ *     and pre-declares what they may do ("room for 2 more"). That is the
+ *     capacity dial, and it is dead.
+ *   · a RUNAWAY BOUND is read AT the spawn, by the machine, and produces
+ *     nothing at all until it actually fires — at which point what surfaces is
+ *     the machine's own measured sentence AT THE THING THAT IS WAITING ("low
+ *     memory — 612 MB of 16.0 GB available"), which is the same shape as a CLI
+ *     relaying that it hit its own limit.
+ *
+ * So: no number is ever published in advance, nothing is killed (this module
+ * signals nothing, ever), nothing is parked (a park needs a human gesture to
+ * lift; pressure clears on its own), and a machine that cannot MEASURE refuses
+ * nothing — an unreadable /proc is ignorance, and ignorance never withholds.
  */
 
+import { execFileSync } from 'node:child_process';
 import { readFileSync, readdirSync, statfsSync } from 'node:fs';
-import { freemem, loadavg } from 'node:os';
+import { freemem, loadavg, platform } from 'node:os';
 import { MACHINE } from './config.mjs';
 
+const MiB = 1024 * 1024;
+const GiB = 1024 * MiB;
+
 const readFile = (p) => {
   try {
     return readFileSync(p, 'utf8').trim();
@@ -92,6 +124,193 @@ export function processTreeRssBytes(pid) {
   return total || null;
 }
 
+/**
+ * HOW MUCH MEMORY A NEW PROCESS COULD ACTUALLY HAVE.
+ *
+ * Deliberately NOT `freemem()`, which reports pages nobody is using — on any
+ * box that has been up a while that is a small number next to a large page
+ * cache, so a machine with 12 GB of reclaimable cache reads as nearly full and
+ * a guard built on it would refuse everything forever. Linux publishes the
+ * honest figure itself (`MemAvailable`, which accounts for what the kernel
+ * would reclaim under pressure); macOS does not, so free + inactive + purgeable
+ * pages is the nearest thing it will say out loud.
+ *
+ * The cgroup is asked SECOND and narrows rather than replaces, for the reason
+ * `machineLimits` gives in config.mjs: a 4GB container on a 256GB box reads the
+ * host through the os module, and oversubscribing there ends with the OOM
+ * killer picking a victim by resident size — frequently not the offender.
+ *
+ * Returns null ONLY where nothing could be read at all, and the caller treats
+ * that as ignorance. Everything downstream must keep that distinction: a
+ * machine that cannot look must not refuse work.
+ *
+ * AND FOR ONE RELEASE IT COULD NOT RETURN NULL, which made the sentence above a
+ * promise the code did not keep. Every branch ended in `freemem()` — the figure
+ * the first paragraph rejects by name — so an unreadable `/proc` (a masked or
+ * restricted container), a `MemAvailable:` line this kernel does not publish, or
+ * a `vm_stat` that will not run all substituted the ONE number this module says
+ * a guard built on it would refuse everything forever. The caller's ignorance
+ * arms were dead code, and what shipped instead was a machine deferring every
+ * agent turn, Deploy press and wiki sweep indefinitely while relaying "low
+ * memory — 612 MB of 16.0 GB available" as if it had measured something. A
+ * Flowviant-invented refusal standing on a number this file already calls
+ * unusable is worse than no guard.
+ *
+ * WINDOWS IS THE ONE PLACE `freemem()` IS THE RIGHT FIGURE, and it is kept
+ * there deliberately rather than by omission: Node reads it from
+ * `GlobalMemoryStatusEx().ullAvailPhys`, which is an AVAILABLE number in the
+ * same sense `MemAvailable` is, not a count of untouched pages. Every other
+ * platform this does not name reports free pages, so it says nothing at all.
+ *
+ * `read` is a PARAMETER, and only so the null contract can be pinned: the
+ * ignorance case cannot be reached from a test that has a working `/proc`, and
+ * an unreachable branch is how the fallback above survived review in the first
+ * place. Nothing in the daemon passes it.
+ */
+export function memAvailableBytes(read = readFile) {
+  if (platform() === 'linux') {
+    let avail = null;
+    const mi = read('/proc/meminfo');
+    const m = mi && mi.match(/^MemAvailable:\s+(\d+)\s+kB/m);
+    if (m) avail = Number(m[1]) * 1024;
+    const max = read('/sys/fs/cgroup/memory.max');
+    if (max && max !== 'max') {
+      const limit = Number(max);
+      const cur = Number(read('/sys/fs/cgroup/memory.current'));
+      if (Number.isFinite(limit) && limit > 0 && Number.isFinite(cur)) {
+        const room = Math.max(0, limit - cur);
+        avail = avail === null ? room : Math.min(avail, room);
+      }
+    }
+    return avail !== null && Number.isFinite(avail) ? avail : null;
+  }
+  if (platform() === 'darwin') return darwinAvailableBytes();
+  if (platform() === 'win32') {
+    const f = freemem();
+    return Number.isFinite(f) && f > 0 ? f : null;
+  }
+  return null;
+}
+
+/**
+ * `vm_stat`'s page counts, in the units it states in its own header.
+ *
+ * The page size is READ rather than assumed for exactly the reason
+ * `processes.mjs` reads VmRSS's unit instead of multiplying statm by 4096:
+ * Apple Silicon runs 16K pages, and a memory readout that is silently four
+ * times wrong on somebody's machine is worse than no readout at all.
+ */
+function darwinAvailableBytes() {
+  let text;
+  try {
+    text = execFileSync('vm_stat', [], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    });
+  } catch {
+    return null; // no vm_stat, or it took too long — say nothing
+  }
+  const pm = text.match(/page size of (\d+) bytes/);
+  const page = pm ? Number(pm[1]) : 4096;
+  const pagesOf = (label) => {
+    const m = text.match(new RegExp(`^${label}:\\s+(\\d+)\\.`, 'm'));
+    return m ? Number(m[1]) : 0;
+  };
+  const pages = pagesOf('Pages free') + pagesOf('Pages inactive') + pagesOf('Pages purgeable');
+  return pages > 0 ? pages * page : null;
+}
+
+/** The guard off entirely — an escape hatch for a box whose operator knows
+ *  better than the thresholds. Read per call, not captured at import, so it is
+ *  true of the environment the daemon is in RIGHT NOW rather than the one it
+ *  booted in. `absence` and `'0'` both mean the guard is on. */
+export function pressureGuardOff() {
+  return process.env.FLOWVIANT_NO_PRESSURE_GUARD === '1';
+}
+
+/** 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 = (name, fallback) => {
+  const n = Number(process.env[name]);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+
+const sizeWord = (n) =>
+  n >= GiB ? `${(n / GiB).toFixed(1)} GB` : `${Math.round(n / MiB)} MB`;
+
+/** How long one measurement stands. The reconcile loop asks several times a
+ *  tick (one per admission point) and every answer would otherwise be a fresh
+ *  /proc read — or, on macOS, a fresh `vm_stat` spawn, which is a process per
+ *  question about whether to start a process. */
+const PRESSURE_CACHE_MS = 2_000;
+let lastMeasure = { at: 0, m: null };
+
+/** What the box says about itself, cached briefly. Exported so a caller can
+ *  hold one reading across several verdicts — and so tests can pass their own
+ *  instead of depending on the machine they run on. */
+export function measurePressure() {
+  const now = Date.now();
+  if (lastMeasure.m && now - lastMeasure.at < PRESSURE_CACHE_MS) return lastMeasure.m;
+  const m = {
+    memAvailable: memAvailableBytes(),
+    memTotal: MACHINE.memBytes,
+    // Unix only; Windows reports zeroes, which are sent as null rather than as
+    // a very calm-looking 0.00 — the same rule the snapshot keeps.
+    load1: loadavg()[0] || null,
+    cores: MACHINE.cores,
+  };
+  lastMeasure = { at: now, m };
+  return m;
+}
+
+/**
+ * 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. Ignorance never withholds.
+ */
+export function pressureVerdict(level, measured) {
+  if (pressureGuardOff()) return null;
+  const m = measured ?? measurePressure();
+  const avail = Number.isFinite(m?.memAvailable) ? m.memAvailable : null;
+  if (level === 'interactive') {
+    const floor = envNum('FLOWVIANT_CRITICAL_FREE_MB', 400) * MiB;
+    if (avail !== null && avail < floor)
+      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(envNum('FLOWVIANT_MIN_FREE_MB', 1024) * MiB, 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 * envNum('FLOWVIANT_MAX_LOAD_PER_CORE', 4))
+    return {
+      reason: `cpu overloaded — load ${load.toFixed(1)} on ${cores} core${cores === 1 ? '' : 's'}`,
+    };
+  return null;
+}
+
 /** Free bytes on the volume holding the worktrees. */
 export function diskFreeBytes(path) {
   try {
@@ -120,7 +339,13 @@ export function machineSnapshot({ worktreeDir, tasks = [] } = {}) {
     diskFree: disk?.free ?? null,
     diskTotal: disk?.total ?? null,
     // Per-task, so "the box is full" can be traced to the task that filled it.
+    //
+    // BOUNDED BEFORE THE WALK, not after: each row costs a /proc tree walk, and
+    // the cap exists so a caller that hands over a long list cannot turn a
+    // telemetry post into a scan of the whole process table. Sixteen is more
+    // live turns than any machine this guard admits will ever hold.
     tasks: tasks
+      .slice(0, 16)
       .map((t) => ({ taskId: t.intentId, rss: processTreeRssBytes(t.pid) }))
       .filter((t) => t.taskId && t.rss),
   };

package/bin/lib/runtimes.mjs

@@ -201,6 +201,31 @@ export function toolEventOf(name, input = {}, cwd = '', scrub = (s) => s) {
   }
 }
 
+/**
+ * THE ACTIVITY KINDS `toolEventOf` ALSO ANSWERS — the dedupe rule, stated once.
+ *
+ * A Claude tool call goes down BOTH paths in claude.mjs: `humanizeClaudeTool`
+ * makes a one-line activity and `toolEventOf` makes a structured event, from
+ * the same `tool_use`. A consumer taking both — the agent turn's trace — would
+ * otherwise render every read twice, once as a sentence and once as a card.
+ *
+ * It is the KINDS the structured builder answers, not every tool kind: `LS`
+ * produces a `list` activity and no tool event, so dropping `list` would delete
+ * it from the trace entirely. And it is only safe to apply on the runtimes
+ * whose stream reaches `onToolEvent` at all — codex and agy have their own
+ * parsers, never call it, and would go silent. Both halves are pinned in
+ * trace.test.mjs, because the two functions are edited independently and the
+ * failure is invisible: a dropped prose line looks exactly like a quiet turn.
+ */
+export const CLAUDE_TOOL_PROSE_KINDS = new Set([
+  'read',
+  'write',
+  'search',
+  'glob',
+  'bash',
+  'plan',
+]);
+
 // ── Codex ──────────────────────────────────────────────────────────────────
 
 /**

package/bin/lib/trace.mjs

@@ -0,0 +1,194 @@
+/**
+ * THE WHOLE TURN, RELAYED — "watch it work".
+ *
+ * An agent turn already streams everything it does: the CLI prints its
+ * thinking, its narration and every tool call, `runTurn` parses all of it, and
+ * the agent lane read exactly ONE line out of that stream every two seconds,
+ * overwrote the previous one, and threw the rest away. So the board could say
+ * an agent was reading a file and never what it had read before that — which is
+ * the difference between a spinner with a caption and watching Claude Code.
+ *
+ * This is the second, DURABLE channel for the same stream. The one-line pulse
+ * (`/fleet/agent-activity`) is untouched and still sent: it carries staleness —
+ * "the machine last spoke 40 seconds ago" — which an append-only list of steps
+ * cannot, because a list that stopped growing and a list that is complete look
+ * identical.
+ *
+ * ── FOUR RULES, AND EACH ONE IS LOAD-BEARING ──
+ *
+ * ORDER IS THE CONTRACT. Batches are serialized through an await chain, never
+ * fired in parallel: the server appends what arrives, so two POSTs in flight at
+ * once would interleave a turn's steps into a sequence that never happened.
+ *
+ * SEQ IS ABSOLUTE, AND DROPS ADVANCE IT. Every entry accepted here gets an
+ * index in this turn's whole stream, whether it is sent or shed from a full
+ * buffer. That makes a retry idempotent — the server trims what it already has
+ * against its high-water mark rather than appending it twice — and it makes a
+ * GAP visible: the server's "N earlier steps aren't shown" is computed from the
+ * distance between the high-water mark and what it kept, so a daemon-side drop
+ * and a server-side prune are reported as the same honest sentence instead of
+ * one of them being silent.
+ *
+ * …AND IT IS ABSOLUTE WITHIN ONE RUN, WHICH IS WHY EVERY BATCH NAMES ITS RUN.
+ * The counter lives in this closure, and this closure is built fresh inside
+ * `runAgentTurn`; the server's high-water mark lives on the TURN ROW and
+ * outlives any number of attempts at it. A turn is re-run whenever the daemon
+ * restarts mid-turn, is taken over, or throws after the CLI ran but before the
+ * settle — the server hands the identical turn back on the next poll — and the
+ * second attempt then opened at `seq: 0` against a mark of three hundred, so
+ * every batch it sent was trimmed to nothing and the surface showed the
+ * ABANDONED attempt's steps with the new one's tail welded on, no seam, no
+ * `dropped` to say so. `run` is a nonce per relay: the server rebases an
+ * unfamiliar one onto its current mark, so a second attempt appends AFTER the
+ * first instead of being deleted by it, and a retry inside one run still trims
+ * exactly as before.
+ *
+ * SCRUB EVERY STRING. This is the CLI's own stdout — a command echoing an env
+ * var, a read of a config file — riding the same uplink the answer does. Prose
+ * is scrubbed here; a tool event arrives already scrubbed by `toolEventOf`,
+ * which does it over a bounded window BEFORE its own caps for reasons its
+ * header states.
+ *
+ * IT IS A READOUT AND MUST NEVER FAIL A TURN. Every failure is swallowed, the
+ * timer is unref'd, and the final flush is bounded — a wedged uplink costs the
+ * tail of a trace, never the settle behind it.
+ */
+
+/** One batch every two seconds — the discipline the tab's narrator keeps, for
+ *  the same reason: a turn emits hundreds of entries and nobody is reading them
+ *  faster than that. */
+export const TRACE_FLUSH_MS = 2_000;
+/** Entries per POST. Matches the server's own per-batch cap. */
+export const TRACE_BATCH = 40;
+/** Entries held while the uplink is down. Past this the OLDEST go: a trace is
+ *  scrollback, and the newest steps are the ones somebody watching wants. The
+ *  drop is not silent — see the seq rule above. */
+export const TRACE_BUFFER = 120;
+/** Longest prose entry. The server clamps to the same number; doing it here too
+ *  means a pathological line never becomes the POST. */
+export const TRACE_PROSE_CAP = 300;
+
+/**
+ * ONE ATTEMPT AT ONE TURN, named.
+ *
+ * Short on purpose — it is an equality check and nothing else, never an id
+ * anybody resolves — and random rather than a counter, because the thing it has
+ * to be distinct from is the PREVIOUS PROCESS's attempt at the same turn, which
+ * a counter restarting at zero would collide with every time.
+ */
+function newRunId() {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36).slice(-4);
+}
+
+/**
+ * `post(body)` delivers one batch and resolves truthy when the entries may be
+ * forgotten — which deliberately includes a permanent refusal (an older server
+ * with no such route, a body the server will never accept). Resolving falsy
+ * keeps them queued for the next flush.
+ */
+export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run = newRunId() }) {
+  /** Entries not yet delivered. `base` is the ABSOLUTE index of queue[0] in
+   *  THIS RUN's stream, so `base + queue.length` is everything this relay has
+   *  ever accepted — sent, queued or shed. Absolute for the TURN is the
+   *  server's business: it rebases each run onto its own high-water mark. */
+  const queue = [];
+  let base = 0;
+  let dirty = false;
+  let timer = null;
+  let stopped = false;
+  /** The await chain. Every flush appends to it, so batches leave in order
+   *  however many callers ask at once. */
+  let chain = Promise.resolve();
+
+  const schedule = () => {
+    if (timer || stopped || !dirty) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void flush();
+    }, TRACE_FLUSH_MS);
+    timer.unref?.(); // never hold the process open for a readout
+  };
+
+  const push = (entry) => {
+    if (stopped || !entry) return;
+    queue.push(entry);
+    while (queue.length > TRACE_BUFFER) {
+      queue.shift();
+      base += 1; // the shed entry keeps its index — the gap is the record
+    }
+    dirty = true;
+    schedule();
+  };
+
+  const drain = async (deadlineMs) => {
+    const until = deadlineMs > 0 ? Date.now() + deadlineMs : 0;
+    while (queue.length) {
+      if (until && Date.now() > until) {
+        dirty = true;
+        return;
+      }
+      const entries = queue.slice(0, TRACE_BATCH);
+      const seq = base;
+      dirty = false;
+      let ok = false;
+      try {
+        ok = (await post({ agentId, turnId, run, seq, entries })) !== false;
+      } catch {
+        ok = false;
+      }
+      if (!ok) {
+        // Held, at the SAME seq: a retry the server has already seen is
+        // trimmed against its high-water mark rather than doubled.
+        dirty = true;
+        return;
+      }
+      queue.splice(0, entries.length);
+      base += entries.length;
+    }
+  };
+
+  const flush = (deadlineMs = 0) => {
+    chain = chain.then(() => drain(deadlineMs)).catch(() => {});
+    const done = chain;
+    void done.then(() => {
+      if (dirty) schedule();
+    });
+    return done;
+  };
+
+  return {
+    /** A prose line from the stream. `kind` is the daemon's activity vocabulary
+     *  (runtimes.mjs); anything that is not thinking or the model speaking is a
+     *  `note` — the honest bucket for a codex error line or an agy tool name,
+     *  rather than a wire value invented per runtime. */
+    prose(kind, text) {
+      const t = scrub(String(text ?? ''))
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, TRACE_PROSE_CAP);
+      if (!t) return;
+      push({ k: kind === 'think' ? 'think' : kind === 'say' ? 'say' : 'note', t });
+    },
+    /** One structured tool event, exactly as `toolEventOf` built it. A tool this
+     *  builder does not know returns null there and nothing is pushed here — a
+     *  card is never invented. */
+    tool(e) {
+      if (e && typeof e === 'object') push({ k: 'tool', e });
+    },
+    flush,
+    /** No more entries, no more timers. The queue survives so a final flush can
+     *  still deliver it. */
+    stop() {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+    /** For tests and nothing else: what has been accepted, where the next batch
+     *  would start, and which attempt this relay is. */
+    stats() {
+      return { run, seq: base, queued: queue.length, emitted: base + queue.length };
+    },
+  };
+}