flowviant 0.108.1 → 0.109.0

package/bin/lib/claudeAuth.mjs

@@ -58,6 +58,9 @@
 
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+// A stamp that may be seconds or milliseconds, to ISO — or null. Shared with
+// runtimeLimits.mjs, which reads the plan windows' reset stamps the same way.
+import { isoFromStamp } from './isoStamp.mjs';
 
 /**
  * The variables that can carry auth into the CLI from the environment.
@@ -72,16 +75,6 @@ export const AUTH_ENV_VARS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAU
 /** Claude Code's OAuth store, relative to the HOME the CLI will be handed. */
 const CRED_REL = ['.claude', '.credentials.json'];
 
-/** A stamp that may be seconds or milliseconds, to ISO — or null if it is
- *  neither. Same tolerance the rest of the daemon applies to numbers it did not
- *  write: an unreadable stamp is ABSENT, never zero and never "now". */
-function isoFromStamp(v) {
-  const n = Number(v);
-  if (!Number.isFinite(n) || n <= 0) return null;
-  const ms = n > 1e11 ? n : n * 1000;
-  const d = new Date(ms);
-  return Number.isNaN(d.getTime()) ? null : d.toISOString();
-}
 
 /**
  * What the CLI on this machine will resolve, as far as it can be seen without

package/bin/lib/claudeStream.mjs

@@ -82,7 +82,7 @@ export function usageFromResult(ev) {
 // container that reports no spend, which is indistinguishable from an older
 // daemon by design. A callback that is silent when it breaks has to be called
 // directly by something.
-export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage }) {
+export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage, onRateLimit }) {
   let ev;
   try {
     ev = JSON.parse(line);
@@ -203,5 +203,18 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
       const msg = listed || ev.error?.message || ev.error || ev.subtype;
       appendText(`${typeof msg === 'string' ? msg : JSON.stringify(msg)}\n`);
     }
+  } else if (ev.type === 'rate_limit_event') {
+    /**
+     * HOW CLOSE THE PLAN IS TO ITS LIMIT, IN THE CLI'S OWN NUMBERS (0.109.0).
+     *
+     * MEASURED on Claude Code 2.1.283, 2026-09-28: an ordinary turn carries
+     * one (status `allowed` at 3% — not only near a threshold), BEFORE its
+     * `result` line — `{status, resetsAt, rateLimitType, unifiedWindows:
+     * {five_hour: {utilization, resetsAt}, seven_day: {…}}, …}`. It was
+     * dropped by the fall-through until now. Handed over whole
+     * (runtimeLimits.mjs reads it); it is not the model speaking, so it
+     * appends no text and emits no activity.
+     */
+    if (ev.rate_limit_info && typeof ev.rate_limit_info === 'object') onRateLimit?.(ev.rate_limit_info);
   }
 }

package/bin/lib/fleetRoster.mjs

@@ -33,9 +33,18 @@ import { detectRuntimes, runtimesReport } from './runtimeDetection.mjs';
 import { knownMcpServers, knownSkills } from './runtimeCapabilities.mjs';
 import { effectiveMaxTurns } from './admission.mjs';
 import { runtimeOfferings } from './runtimeOfferings.mjs';
+import { RUNTIME_LIMITS_PARAM_MAX, runtimeLimitsReport } from './runtimeLimits.mjs';
 
 let warnedEnvIdentity = false;
 
+/**
+ * HOW LONG THE POLL'S URL MAY GROW BEFORE AN OPTIONAL READOUT STAYS HOME.
+ * The runtime offerings and the plan-limit report are each added only while
+ * the whole URL stays under this; the identity and admission params after
+ * them are short and always ride.
+ */
+const POLL_URL_BUDGET = 14_000;
+
 /**
  * HAS THIS PROCESS ALREADY ASKED FOR THE MACHINE? (0.91.0)
  *
@@ -255,11 +264,37 @@ export async function fetchRoster(
       for (const [param, report] of Object.entries(offerings)) {
         if (Object.keys(report).length) {
           const payload = JSON.stringify(report);
-          if (payload.length <= 8_000 && url.toString().length + encodeURIComponent(payload).length <= 14_000) url.searchParams.set(param, payload);
+          if (payload.length <= 8_000 && url.toString().length + encodeURIComponent(payload).length <= POLL_URL_BUDGET) url.searchParams.set(param, payload);
         }
       }
     } catch { /* local readouts never fail the poll */ }
   }
