flowviant 0.88.0 → 0.89.0

package/bin/lib/admission.mjs

@@ -23,7 +23,16 @@
  * ── 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
+ * the only time anyone hears about it is the moment it actually fires.
+ *
+ * NARROWED 2026-09-17, knowingly. The effective ceiling now rides the poll as
+ * `mt` and is shown in two places, and neither is a meter: project SETTINGS,
+ * beside the control that sets it — a dial has to say what it is currently
+ * worth or it is a control with no readout — and on the board ONLY while a real
+ * agent is being deferred, which is the "at the thing that is waiting, in the
+ * moment" carve-out this product already grants. What stays forbidden is the
+ * resting global chip and any statement of HEADROOM: "room for N more" is still
+ * dead, and the refusal below still names ACTIVITY and never the bound. 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
@@ -70,12 +79,98 @@
  * idempotent so doing both is the normal case rather than a bug.
  */
 
-import { MAX_CONCURRENT } from './config.mjs';
+import { MAX_CONCURRENT, MAX_CONCURRENT_FROM_ENV } from './config.mjs';
 import { pressureVerdict } from './resources.mjs';
 
+/**
+ * ── THE CEILING HAS THREE POSSIBLE AUTHORS (2026-09-17) ──
+ *
+ * The owner's box derived ONE, so every parallel agent serialized here with
+ * nothing but a per-agent pulse line to explain it: "thats why i was
+ * immediately confused. theres nothing telling me that i could only have one
+ * agent on the board." His fix was to move the dial into the product — "it
+ * shouldnt be a variable on the npx to make it friendly for non tech users. why
+ * cant it be on the web interface?" — so the roster reply may now carry
+ * `maxTurns`.
+ *
+ * THE ORDER IS ENV > SERVER > DERIVED, and the middle one is the new arrival:
+ *
+ *  · ENV WINS because an operator who typed `FLOWVIANT_MAX_CONCURRENT=2` at the
+ *    box is stating their last word about their own machine, and a control they
+ *    cannot see must not silently overrule it. This is the same posture the
+ *    daemon keeps everywhere else it is handed an instruction: the app decides
+ *    the product, the box decides the box.
+ *  · THE SERVER'S DIAL beats the derivation because the app is where every
+ *    decision in this product is made, and the derivation is a GUESS about
+ *    hardware — a good one, but one a person looking at their own machine is
+ *    entitled to overrule without opening a terminal.
+ *  · THE DERIVATION is the resting state, and it is what a project that has
+ *    never touched the dial gets. `null` — not 0, not NaN — is what "nobody
+ *    said" looks like, so the fallback is reached by ABSENCE rather than by a
+ *    sentinel number that could be mistaken for a bound.
+ *
+ * Pure, and exported, so the order can be proved without a server, a poll or a
+ * box of any particular size.
+ */
+export function pickMaxTurns({ env = null, server = null, derived = 1 } = {}) {
+  const clamp = (n) => {
+    const v = Number(n);
+    if (!Number.isFinite(v) || v < 1) return null;
+    return Math.min(Math.floor(v), 32);
+  };
+  return clamp(env) ?? clamp(server) ?? clamp(derived) ?? 1;
+}
+
+/**
+ * THE LAST NUMBER THE SERVER NAMED, or null.
+ *
+ * A module holder rather than a value threaded through `createWorkManager`,
+ * because the reader and the writer are two files apart and one poll apart: the
+ * POLL learns it (fleet.mjs) and every ADMISSION reads it, including the ones
+ * work.mjs takes in lanes fleet.mjs never sees. The alternative — passing it
+ * down — would mean the number that bound a spawn was whatever was current when
+ * the manager was CONSTRUCTED, which is exactly the frozen-at-startup bug
+ * `getBaseRef` and `getLeaseTtl` are getters to avoid.
+ */
+let serverMaxTurns = null;
+
+/**
+ * Record what the roster said. ANYTHING THAT IS NOT A USABLE NUMBER CLEARS IT,
+ * and both directions of that matter:
+ *
+ *  · a MALFORMED value must not become a ceiling — `Number('')` is 0 and a
+ *    ceiling of 0 refuses every spawn forever, which is a machine that has
+ *    silently stopped working;
+ *  · an ABSENT value is how "Auto" is spelled on the wire (the server simply
+ *    does not send the key), and how an older SERVER looks. Both mean the
+ *    derivation stands, so absence has to clear a value set by an earlier poll
+ *    rather than leaving the last dial standing forever — otherwise turning the
+ *    dial back to Auto would be unspellable.
+ */
+export function setServerMaxTurns(raw) {
+  const v = Number(raw);
+  serverMaxTurns = Number.isFinite(v) && v >= 1 ? Math.min(Math.floor(v), 32) : null;
+  return serverMaxTurns;
+}
+
+/** THE NUMBER IN FORCE RIGHT NOW — read per admission, and reported to the app
+ *  on the poll as `mt`, because it is the bound the refusal is about. */
+export function effectiveMaxTurns() {
+  return pickMaxTurns({
+    env: MAX_CONCURRENT_FROM_ENV ? MAX_CONCURRENT : null,
+    server: serverMaxTurns,
+    derived: MAX_CONCURRENT,
+  });
+}
+
 export function createAdmission({
   liveTurnCount,
-  maxConcurrent = MAX_CONCURRENT,
+  /** A NUMBER OR A FUNCTION. The function form is the live one: the ceiling can
+   *  move between two polls now, so a value captured when the manager was built
+   *  would be the dial as it stood at daemon start for the rest of the process.
+   *  A number is still accepted, and every test here passes one — the whole
+   *  point of injecting it. */
+  maxConcurrent = effectiveMaxTurns,
   verdict = pressureVerdict,
 } = {}) {
   /** Slots taken by a decision whose process does not exist yet. A Set of
@@ -88,7 +183,18 @@ export function createAdmission({
   function admit(level) {
     const counted = Number(liveTurnCount?.() ?? 0);
     const live = (Number.isFinite(counted) ? counted : 0) + holding.size;
-    if (live >= maxConcurrent)
+    /**
+     * READ PER ADMISSION, and falling back to the DERIVED number rather than to
+     * nothing. A ceiling that comes out NaN is not a permissive ceiling, it is
+     * NO ceiling — `live >= NaN` is false every time — which is precisely the
+     * unguarded spawn loop that froze somebody's computer. The local derivation
+     * is the one value in this process that cannot be garbage.
+     */
+    const asked =
+      typeof maxConcurrent === 'function' ? Number(maxConcurrent()) : Number(maxConcurrent);
+    const ceiling =
+      Number.isFinite(asked) && asked >= 1 ? Math.min(Math.floor(asked), 32) : MAX_CONCURRENT;
+    if (live >= ceiling)
       return {
         reason: `the machine is already running ${live} CLI turn${live === 1 ? '' : 's'}`,
       };

package/bin/lib/config.mjs

@@ -118,6 +118,16 @@ export const MACHINE = machineLimits();
  * tests want, and this process is the only party that can see the cores, the
  * RAM and the fan.
  *
+ * …AND SINCE 2026-09-17 THE APP MAY NAME A NUMBER TOO, which narrows that
+ * sentence rather than reversing it. What stays true is that the DERIVATION
+ * belongs here and that the enforcement is local: a ceiling that only exists as
+ * a request is not one. What changed is that a person may now say "run two at
+ * once" without going to the box, because the owner's answer to being stuck at
+ * one was "it shouldnt be a variable on the npx to make it friendly for non
+ * tech users. why cant it be on the web interface?". The precedence — env, then
+ * the app's dial, then this derivation — lives in `pickMaxTurns`
+ * (admission.mjs), and this value is what that falls back to.
+ *
  * 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.
@@ -142,23 +152,56 @@ export const MACHINE = machineLimits();
  *
  * MEMORY is the bound, not cores. Cores oversubscribe gracefully (everything
  * gets slower); memory does not (something dies, and not necessarily the
- * offender). A task is a Claude session plus a dev server plus whatever the
- * test runner spawns — call it 2GB, keep 2GB back for the operating system,
- * and let cores cap it only when they are the scarcer thing.
- *
- * This used to be `min(4, cores/2)` — half the cores because "the user is
- * working on this machine too", and a hard 4 because a personal Claude plan
- * ran out before the CPU did. Both were laptop assumptions. The machine is now
- * a box the project leaves running, so it reserves one core rather than half of
- * them, and the ceiling is what the hardware can hold rather than a guess about
- * somebody's plan.
+ * offender).
+ *
+ * BOTH HALVES WERE RETUNED 2026-09-17, after the owner's box computed ONE and
+ * he met it as "theres nothing telling me that i could only have one agent on
+ * the board". The old numbers were `floor((memGB − 2) / 2)` and `cores − 1`,
+ * and each was a guess this file had stopped examining:
+ *
+ *  · 2GB PER TURN assumed every turn drags a dev server and a test runner
+ *    behind it. Most do not — an agent turn is a CLI that reads, edits and
+ *    commits, and it is API-bound for nearly all of its life. 1GB per turn with
+ *    the same 2GB held back for the operating system is the honest sizing, and
+ *    the PRESSURE guard (resources.mjs) is what catches the turn that really
+ *    does hold gigabytes: it measures at the moment of spawning, which is a
+ *    thing a static divisor cannot do.
+ *  · `cores − 1` is the laptop assumption this comment already claims to have
+ *    retired, reborn one line down. The paragraph above says cores
+ *    OVERSUBSCRIBE GRACEFULLY and memory is what does not — so cores must not
+ *    be the half that binds first. On a 2-core VM `cores − 1` was 1, and that
+ *    single subtraction is the whole reason the owner's machine serialized
+ *    every agent. `cores * 2` lets the scheduler do what it is for, and memory
+ *    stays the bound that actually refuses.
+ *
+ * `min(32, …)` and the env override are untouched: the hard 32 is a runaway
+ * bound on a box, not a product decision, and an operator who typed a number at
+ * the machine gets exactly that number.
+ */
+export function deriveMaxConcurrent(memBytes, cores) {
+  const byMem = Math.floor(memBytes / 2 ** 30 - 2);
+  const byCpu = Number(cores) * 2;
+  return Math.max(1, Math.min(32, byMem, byCpu));
+}
+
+/**
+ * WAS THE ENV VAR THE SOURCE? — the one fact the precedence rule cannot
+ * reconstruct afterwards.
+ *
+ * `FLOWVIANT_MAX_CONCURRENT=4` and a box that happens to derive 4 produce the
+ * identical number, and they are not the same statement: one is an operator's
+ * last word and must outrank the app's dial, the other is a default the app may
+ * override. See `pickMaxTurns` in admission.mjs for what is done with it.
  */