+  /**
+   * HOW CLOSE EACH CLI'S PLAN IS TO ITS LIMIT (`rtl`, 0.109.0) — the vendor's
+   * own numbers, learned off turns this daemon already ran (runtimeLimits.mjs):
+   * `{claude?, codex?}`, each `{plan, status, at, windows: [{id, minutes,
+   * usedPct, resetsAt, at}]}`.
+   *
+   * A DAEMON→SERVER REPORT, so no floor, and the three states the other
+   * learned readouts keep: NOT SENT until something was learned (absent is
+   * "nothing learned yet" as much as "an older daemon"), a report once one
+   * was. Bounded twice — the report's own byte cap, the app's
+   * `RUNTIME_LIMITS_PARAM_MAX`, and the URL budget, where it is the readout
+   * that stays home first: nothing else on the poll yields to it.
+   */
+  try {
+    const limits = runtimeLimitsReport();
+    if (limits) {
+      const payload = JSON.stringify(limits);
+      if (
+        Buffer.byteLength(payload, 'utf8') <= RUNTIME_LIMITS_PARAM_MAX &&
+        url.toString().length + encodeURIComponent(payload).length + 5 <= POLL_URL_BUDGET
+      )
+        url.searchParams.set('rtl', payload);
+    }
+  } catch {
+    /* a readout — the poll must never fail on one */
+  }
   // THIS BOX'S IDENTITY — `envpub`, and since 2026-09-21 nothing else.
   //
   // It carried two more params while the secrets vault existed: `envv` (the

package/bin/lib/isoStamp.mjs

@@ -0,0 +1,23 @@
+/**
+ * AN EPOCH STAMP THE DAEMON DID NOT WRITE, AS ISO — or null.
+ *
+ * One home (2026-09-28) because two readers of other programs' files need the
+ * same tolerance: `claudeAuth.mjs` reads Claude Code's OAuth expiries, and
+ * `runtimeLimits.mjs` reads the plan windows' `resetsAt` (Claude's stream) and
+ * `resets_at` (Codex's rollout). Neither vendor promises a unit, so a value
+ * above 1e11 is read as milliseconds and anything else as seconds — 1e11
+ * seconds is the year 5138, and 1e11 milliseconds is 1973, so the two ranges
+ * a real stamp can fall in never meet.
+ *
+ * AN UNREADABLE STAMP IS ABSENT, never zero and never "now": a non-number, a
+ * NaN, an Infinity, zero or a negative all answer null. A leaf module on
+ * purpose — it imports nothing, so either reader may import it without a cycle.
+ */
+export function isoFromStamp(v) {
+  if (v === null || v === undefined || v === '' || typeof v === 'boolean') return null;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const ms = n > 1e11 ? n : n * 1000;
+  const d = new Date(ms);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}

package/bin/lib/runTurn.mjs

@@ -17,6 +17,7 @@ import { resolveTurnProfile } from './turnProfile.mjs';
 import { claudePermFor } from './claudePosture.mjs';
 import { handleStreamLine } from './claudeStream.mjs';
 import { never, workLanesStopped } from './standDownGate.mjs';
+import { learnCodexLimits, recordClaudeRateLimit } from './runtimeLimits.mjs';
 
 /**
  * THE ENVIRONMENT A CLI TURN IS SPAWNED WITH — the daemon's own, plus the
@@ -48,7 +49,7 @@ export function cliEnv(mcpEnv) {
 // `onActivity` so the caller can forward progress. Build-agent turns leave it
 // off and keep the raw text passthrough + line sentinels.
 export function runTurn(opts) {
-  const { prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, agentTools, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onToolEvent, onInit, onUsage, onThreadId, onAnswer, vaultDir, knowledgeDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId } = opts;
+  const { prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, agentTools, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onToolEvent, onInit, onUsage, onRateLimit, onThreadId, onAnswer, vaultDir, knowledgeDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId } = opts;
   /**
    * AFTER THE TEARDOWN, NO TURN STARTS AND NO TURN ENDS (standDownGate.mjs).
    * A stand-down that drains a deploy keeps this process alive; without this
@@ -229,16 +230,37 @@ export function runTurn(opts) {
       const appendText = (t) => {
         out += t;
       };
+      /**
+       * THE PLAN'S WINDOWS, LEARNED OFF EVERY TURN THIS DAEMON RUNS (0.109.0).
+       *
+       * This is the one spawn point — agent turns, Terminal tabs, capture
+       * chats, the planner, the pre-review and the wiki all come through here
+       * — so it is the one place that sees every CLI's word on its plan.
+       * Claude says it on the stream (`rate_limit_event`), recorded as it
+       * arrives; a caller's own `onRateLimit` still hears it. Codex writes it
+       * into the thread's rollout file instead, so the thread this turn spoke
+       * under (announced on `thread.started`, else the one it resumed) is read
+       * AFTER the child closes, on the next tick — the turn's answer never
+       * waits on a file read. See runtimeLimits.mjs.
+       */
+      const onRate = (info) => {
+        recordClaudeRateLimit(info);
+        onRateLimit?.(info);
+      };
+      let codexThread = rt.id === 'codex' && typeof resumeThreadId === 'string' ? resumeThreadId : null;
       /** One line of the child's stdout, in whichever dialect it speaks. */
       const onLine = (line) => {
         if (!rt.parse)
-          return handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage });
+          return handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage, onRateLimit: onRate });
         const ev = rt.parse(line, cwd);
         if (!ev) return;
         // The conversation id, when the runtime announces one (codex's
         // thread.started). Purely additive: callers that pass no onThreadId —
         // every dispatch path — see zero behavior change.