+export const MAX_CONCURRENT_FROM_ENV = (() => {
+  const asked = Number(process.env.FLOWVIANT_MAX_CONCURRENT);
+  return Number.isFinite(asked) && asked >= 1;
+})();
+
 export const MAX_CONCURRENT = (() => {
   const asked = Number(process.env.FLOWVIANT_MAX_CONCURRENT);
   if (Number.isFinite(asked) && asked >= 1) return Math.min(Math.floor(asked), 32);
-  const byMem = Math.floor((MACHINE.memBytes / 2 ** 30 - 2) / 2);
-  const byCpu = MACHINE.cores - 1;
-  return Math.max(1, Math.min(32, byMem, byCpu));
+  return deriveMaxConcurrent(MACHINE.memBytes, MACHINE.cores);
 })();
 export const IDLE_SECONDS = Number(process.env.IDLE_SECONDS || 30);
 // Live mode: after this long idle-parked on a blocker, tear the session down to

package/bin/lib/fleet.mjs

@@ -85,6 +85,7 @@ import {
   THINK_MARKER,
 } from './runtimes.mjs';
 import { createWorkManager } from './work.mjs';
+import { effectiveMaxTurns, setServerMaxTurns } from './admission.mjs';
 import { scanLocalSessions, ourConversationIds } from './localSessions.mjs';
 import { repoState } from './repoState.mjs';
 import { claudeAuthContext } from './claudeAuth.mjs';