-        if (ev.threadId) onThreadId?.(ev.threadId);
+        if (ev.threadId) {
+          if (rt.id === 'codex') codexThread = ev.threadId;
+          onThreadId?.(ev.threadId);
+        }
         // The runtime's own token count (codex's `turn.completed`) — the same
         // `onUsage` Claude's result event feeds, so a caller charges a turn
         // identically whichever CLI ran it.
@@ -294,6 +316,11 @@ export function runTurn(opts) {
       child.on('close', () => {
         if (buf.trim()) onLine(buf);
         resolve(out);
+        // After the answer is handed back, never before it: see `onRate`.
+        if (codexThread) {
+          const thread = codexThread;
+          setImmediate(() => void learnCodexLimits(thread));
+        }
       });
       return;
     }

package/bin/lib/runtimeLimits.mjs

@@ -0,0 +1,365 @@
+/**
+ * HOW CLOSE EACH CLI'S PLAN IS TO ITS LIMIT, IN THE VENDOR'S OWN NUMBERS
+ * (2026-09-28, 0.109.0) — a per-process cache of what the CLIs said about
+ * their plan windows, relayed on the roster poll as `rtl`.
+ *
+ * THE OWNER'S CARVE-OUT, stated once here because every reader leans on it:
+ * "show activity, never capacity" still stands for Flowviant's own bounds. A
+ * plan window is not Flowviant's capacity — it is the VENDOR measuring its own
+ * plan, and this file only carries that measurement to Project settings ›
+ * Machines, where it reads as "used", never "left" or "free". Nothing here
+ * decides, gates, parks or schedules anything off these numbers.
+ *
+ * TWO SOURCES, ONE SHAPE:
+ *
+ *  · CLAUDE CODE says it on the stream. Every `-p --output-format stream-json`
+ *    turn carries a `rate_limit_event` BEFORE its `result` line, and the
+ *    daemon used to drop it. MEASURED on Claude Code 2.1.283, 2026-09-28
+ *    (`claude -p "say hi" --model haiku --output-format stream-json
+ *    --verbose`): it fires on an ordinary turn (status `allowed` at 3%), not
+ *    only near a threshold; `utilization` is a 0–1 FRACTION (hence
+ *    CLAUDE_UTILIZATION_SCALE = 100 — one constant, no crossover heuristic);
+ *    `resetsAt` is epoch SECONDS; `unifiedWindows` names `five_hour` and
+ *    `seven_day`. claudeStream.mjs hands the event's `rate_limit_info` here.
+ *  · CODEX says it in a file. `codex exec --json` (0.156.1) puts no limits on
+ *    stdout; its rollout `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<thread>
+ *    .jsonl` (folder = the LOCAL date the thread STARTED; a resumed thread
+ *    appends to its original file) carries `event_msg` → `token_count`
+ *    payloads with `rate_limits: {primary, secondary, plan_type, …}`. After a
+ *    codex turn closes, runTurn.mjs asks `learnCodexLimits` to read the tail.
+ *
+ * THREE STATES, the way every machine report here keeps them: null = nothing
+ * learned (the param is not sent), a measured value, and — inside a window —
+ * null for a number the CLI did not give. An absent or garbage percentage is
+ * NULL, never 0: "0% used" is a claim, and nobody measured it.
+ *
+ * THE BOUNDS are the app's (`packages/shared/src/schemas/runtimeLimits.ts`
+ * exports the same four names and values; `scripts/check-app-parity.mjs`
+ * rule 7 holds them equal): the server re-applies them, so a looser copy here
+ * would only have a report dropped at the boundary.
+ */
+
+import { readdir, open, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isoFromStamp } from './isoStamp.mjs';
+import { claudeAuthContext } from './claudeAuth.mjs';
+import { detectRuntimes } from './runtimeDetection.mjs';
+import { CODEX_THREAD_RE } from './workSessionRuntime.mjs';
+
+/** Claude's `utilization` is a fraction (0.03 = 3%) — MEASURED, see above. */
+export const CLAUDE_UTILIZATION_SCALE = 100;
+/** The whole `rtl` param, as JSON bytes. */
+export const RUNTIME_LIMITS_PARAM_MAX = 2000;
+/** Windows per CLI entry. */
+export const RUNTIME_LIMIT_WINDOWS_MAX = 6;
+/** A window id's length (`five_hour`, `seven_day`, `m1440`). */
+export const RUNTIME_LIMIT_ID_MAX = 40;
+/** A plan slug's length (`max`, `pro`, `prolite`). */
+export const RUNTIME_LIMIT_PLAN_MAX = 32;
+
+const WINDOW_ID = new RegExp(`^[a-z0-9_]{1,${RUNTIME_LIMIT_ID_MAX}}$`);
+const PLAN_SLUG = new RegExp(`^[A-Za-z0-9_-]{1,${RUNTIME_LIMIT_PLAN_MAX}}$`);
+const CLAUDE_STATUSES = new Set(['allowed', 'allowed_warning', 'rejected']);
+/** The two windows Claude names whose length is known; any other is null. */
+const CLAUDE_WINDOW_MINUTES = { five_hour: 300, seven_day: 10080 };
+/** A percentage outside this is garbage, not a reading. */
+const PCT_MAX = 1000;
+/** The rollout's tail — the last token_count sits near the end of a file
+ *  that grows to many megabytes over a long thread. */
+const ROLLOUT_TAIL_BYTES = 256 * 1024;
+/** Day directories walked for a rollout, newest first. */
+const ROLLOUT_DAYS_MAX = 62;
+const PLAN_TTL_MS = 60_000;
+
+const iso = (ms) => new Date(ms).toISOString();
+
+/** A percentage to one decimal, or null — never 0 for "not said". */
+function pctOf(v, scale = 1) {
+  if (v === null || v === undefined || v === '' || typeof v === 'boolean') return null;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < 0) return null;
+  const pct = Math.round(n * scale * 10) / 10;
+  return pct <= PCT_MAX ? pct : null;
+}
+
+const planOf = (v) => (typeof v === 'string' && PLAN_SLUG.test(v) ? v : null);
+
+/** Per CLI: `{ status, at (ms), plan?, windows: Map<id, window> }`, or null. */
+let claudeState = null;
+let codexState = null;
+
+/** Keep a window map to the bound, dropping the oldest reading first. */
+function capWindows(windows) {
+  while (windows.size > RUNTIME_LIMIT_WINDOWS_MAX) {
+    let oldest = null;
+    for (const w of windows.values()) if (!oldest || w.at < oldest.at) oldest = w;
+    windows.delete(oldest.id);
+  }
+}
+
+/**
+ * RECORD WHAT CLAUDE CODE'S `rate_limit_event` SAID.
+ *
+ * `unifiedWindows` names every window the plan has, each with its own
+ * utilization and reset; an older CLI that sends only the single
+ * `rateLimitType` window (with whatever `utilization`/`resetsAt` ride beside
+ * it) is read as that one window. Windows MERGE by id, each with its own `at`:
+ * an event that speaks about one window never erases what an earlier event
+ * said about another. The status is the latest event's.
+ */
+export function recordClaudeRateLimit(info, now = Date.now()) {
+  if (!info || typeof info !== 'object' || Array.isArray(info)) return;
+  const at = iso(now);
+  const state = (claudeState ??= { status: null, at: null, windows: new Map() });
+  const put = (id, utilization, resetsAt) => {
+    if (typeof id !== 'string' || !WINDOW_ID.test(id)) return;
+    state.windows.set(id, {
+      id,
+      minutes: CLAUDE_WINDOW_MINUTES[id] ?? null,
+      usedPct: pctOf(utilization, CLAUDE_UTILIZATION_SCALE),
+      resetsAt: isoFromStamp(resetsAt),
+      at,
+    });
+  };
+  const unified = info.unifiedWindows;
+  if (unified && typeof unified === 'object' && !Array.isArray(unified)) {
+    for (const [id, w] of Object.entries(unified)) {
+      if (w && typeof w === 'object') put(id, w.utilization, w.resetsAt);
+    }
+  } else if (typeof info.rateLimitType === 'string') {
+    put(info.rateLimitType, info.utilization, info.resetsAt);
+  }
+  capWindows(state.windows);
+  state.status = CLAUDE_STATUSES.has(info.status) ? info.status : 'other';
+  state.at = at;
+}
+
+/**
+ * RECORD WHAT A CODEX ROLLOUT'S `rate_limits` SAID.
+ *
+ * `primary` and `secondary` are the plan's windows, named by their length:
+ * 300 minutes is `five_hour` and 10080 is `seven_day` (Claude's own ids, so
+ * the app words them once), any other length `m<N>`. The snapshot is WHOLE —
+ * each token_count carries every window the plan has — so it replaces the
+ * previous one rather than merging: a window the plan no longer has must not
+ * linger. `resets_at` is seconds. Codex gives the plan slug itself
+ * (`plan_type`); `rate_limit_reached_type` is non-null once a window is hit.
+ */
+export function recordCodexRateLimits(rl, now = Date.now()) {
+  if (!rl || typeof rl !== 'object' || Array.isArray(rl)) return;
+  const at = iso(now);
+  const windows = new Map();
+  for (const [slot, w] of [['primary', rl.primary], ['secondary', rl.secondary]]) {
+    if (!w || typeof w !== 'object') continue;
+    const m = Number(w.window_minutes);
+    const minutes = Number.isInteger(m) && m > 0 ? m : null;
+    const id = minutes === 300 ? 'five_hour' : minutes === 10080 ? 'seven_day' : minutes ? `m${minutes}` : slot;
+    if (!WINDOW_ID.test(id)) continue;
+    windows.set(id, { id, minutes, usedPct: pctOf(w.used_percent), resetsAt: isoFromStamp(w.resets_at), at });
+  }
+  codexState = {
+    plan: planOf(rl.plan_type),
+    status: rl.rate_limit_reached_type != null ? 'rejected' : 'allowed',
+    at,
+    windows,
+  };
+}
+
+/** threadId → rollout path, per CODEX_HOME. Bounded: a long-lived daemon
+ *  runs many threads and the map must not grow with them. */
+const rolloutPaths = new Map();
+const ROLLOUT_PATHS_MAX = 64;
+
+const newestFirst = async (dir, re) => {
+  try {
+    return (await readdir(dir)).filter((n) => re.test(n)).sort().reverse();
+  } catch {
+    return [];
+  }
+};
+
+/** Find `rollout-…-<threadId>.jsonl` by NAME — the id is matched against
+ *  what `readdir` returned and never joined into a path. */
+async function findRollout(root, threadId) {
+  const suffix = `-${threadId}.jsonl`;
+  let days = 0;
+  for (const y of await newestFirst(root, /^\d{4}$/)) {
+    for (const m of await newestFirst(join(root, y), /^\d{2}$/)) {
+      for (const d of await newestFirst(join(root, y, m), /^\d{2}$/)) {
+        if (++days > ROLLOUT_DAYS_MAX) return null;
+        const dayDir = join(root, y, m, d);
+        const hit = (await newestFirst(dayDir, /^rollout-.*\.jsonl$/)).find((n) => n.endsWith(suffix));
+        if (hit) return join(dayDir, hit);
+      }
+    }
+  }
+  return null;
+}
+
+/** The last token_count's non-null `rate_limits` in the file's tail, or null. */
+async function lastRateLimits(file) {
+  const fh = await open(file, 'r');
+  try {
+    const { size } = await fh.stat();
+    const len = Math.min(size, ROLLOUT_TAIL_BYTES);
+    const buf = Buffer.alloc(len);
+    await fh.read(buf, 0, len, size - len);
+    const lines = buf.toString('utf8').split('\n');
+    // A tail that starts mid-file starts mid-line: that first piece is not JSON.
+    if (size > len) lines.shift();
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i];
+      if (!line.includes('"token_count"') || !line.includes('"rate_limits"')) continue;
+      let ev;
+      try {
+        ev = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const p = ev?.payload;
+      if (p?.type === 'token_count' && p.rate_limits && typeof p.rate_limits === 'object') return p.rate_limits;
+    }
+    return null;
+  } finally {
+    await fh.close();
+  }
+}
+
+/**
+ * LEARN A CODEX THREAD'S PLAN WINDOWS FROM ITS ROLLOUT, after its turn closed.
+ *
+ * Best-effort from end to end, and it never throws: an id of the wrong shape,
+ * a missing CODEX_HOME, a rollout older than the walk, an unreadable file or a
+ * tail with no `rate_limits` all change nothing. Returns whether it learned.
+ */
+export async function learnCodexLimits(threadId, { env = process.env, now } = {}) {
+  try {
+    if (typeof threadId !== 'string' || !CODEX_THREAD_RE.test(threadId)) return false;
+    const root = join(env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
+    const key = `${root}\0${threadId}`;
+    let file = rolloutPaths.get(key) ?? null;
+    if (file) {
+      try {
+        await stat(file);
+      } catch {
+        rolloutPaths.delete(key);
+        file = null;
+      }
+    }
+    if (!file) {
+      file = await findRollout(root, threadId);
+      if (!file) return false;
+      rolloutPaths.set(key, file);
+      if (rolloutPaths.size > ROLLOUT_PATHS_MAX) rolloutPaths.delete(rolloutPaths.keys().next().value);
+    }
+    const rl = await lastRateLimits(file);
+    if (!rl) return false;
+    recordCodexRateLimits(rl, now ?? Date.now());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * CLAUDE'S PLAN SLUG (`max`, `pro`…) off the OAuth store `claudeAuth.mjs`
+ * already reads — never a token, only the plan name it keeps. Read at most
+ * once a minute; null when unknown (a keychain machine, an env-var key).
+ */
+let planMemo = null;
+export function claudePlanReading(now = Date.now()) {
+  if (planMemo && now - planMemo.readAt < PLAN_TTL_MS) return planMemo;
+  let plan = null;
+  try {
+    plan = planOf(claudeAuthContext().subscriptionType);
+  } catch {
+    plan = null;
+  }
+  planMemo = { plan, readAt: now };
+  return planMemo;
+}
+export function claudePlan() {
+  return claudePlanReading().plan;
+}
+
+const windowOrder = (a, b) =>
+  (a.minutes ?? Infinity) - (b.minutes ?? Infinity) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+/** One CLI's entry on the wire — every key present, newest windows kept. */
+function entryOf({ plan, status, at, windows }) {
+  const list = [...windows.values()]
+    .filter((w) => WINDOW_ID.test(w.id))
+    .sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0))
+    .slice(0, RUNTIME_LIMIT_WINDOWS_MAX)
+    .sort(windowOrder)
+    .map((w) => ({ id: w.id, minutes: w.minutes, usedPct: w.usedPct, resetsAt: w.resetsAt, at: w.at }));
+  return { plan: planOf(plan), status: status ?? null, at: at ?? null, windows: list };
+}
+
+const bytes = (v) => Buffer.byteLength(JSON.stringify(v), 'utf8');
+
+/**
+ * THE REPORT, FITTED TO `maxBytes`: windows are dropped oldest reading first
+ * until it fits, and a report that still does not fit with none left is null
+ * (not sent) rather than cut mid-entry. Pure; exported for its test.
+ */
+export function fitRuntimeLimits(report, maxBytes = RUNTIME_LIMITS_PARAM_MAX) {
+  if (!report) return null;
+  const out = Object.fromEntries(
+    Object.entries(report).map(([k, e]) => [k, { ...e, windows: [...(e.windows ?? [])] }])
+  );
+  while (bytes(out) > maxBytes) {
+    let oldest = null;
+    for (const [k, e] of Object.entries(out)) {
+      e.windows.forEach((w, i) => {
+        if (!oldest || String(w.at) < String(oldest.w.at)) oldest = { k, i, w };
+      });
+    }
+    if (!oldest) return null;
+    out[oldest.k].windows.splice(oldest.i, 1);
+  }
+  return out;
+}
+
+/**
+ * WHAT THE ROSTER POLL SENDS AS `rtl` — `{ claude?, codex? }`, or null when
+ * nothing is learned.
+ *
+ * Claude's entry needs Claude INSTALLED here (the detection the poll already
+ * runs) and something to say: its plan from the OAuth store, or a window a
+ * turn reported. A plan with no window yet has no status to relay, so its
+ * `status` is null — unknown, never a guessed `allowed`. Codex's entry exists
+ * once a rollout taught it. `detected` and `plan` are the test's handles.
+ */
+export function runtimeLimitsReport({ detected, plan, now = Date.now() } = {}) {
+  const out = {};
+  let claudeInstalled = false;
+  try {
+    claudeInstalled = Boolean((detected ?? detectRuntimes()).find((d) => d.id === 'claude')?.installed);
+  } catch {
+    claudeInstalled = false;
+  }
+  if (claudeInstalled) {
+    const reading = plan === undefined ? claudePlanReading(now) : { plan: planOf(plan), readAt: now };
+    const learned = claudeState && claudeState.windows.size > 0;
+    if (reading.plan || learned) {
+      out.claude = entryOf({
+        plan: reading.plan,
+        status: claudeState?.status ?? null,
+        at: claudeState?.at ?? iso(reading.readAt),
+        windows: claudeState?.windows ?? new Map(),
+      });
+    }
+  }
+  if (codexState) out.codex = entryOf(codexState);
+  return Object.keys(out).length ? fitRuntimeLimits(out) : null;
+}
+
+/** Test-only: forget everything learned, the plan memo and the path cache. */
+export function resetRuntimeLimitsForTest() {
+  claudeState = null;
+  codexState = null;
+  planMemo = null;
+  rolloutPaths.clear();
+}

package/bin/lib/turnUsage.mjs

@@ -0,0 +1,36 @@
+/**
+ * ONE TURN'S TOKENS, ADDED UP ACROSS THE SPAWNS THAT MADE IT (2026-09-28).
+ *
+ * The agent lane SETS its usage — one spawn, one `result` — and leaves the
+ * adding-up to the server. The Terminal tab, the capture chat and the wiki
+ * are different: a tab turn whose resume came back empty runs a fresh retry
+ * in the same turn, and BOTH spawns spent real tokens; reporting only the
+ * second would under-count exactly the turns that went wrong. So those lanes
+ * sum what each spawn reported before the one settle carries it.
+ *
+ * The wire shape is the agent lane's, unchanged: `{input, output,
+ * cacheCreate, cacheRead, runtime}`. Null-safe on both sides — a spawn that
+ * reported nothing adds nothing, and nothing reported at all stays null
+ * (never four zeros: "spent nothing" is a claim nobody measured). Each counter
+ * is coerced and floored the way `usageFromResult` reads the CLI's numbers.
+ * The runtime is the first one named: one turn runs on one CLI.
+ */
+const n = (v) => {
+  const x = Number(v);
+  return Number.isFinite(x) && x > 0 ? Math.floor(x) : 0;
+};
+
+export function addUsage(a, b) {
+  const has = (u) => Boolean(u) && typeof u === 'object';
+  if (!has(a) && !has(b)) return null;
+  const x = has(a) ? a : {};
+  const y = has(b) ? b : {};
+  const runtime = x.runtime ?? y.runtime;
+  return {
+    input: n(x.input) + n(y.input),
+    output: n(x.output) + n(y.output),
+    cacheCreate: n(x.cacheCreate) + n(y.cacheCreate),
+    cacheRead: n(x.cacheRead) + n(y.cacheRead),
+    ...(runtime ? { runtime } : {}),
+  };
+}

package/bin/lib/wikiRunner.mjs

@@ -38,6 +38,7 @@ import { recordMcpServers, recordSkills } from './runtimeCapabilities.mjs';
 import { THINK_MARKER } from './runtimeEvents.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { postToFleet } from './fleetPost.mjs';
+import { addUsage } from './turnUsage.mjs';
 
 export function createWikiRunner({
   repoRoot,
@@ -372,6 +373,17 @@ export function createWikiRunner({
          * installing one, and a thrown turn is exactly the transient case.
          */
         let sweepCompleted = false;
+        /**
+         * WHAT THIS TASK'S TURN SPENT, AS THE CLI COUNTED IT (2026-09-28),
+         * tagged with the CLI. It rides the DONE frame only — the one frame a
+         * task sends exactly once, which is what lets the server charge it
+         * without a claim of its own; the throttled mid-turn frames stay a
+         * readout. Null (and absent from the frame) when no CLI ran.
+         */
+        let usage = null;
+        const onUsage = (rt) => (u) => {
+          usage = addUsage(usage, { ...u, runtime: rt });
+        };
         try {
           // Immediate frame so the cover shows the daemon feed right away (the
           // "reading your code" phase), not a static message, while Claude warms up.
@@ -444,6 +456,7 @@ export function createWikiRunner({
               label: c.cyan('[wiki]'),
               streamJson: true,
               onActivity,
+              onUsage: onUsage(wikiRt),
               // FREE SKILLS, off a turn that was running anyway. This stream is
               // already parsed and its init event already carries the CLI's own
               // resolved skill set — the same fact a tab turn teaches — so the
@@ -501,6 +514,7 @@ export function createWikiRunner({
                 label: c.cyan('[wiki]'),
                 streamJson: true,
                 onActivity,
+                onUsage: onUsage(wikiRt),
                 // Same free harvest as the sweep above.
                 onInit: (i) => {
                   recordSkills(i.skills);
@@ -564,7 +578,7 @@ export function createWikiRunner({
           }
           // Terminal frame so the app cover clears promptly (don't wait for the
           // freshness window to lapse). force-sent past the throttle.
-          await postWikiProgress(frame({ done: true }), true);
+          await postWikiProgress(frame({ done: true, ...(usage ? { usage } : {}) }), true);
           // Safety net: the wiki turn is read-only on the repo by CONTRACT, but
           // permission enforcement is a curated tool list, not a path jail —
           // discard anything a confused turn wrote to the worktree so it can

package/bin/lib/workAgentPlans.mjs

@@ -5,14 +5,15 @@ import { FLEET_URL, FLEET_TOKEN, USER_AGENT, DAEMON_INSTANCE } from './config.mj
 import { git, isSafePathSegment } from './git.mjs';
 import { parseProposal } from './agentPlan.mjs';
 import { c, note } from './ui.mjs';
-import { runTurn } from './runTurn.mjs';
+import { runTurn as defaultRunTurn } from './runTurn.mjs';
 import { SYSTEM_PLAN, AGENT_PLAN_KICKOFF } from './prompts.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
 import { RUNTIMES } from './runtimes.mjs';
-import { pickRuntimeFor } from './runtimeDetection.mjs';
+import { pickRuntimeFor as defaultPickRuntimeFor } from './runtimeDetection.mjs';
 import { removeProbeTranscript } from './runtimeCapabilities.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { REPO_PLACE } from './workPlaces.mjs';
+import { addUsage } from './turnUsage.mjs';
 
 export function createWorkAgentPlans({
   postBestEffort,
@@ -23,6 +24,10 @@ export function createWorkAgentPlans({
   admit,
   placeLocks,
   workChildren,
+  // The real CLI driver and picker; injectable only so the lane can be driven
+  // in a test without spending a model turn (the wiki runner's shape).
+  runTurn = defaultRunTurn,
+  pickRuntimeFor = defaultPickRuntimeFor,
 }) {
   const AGENT_PLAN_DONE_URL = fleetEndpoint('agent-plan-done', FLEET_URL);
   const AGENT_PLAN_ACTIVITY_URL = fleetEndpoint('agent-plan-activity', FLEET_URL);
@@ -297,6 +302,15 @@ export function createWorkAgentPlans({
     let planSession = null;
     /** The cap fired: the CLI was still running when this machine stopped it. */
     let wedged = false;
+    /**
+     * WHAT THE PLANNER SPENT, AS THE CLI COUNTED IT (2026-09-28) — on every
+     * report that follows a spawn: a proposal, a reply that did not parse, a
+     * wedged turn and a thrown one all sent the requests they sent. The
+     * server charges it once per press, behind a claim bound to the lease, so
+     * a report the retry posts again adds nothing. Null until the CLI reports.
+     */
+    let usage = null;
+    const spent = () => (usage ? { usage } : {});
     // Said BEFORE the lock is asked for, because a reader only waits when a
     // writer holds the checkout or is queued ahead of it — which is exactly
     // this condition, read one line before we join the queue.
@@ -341,6 +355,11 @@ export function createWorkAgentPlans({
             if (typeof i.sessionId === 'string' && i.sessionId.trim())
               planSession = i.sessionId.trim();
           },
+          // Tagged with the CLI that counted it; one turn, so the sum is the
+          // one report (turnUsage.mjs keeps it null-safe).
+          onUsage: (u) => {
+            usage = addUsage(usage, { ...u, runtime: rt });
+          },
           onSpawn: (ch) => {
             planChild = ch;
             // No id: a Deploy press is not a task, and the snapshot's per-task
@@ -374,7 +393,7 @@ export function createWorkAgentPlans({
         out = await Promise.race([turn, capped]);
       });
     } catch (e) {
-      await postAgentPlan({ id, error: envScrub(String(e?.message || e)).slice(0, 500) });
+      await postAgentPlan({ id, error: envScrub(String(e?.message || e)).slice(0, 500), ...spent() });
       return;
     } finally {
       if (planTimer) clearTimeout(planTimer);
@@ -394,6 +413,7 @@ export function createWorkAgentPlans({
       await postAgentPlan({
         id,
         error: 'the planning turn ran past fifteen minutes on this machine and was stopped',
+        ...spent(),
       });
       return;
     }
@@ -407,10 +427,11 @@ export function createWorkAgentPlans({
         error: out.trim()
           ? `the plan did not come back as JSON: ${envScrub(out).slice(0, 300)}`
           : 'the planning turn produced no output — the CLI may be signed out',
+        ...spent(),
       });
       return;
     }
-    await postAgentPlan({ id, proposal, sessionRef: repoRoot });
+    await postAgentPlan({ id, proposal, sessionRef: repoRoot, ...spent() });
   };
 
   const processAgentPlanJobs = (jobs) => {

package/bin/lib/workSessionTurns.mjs

@@ -19,7 +19,8 @@ import { git, isSafePathSegment } from './git.mjs';
 import { processStartTime } from './procRegistry.mjs';
 import { c, note, ok, warn } from './ui.mjs';
 import { mcpFor } from './claude.mjs';
-import { runTurn } from './runTurn.mjs';
+import { runTurn as defaultRunTurn } from './runTurn.mjs';
+import { addUsage } from './turnUsage.mjs';
 import {
   SYSTEM_WORK,
   SYSTEM_CAPTURE,
@@ -87,6 +88,9 @@ export function createWorkSessionTurns({
   noteSessionGroup,
   reportPlaceWorktrees,
   burstListeners,
+  // The real CLI driver; injectable only so the lane can be driven in a test
+  // without spending a model turn (the wiki runner's shape).
+  runTurn = defaultRunTurn,
 }) {
   const workAnswering = new Set(); // turn ids currently queued/running here
   const MAX_WORK_TRIES = 3;
@@ -159,6 +163,17 @@ export function createWorkSessionTurns({
          *  words were lost and the turn was re-offered and re-run. Null until
          *  the turn gets as far as building one. */
         let toolLog = null;
+        /**
+         * WHAT THIS TURN SPENT, AS THE CLI COUNTED IT (2026-09-28) — declared
+         * out here for the same reason as the tool log: the `catch` spreads it
+         * into the failed settle. SUMMED over both spawns (turnUsage.mjs): a
+         * resume that came back empty and its fresh retry both spent tokens.
+         * Null until a CLI reports, so every refusal before a spawn carries
+         * none, which is what `...(usage ? … : {})` rests on. The server
+         * charges it once per turn, behind a one-shot claim, so a settle that
+         * sits in the retry queue and is posted again adds nothing.
+         */
+        let usage = null;
         try {
           const tries = workAttempts.get(job.id) ?? 0;
           if (tries >= MAX_WORK_TRIES) {
@@ -646,6 +661,11 @@ export function createWorkSessionTurns({
               },
               // The structured twin of the line above — see toolLog.
               onToolEvent: pushToolEvent,
+              // The CLI's own token counts, tagged with which CLI counted them
+              // — ADDED, not set: both runTurn calls below share these args.
+              onUsage: (u) => {
+                usage = addUsage(usage, { ...u, runtime: rt.id });
+              },
               // What this CLI says it can be asked for by name. Harvested off
               // the init event the stream already carries — no probe, no scan,
               // no extra spawn — and reported on the next roster poll so the
@@ -805,6 +825,8 @@ export function createWorkSessionTurns({
               // Whatever it DID before coming back empty is exactly the
               // question a failed turn's log answers.
               ...(toolLog.ev.length > 0 ? { tools: toolLog } : {}),
+              // …and an empty fork still spent what it spent.
+              ...(usage ? { usage } : {}),
             });
             warn('adopt turn produced no output — settled as failed');
             return;
@@ -842,6 +864,7 @@ export function createWorkSessionTurns({
             // on the settled message (the live copy on the record is cleared
             // at settle). Already scrubbed at collection.
             ...(toolLog.ev.length > 0 ? { tools: toolLog } : {}),
+            ...(usage ? { usage } : {}),
           });
           if (answer.length > 0) ok(`${c.cyan('tab')} ${c.dim('— replied in the session')}`);
           else warn('session turn produced no output — settled as failed');
@@ -855,6 +878,8 @@ export function createWorkSessionTurns({
             // "What did it do before it failed" is exactly the question a
             // crashed turn's log answers — same spread as the main settle.
             ...(toolLog?.ev.length > 0 ? { tools: toolLog } : {}),
+            // A turn that threw after its CLI ran still spent what it spent.
+            ...(usage ? { usage } : {}),
           });
           warn(`session turn failed: ${e?.message ?? e}`);
         } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.108.1",
+  "version": "0.109.0",
   "description": "Run your own coding CLIs as build agents for Flowviant — 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": {