@@ -259,6 +260,34 @@ async function fetchRoster(
   try {
     if (churnHold !== undefined) {
       url.searchParams.set('pr', churnHold ? String(churnHold.reason).slice(0, 160) : '-');
+      /**
+       * …AND THE BOUND THE REFUSAL IS ABOUT (2026-09-17, `mt`).
+       *
+       * THIS AMENDS THE PARAGRAPH DIRECTLY ABOVE, which says the relayed
+       * sentence "names ACTIVITY … never the ceiling, never headroom". That
+       * rule was written to stop a capacity meter, and it succeeded so
+       * completely that a machine which could only ever run ONE turn had no way
+       * to say so — the owner, verbatim: "we should have ui indicating this on
+       * the board view and a ui indicating or showing the agent as waiting or
+       * queued as a result of that resource constraint. thats why i was
+       * immediately confused. theres nothing telling me that i could only have
+       * one agent on the board."
+       *
+       * So the ceiling crosses the wire, and the narrow shape that survives is
+       * the same carve-out the sentence beside it already lives under: it is
+       * shown in SETTINGS (beside the dial that sets it — a control with no
+       * readout is not a control) and on the BOARD only while a real agent is
+       * actually being deferred. Never a resting chip, and never headroom:
+       * nothing anywhere subtracts this from the live count to advertise room.
+       *
+       * It rides the `pr` gate deliberately — this is the bound that admission
+       * measured against, so a poll with no admission to ask has no effective
+       * ceiling to report either, and absence keeps meaning "an older daemon".
+       * `capacity` above is the DERIVED number and predates the dial; it is a
+       * dispatch-era fossil the server ignores, and the two are not the same
+       * fact.
+       */
+      url.searchParams.set('mt', String(effectiveMaxTurns()));
     }
   } catch {
     /* a readout — the poll must never fail on one */
@@ -1933,6 +1962,20 @@ export async function runFleetDaemon() {
       }
     }
     if (roster.mcpUrl) mcpUrl = roster.mcpUrl;
+    /**
+     * HOW MANY TURNS THE APP SAYS THIS MACHINE MAY RUN (2026-09-17).
+     *
+     * Set on EVERY poll, including the ones that carry no key — absence is how
+     * "Auto" is spelled and how an older server looks, and both mean the
+     * derivation stands. Leaving a previous value in place on an absent key
+     * would make turning the dial back to Auto unspellable, which is the
+     * learn-only bug `listSessionPlaces` already paid for once.
+     *
+     * HERE, ABOVE EVERY LANE, so a number that arrived on this poll binds the
+     * spawns this same reconcile is about to decide. The `mt` the NEXT poll
+     * reports is therefore the value that was actually in force.
+     */
+    setServerMaxTurns(roster.maxTurns);
     if (roster.project?.id) wikiProjectId = roster.project.id; // keys the vault dir
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
     // A COMMANDED STOP OUTRANKS AN UPDATE, and that ordering is the whole reason

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.88.0",
+  "version": "0.89.0",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {