flowviant 0.125.29 → 0.125.31

package/bin/lib/runtimeLimits.mjs

@@ -8,7 +8,9 @@
  * 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.
+ * decides, gates or parks anything off these numbers; the one other relay is
+ * a hit limit's own reset, carried on the park (`limitResetAt`, 2026-11-06)
+ * so the server retries when the CLI said, not on a guess.
  *
  * TWO SOURCES, ONE SHAPE:
  *
@@ -135,6 +137,8 @@ export function recordClaudeRateLimit(info, now = Date.now()) {
   capWindows(state.windows);
   state.status = CLAUDE_STATUSES.has(info.status) ? info.status : 'other';
   state.at = at;
+  // The binding window's reset rides the event itself beside a rejection.
+  state.rejectedResetsAt = state.status === 'rejected' ? isoFromStamp(info.resetsAt) : null;
 }
 
 /**
@@ -370,6 +374,60 @@ export function runtimeLimitsReport({ detected, plan, now = Date.now() } = {}) {
   return Object.keys(out).length ? fitRuntimeLimits(out) : null;
 }
 
+/** A park's reset is relayed only past now and within this (the longest plan
+ *  window is a week); the server applies the same bound (`PARK_RESET_MAX_MS`). */
+export const PARK_RESET_MAX_MS = 8 * 24 * 60 * 60_000;
+/** A rejection older than this is not the one this turn hit. */
+const LIMIT_READING_FRESH_MS = 30 * 60_000;
+
+/** An ISO reset after `now` and within the bound, or null. */
+export function boundedResetAt(iso, now = Date.now()) {
+  const t = typeof iso === 'string' ? Date.parse(iso) : NaN;
+  return Number.isFinite(t) && t > now && t - now <= PARK_RESET_MAX_MS ? new Date(t).toISOString() : null;
+}
+
+/** The latest reset among windows the CLI measured as full (≥ 100% used):
+ *  the account carries on only once every full window has reset. */
+const fullWindowsReset = (windows) => {
+  let latest = null;
+  for (const w of windows?.values?.() ?? []) {
+    if (w.usedPct != null && w.usedPct >= 100 && w.resetsAt && (!latest || w.resetsAt > latest)) latest = w.resetsAt;
+  }
+  return latest;
+};
+
+/**
+ * WHEN THE LIMIT THIS TURN HIT RESETS, IN THE CLI'S OWN MEASURE (2026-11-06) —
+ * ISO, or null. Relayed on the park (`/fleet/agent-parked` `resetsAt`) so the
+ * server retries then instead of after its fixed cooldown.
+ *
+ * Only a REJECTION read fresh: Claude's `rate_limit_event` with status
+ * `rejected` (its own `resetsAt`, else a full window's), or a Codex rollout
+ * naming the limit reached — read now, off this turn's thread under the
+ * agent's CODEX_HOME (`env`), because the after-close read in runTurn.mjs is
+ * not awaited — with a full window's `resets_at`. Anything unmeasured, stale,
+ * past or past the bound is null, and the server's cooldown stands. Never
+ * throws.
+ */
+export async function limitResetAt(runtime, { threadId, env, now = Date.now() } = {}) {
+  try {
+    const fresh = (st) => st?.status === 'rejected' && now - Date.parse(st.at) <= LIMIT_READING_FRESH_MS;
+    if (runtime === 'claude' || !runtime) {
+      if (!fresh(claudeState)) return null;
+      return boundedResetAt(claudeState.rejectedResetsAt ?? fullWindowsReset(claudeState.windows), now);
+    }
+    if (runtime === 'codex') {
+      // The agent's own home first, then the person's (its sessions link there).
+      if (threadId && !(await learnCodexLimits(threadId, { env, now })) && env) await learnCodexLimits(threadId, { now });
+      if (!fresh(codexState)) return null;
+      return boundedResetAt(fullWindowsReset(codexState.windows), now);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /** Test-only: forget everything learned, the plan memo and the path cache. */
 export function resetRuntimeLimitsForTest() {
   claudeState = null;

package/bin/lib/runtimeReview.mjs

@@ -0,0 +1,185 @@
+/** One model-independent review tool over reusable execution/surface adapters. */
+import { createServer } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { listenHeldTool, heldToolArgv } from './heldTool.mjs';
+import { serveMcpStdio } from './mcpStdio.mjs';
+import { readReviewTargets, reviewCwd, commandOnPath } from './reviewTargets.mjs';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { desktopSupport } from './reviewDesktop.mjs';
+import { openLinuxDesktop } from './linuxDesktopBridge.mjs';
+import { openBridgePage } from './reviewBridge.mjs';
+import { openRobloxStudio } from './robloxStudioBridge.mjs';
+import { reviewedProviderCommand } from './reviewEnvironmentConfig.mjs';
+import { environmentOverlay, readWorktreeEnvironment } from './reviewEnvironment.mjs';
+import { childEnv } from './childEnv.mjs';
+import { measureListeners } from './listeners.mjs';
+import { resolveBrowser } from './shot.mjs';
+import { reviewSourceState, sameReviewSource } from './uiReview.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+import { ensureArtifactDir, ARTIFACT_DIR } from './artifacts.mjs';
+import { learnExtraSecrets, forgetExtraSecrets, scrub } from './uplinkScrub.mjs';
+
+export const RUNTIME_REVIEW_SERVER = 'card_runtime';
+const TOOLS = [
+  { name: 'discover', description: 'List reviewed command, browser, desktop, Roblox Studio and engine review targets and measured prerequisites. Discovery starts no application.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'run', description: 'Run a named reviewed target. Command checks return logs and source-bound evidence; interactive targets open the SAME Live app frame and human control handoff. Never treats a build or sync server as gameplay.', inputSchema: { type: 'object', properties: { target: { type: 'string' }, repository: { type: 'string' } }, required: ['target'], additionalProperties: false } },
+  { name: 'observe', description: 'Capture and retain the current shared runtime surface. Screenshot capture is an observation, not a passing test.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'act', description: 'Interact with the current surface using bounded click, type, key, scroll or browser navigation verbs. Human control pauses model interactions.', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['click', 'type', 'key', 'scroll', 'navigate', 'snapshot'] }, x: { type: 'number' }, y: { type: 'number' }, text: { type: 'string' }, key: { type: 'string' }, path: { type: 'string' }, selector: { type: 'string' }, deltaY: { type: 'number' } }, required: ['type'], additionalProperties: false } },
+  { name: 'handoff', description: 'Hold this turn for human private sign-in or native app testing. Waits without model polling and resumes the same conversation.', inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: ['signin', 'control'] }, reason: { type: 'string', maxLength: 300 } }, required: ['kind', 'reason'], additionalProperties: false } },
+  { name: 'stop', description: 'Stop the runtime processes owned by this tool. A person’s Stop prevents reopening for the turn.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+];
+const text = value => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+const availablePort = () => new Promise((resolve, reject) => {
+  const server = createServer(); server.once('error', reject);
+  server.listen(0, '127.0.0.1', () => { const port = server.address().port; server.close(() => resolve(port)); });
+});
+
+export async function createRuntimeReview({ wt, repoRoot, baseRef, sources = [], browser, signal, onChild,
+  openDesktop = openLinuxDesktop, openBridge = openBridgePage, openRoblox = openRobloxStudio, desktopProbe = desktopSupport, browserProbe = resolveBrowser }) {
+  const catalog = (sources.length ? sources : [{ wt, repoRoot, baseRef }]).map(source => ({ ...readReviewTargets(source.repoRoot, source.baseRef),
+    wt: source.wt, name: source.name ?? basename(source.repoRoot), id: source.id }));
+  if (catalog.every(source => Object.keys(source.targets).length === 0)) return null;
+  const controller = new AbortController(), reports = [], commands = new Set();
+  let closed = false, busy = false, current = null, app = null;
+  const abort = () => { void close(); };
+  const environmentFor = source => readWorktreeEnvironment(source.wt)?.env ?? process.env;
+  function support(target, env) {
+    if (target.platforms && !target.platforms.includes(process.platform)) return { available: false, reason: `This target requires ${target.platforms.join(' or ')}; this machine is ${process.platform}.` };
+    if (target.adapter === 'browser') {
+      const found = browserProbe();
+      return browser && found && !found.viaWindows ? { available: true } : { available: false, reason: 'No native managed Chromium browser is available on this machine.' };
+    }
+    if (target.adapter === 'desktop') return browser ? desktopProbe(env) : { available: false, reason: 'The interactive surface transport is unavailable on this turn.' };
+    if (target.adapter === 'roblox') {
+      const found = browserProbe();
+      return browser && process.platform === 'linux' && commandOnPath('flock', env) && found && !found.viaWindows ? { available: true } : { available: false, reason: 'Studio viewport review needs a Linux/WSL daemon, flock and native headless Chromium. Studio/MCP runs on the Windows host.' };
+    }
+    if (target.adapter === 'bridge' && !browser) return { available: false, reason: 'The interactive surface transport is unavailable on this turn.' };
+    return { available: true };
+  }
+  const stopApp = async () => { const previous = app; app = null; await previous?.close(); };
+  async function close() {
+    if (closed) return;
+    closed = true; signal?.removeEventListener('abort', abort); controller.abort();
+    if (current) await browser?.close();
+    await Promise.all([stopApp(), ...[...commands].map(command => command.close())]);
+    held.server.close(); held.server.closeAllConnections(); forgetExtraSecrets(secretKey);
+  }
+  const record = (source, target, name, before, result) => {
+    const after = reviewSourceState(source.wt);
+    const report = { target: name, repository: source.name, adapter: target.adapter, ...result,
+      before, after, sourceStable: sameReviewSource(before, after) };
+    reports.push({ source, report });
+    if (ensureArtifactDir(wt)) {
+      const path = `runtime-review-${randomUUID()}.md`;
+      const body = `# Runtime review: ${source.name}/${name}\n\n${scrub(JSON.stringify(report, null, 2))}\n`;
+      writeFileSync(join(wt, ARTIFACT_DIR, path), body, { flag: 'wx', mode: 0o600 });
+      report.artifact = `${ARTIFACT_DIR}/${path}`;
+    }
+    return report;
+  };
+  const call = async (name, input = {}) => {
+    if (closed || controller.signal.aborted) throw new Error('This review turn has ended.');
+    if (name === 'discover') return text({ repositories: catalog.map(source => ({ repository: source.name, targets: Object.entries(source.targets).map(([target, config]) => ({ target, adapter: config.adapter,
+      ...support(config, environmentFor(source)), command: config.command })) })),
+      instruction: 'Use the repository’s existing workflows when no recipe is configured. A missing runtime leaves those checks unverified; code editing can continue. A Roblox/Rojo sync server is not gameplay.' });
+    if (busy) throw new Error('Another runtime review operation is finishing.');
+    busy = true;
+    try {
+      if (name === 'observe') { if (!browser) throw new Error('No interactive runtime is available.'); return await browser.act({ type: 'snapshot' }); }
+      if (name === 'act') { if (!browser) throw new Error('No interactive runtime is available.'); return await browser.act(input); }
+      if (name === 'handoff') { if (!browser) throw new Error('No interactive runtime is available.'); return await browser.handoff(input); }
+      if (name === 'stop') { browser?.stopSurface(); await stopApp(); current = null; return text({ stopped: true }); }
+      if (name !== 'run') throw new Error('Unknown runtime tool.');
+      const source = input.repository == null ? catalog.find(source => source.wt === wt) : catalog.find(source => source.name === input.repository || source.id === input.repository);
+      const target = source && Object.hasOwn(source.targets, input.target) ? source.targets[input.target] : null;
+      if (!target) throw new Error('That reviewed target does not exist. Call discover and use a listed repository/target.');
+      const cwd = reviewCwd(source.wt, target.cwd), env = environmentFor(source), measured = support(target, env);
+      if (!measured.available) throw new Error(measured.reason);
+      if (!commandOnPath(target.command[0], env) && !target.command[0].startsWith('./')) throw new Error(`Review command ${target.command[0]} is not installed on this machine.`);
+      const scoped = readWorktreeEnvironment(source.wt);
+      const interactiveEnv = { ...childEnv({ cwd }), ...Object.fromEntries((target.env ?? []).filter(key => env[key] != null).map(key => [key, env[key]])), ...(scoped ? environmentOverlay(scoped) : {}) };
+      const before = reviewSourceState(source.wt), options = { cwd, env: target.adapter === 'command' ? env : interactiveEnv, onChild, signal: controller.signal, timeoutMs: target.timeoutSeconds * 1000 };
+      if (target.adapter === 'command') {
+        const running = startReviewProcess(target.command, options);
+        commands.add(running);
+        let result;
+        try { result = await running.done; } finally { commands.delete(running); }
+        const report = record(source, target, input.target, before, { status: !result.error && result.code === 0 ? 'passed' : 'failed', exitCode: result.code, output: result.output, ...(result.error ? { error: result.error } : {}) });
+        return text({ ...report, output: result.output.slice(-4000), ...(result.output.length > 4000 ? { outputTruncated: true } : {}) });
+      }
+      browser.assertControl();
+      const key = `${source.wt}:${input.target}`;
+      if (target.adapter === 'browser') {
+        try {
+        if (current?.key !== key || !app?.running()) {
+          await stopApp();
+          const port = target.port || await availablePort();
+          if (measureListeners(source.wt).rows.some(row => row.port === port)) throw new Error('That worktree port is already running. Use card_browser for the existing server, or choose a different review port.');
+          app = startReviewProcess(target.command.map(arg => arg.replaceAll('${PORT}', String(port))), options);
+          current = { key, port };
+          for (let n = 0; n < 100; n++) {
+            if (controller.signal.aborted) throw new Error('The review turn ended during startup.');
+            if (!app.running()) throw new Error(app.result()?.error ?? `The review app exited. ${app.output()}`);
+            if (measureListeners(source.wt).rows.some(row => row.port === port)) break;
+            if (n === 99) throw new Error('No listener was measured for this review target.');
+            await new Promise(resolve => setTimeout(resolve, 100));
+          }
+        }
+        return await browser.open({ port: current.port, hostname: target.hostname, scheme: target.scheme, path: target.path ?? '/', fixture: target.fixture }, source.wt);
+        }
+        catch (error) { await stopApp(); current = null; throw error; }
+      }
+      const result = await browser.openSurface({ key, target: input.target, surface: target.adapter === 'desktop' ? 'desktop' : 'engine',
+        open: async surface => {
+          await stopApp(); current = { key };
+          if (target.adapter === 'desktop') return openDesktop({ ...options, ...surface, command: target.command, support: measured });
+          const command = reviewedProviderCommand({ root: source.root, commit: source.commit, recipe: { database: { command: target.command } } });
+          if (target.adapter === 'roblox') return openRoblox({ ...options, ...surface, command, cwd: source.root, worktree: source.wt, configuration: target.configuration });
+          return openBridge({ ...options, ...surface, command, cwd: source.root, worktree: source.wt, configuration: target.configuration });
+        } });
+      record(source, target, input.target, before, { status: 'observed', note: 'Interactive runtime opened. Captures and input do not establish passing gameplay tests.' });
+      return result;
+    } catch (error) { throw new Error(reviewDiagnostic(error.message)); }
+    finally { busy = false; }
+  };
+  const held = await listenHeldTool({ envPrefix: 'FLOWVIANT_RUNTIME_REVIEW', verb: '__runtime-review-mcp', requestTimeoutMs: 615_000, isClosed: () => closed,
+    respond: async (req, res) => {
+      try {
+        const chunks = []; let size = 0;
+        for await (const bytes of req) { size += bytes.length; if (size > 16_000) throw new Error('Runtime request exceeds its byte bound.'); chunks.push(bytes); }
+        const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (!TOOLS.some(tool => tool.name === input.name)) throw new Error('Unknown runtime tool.');
+        const result = await call(input.name, input.input);
+        res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(result));
+      } catch (error) { res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ isError: true, content: [{ type: 'text', text: reviewDiagnostic(error.message) }] })); }
+    } });
+  const secretKey = `runtime-review:${held.capability.slice(0, 12)}`;
+  learnExtraSecrets(secretKey, [{ name: 'FLOWVIANT_RUNTIME_REVIEW_CAPABILITY', value: held.capability }]);
+  signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) await close();
+  return { env: held.env, config: { command: process.execPath, args: held.args, env: held.env, toolTimeoutSec: 650 }, close,
+    instructions: `Use card_runtime.discover to find reviewed command, browser, desktop or engine targets. Run a named target with card_runtime.run; never treat code compilation or a sync server as a visual/gameplay test. Desktop targets use a private virtual display, never the personal desktop. Native/engine screenshots use the SAME Live app frame and handoff controls as browser review. Human control pauses model observations/input; call handoff before asking for sign-in or manual testing and finish this invocation without polling. Missing capabilities are skipped checks, not passing tests or reasons to stop code work. Keep external services on scoped test bindings. Observe and retain actual captures before delivery. For a runner without MCP, this turn also provides the private shell helper argv ${JSON.stringify([process.execPath, ...heldToolArgv('__runtime-review')])}; pass a JSON request file {name,input}.`,
+    finalize() {
+      return reports.map(({ source, report }) => `Runtime review ${report.repository}/${report.target}: ${report.status}${report.status === 'observed' ? ' (not a passing gameplay test)' : ''}. ${report.sourceStable && sameReviewSource(report.after, reviewSourceState(source.wt)) ? 'Source matches final tracked/nonignored state.' : 'STALE: source changed or could not be measured; this does not verify final source.'}${report.artifact ? ` Evidence: ${report.artifact}.` : ''}`).join('\n');
+    },
+  };
+}
+
+async function requestRuntime(input) {
+  const response = await fetch(process.env.FLOWVIANT_RUNTIME_REVIEW_URL, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FLOWVIANT_RUNTIME_REVIEW_CAPABILITY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(input), signal: AbortSignal.timeout(615_000) });
+  if (!response.ok) throw new Error('The held runtime turn has ended.');
+  return response.json();
+}
+export async function runtimeReviewMain(mcp = false) {
+  if (mcp) return serveMcpStdio({ serverInfo: { name: RUNTIME_REVIEW_SERVER, version: '1.0.0' }, tools: TOOLS, rawResult: true, call: (name, input) => requestRuntime({ name, input }) });
+  try {
+    const { readFileSync } = await import('node:fs');
+    const result = await requestRuntime(JSON.parse(readFileSync(process.argv[3], 'utf8')));
+    // Shell tools are text transports. Never flood a model context with image
+    // base64; observe retains a local artifact that its image tool can inspect.
+    const content = result.content?.map(block => block.type === 'image' ? { type: 'text', text: 'Image shown in Live app. Use observe to retain it, then open the reported artifact with an available image tool. Capture alone does not establish visual inspection.' } : block);
+    process.stdout.write(JSON.stringify({ ...result, ...(content ? { content } : {}) }) + '\n'); process.exitCode = result.isError ? 1 : 0;
+  } catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 1; }
+}

package/bin/lib/splitGate.mjs

@@ -0,0 +1,115 @@
+/**
+ * THE PERSON'S YES BEFORE CHILDREN EDIT FILES (2026-11-06, D13/D28–D31, E5).
+ *
+ * A card turn's job carries `subagents` (`SubagentSplitJob`, shared
+ * subagentSplit.ts, `DAEMON_SUBAGENT_SPLIT_MIN`) from a server that asks:
+ *  - `ask`: a child that edits files waits for an approved split. The gate
+ *    refuses its spawn in words that tell the model to propose the split
+ *    (agentSplit.mjs) and stop. A read-only lookup on the agent's own CLI
+ *    starts without asking (D13).
+ *  - `approved`: this turn is the person's "Use N subagents".
+ *  - `always`: the agent's Always switch (D29). It only skips this question;
+ *    Claude's own workflow/ultracode modes stay separate (D14).
+ * ABSENT IS THE OLD SERVER, and the old behaviour stands: nothing is held and
+ * nothing is proposed. A research card's children only read already (the
+ * gate fences them), so nothing there waits either.
+ *
+ * WHETHER A CHILD EDITS, per CLI, conservatively — unknown is editing:
+ *  - Claude's Agent/Task: by `subagent_type`. Only the built-in read-only
+ *    types (Explore, Plan: no Edit/Write/NotebookEdit tools) read; general-
+ *    purpose, a project's own type, or none named, edit. The gate also refuses
+ *    such a child's file-write tools (orchestrator.mjs), since a type is the
+ *    model's word; its shell is not fenced.
+ *  - Codex's spawn_agent: by a declared read-only sandbox on the spawn, which
+ *    no measured Codex input carries today, so every Codex spawn waits.
+ * Pure: no record, slot or request is read here.
+ */
+import { isBackgroundSpawnTool, isSpawnTool } from './nativeAgentTools.mjs';
+import { CLAUDE_CHILD_MODELS, claudeFamily } from './orchestratorNative.mjs';
+import { SPLIT_SOLO_LABEL } from './agentSplit.mjs';
+
+export const SPLIT_MODES = Object.freeze(['ask', 'approved', 'always']);
+/** Claude Code's built-in subagent types whose tools exclude file writes. */
+export const CLAUDE_READ_ONLY_TYPES = Object.freeze(['Explore', 'Plan']);
+const READ_ONLY_SANDBOX = /^read[-_ ]?only$/i;
+
+/** The job's split field, or null when absent or unreadable (the old path). */
+export function splitPolicy(job) {
+  const s = job?.subagents;
+  if (!s || typeof s !== 'object' || !SPLIT_MODES.includes(s.mode)) return null;
+  const str = v => typeof v === 'string' && v.trim() ? v.trim() : null;
+  return { mode: s.mode, runtime: str(s.runtime), model: str(s.model), effort: str(s.effort) };
+}
+
+/** Whether this spawn's child may edit files; true whenever it cannot tell. */
+export function childEdits(event, input = event?.tool_input ?? {}) {
+  if (isBackgroundSpawnTool(event?.tool_name)) return !CLAUDE_READ_ONLY_TYPES.includes(input.subagent_type);
+  if (isSpawnTool(event?.tool_name)) return ![input.sandbox, input.sandbox_mode, input.sandbox_policy].some(v => typeof v === 'string' && READ_ONLY_SANDBOX.test(v));
+  return true;
+}
+
+export const splitRefusal = runtime => `This child may edit files, and the person has not approved a split, so it was not started. Propose the split instead: end your turn with the split JSON (status "split") naming each part, the paths it touches and whether it edits files, then stop and wait for the person's answer. ${runtime === 'codex' ? 'On Codex every spawn waits for that answer; do read-only lookups yourself.' : 'A read-only lookup starts without asking: spawn it with the Explore or Plan agent type.'} Or do this part yourself.`;
+
+/** The deny words for a spawn the split holds, or null when it may start. */
+export function splitHold(policy, event, spawn, { runtime, access }) {
+  if (!policy || policy.mode !== 'ask' || access === 'read') return null;
+  return childEdits(event, spawn?.input) ? splitRefusal(runtime) : null;
+}
+
+/** Whether the gate admitted this spawn as a read-only lookup (ask mode). */
+export const readOnlyLookup = (policy, event, spawn, access) => Boolean(policy && policy.mode === 'ask' && access !== 'read' && !childEdits(event, spawn?.input));
+
+/**
+ * The children's model and effort under an approved or Always split: the
+ * person's batch choice, where they named one, over the card's. On Claude the
+ * Agent tool takes only a family alias; a choice outside the known families
+ * is not honourable there, and the card's model stands (`unhonoured`).
+ */
+export function splitBrain(policy, runtime, card = {}) {
+  if (!policy || policy.mode === 'ask') return { brain: {}, unhonoured: [] };
+  // A batch on another CLI (E7) chose that CLI's model: native children keep the card's.
+  if (policy.runtime && policy.runtime !== runtime) return { brain: {}, unhonoured: [] };
+  const brain = {}, unhonoured = [];
+  if (policy.model) {
+    if (runtime === 'claude' && !CLAUDE_CHILD_MODELS.includes(claudeFamily(policy.model))) unhonoured.push(`Claude's Agent tool names only ${CLAUDE_CHILD_MODELS.join(', ')}, so children run on ${card.model ?? 'the card’s model'}, not ${policy.model}`);
+    else brain.model = policy.model;
+  }
+  if (policy.effort) brain.effort = policy.effort;
+  return { brain, unhonoured };
+}
+
+const choiceWords = (policy, runtime, card) => {
+  const { brain, unhonoured } = splitBrain(policy, runtime, card);
+  const model = brain.model ?? card.model, effort = brain.effort ?? card.effort;
+  const at = `${model ?? 'the card’s model'}${effort ? ` at ${effort} effort` : ''}`;
+  const codex = runtime === 'codex' && brain.model ? ' On Codex a model outside this machine’s catalog cannot be named for a child; it then inherits the card’s.' : '';
+  return `Run every child on ${at}: the person chose it for the whole batch, so name no other model or effort for a child.${unhonoured.length ? ` ${unhonoured.join('. ')}.` : ''}${codex}`;
+};
+
+const CLI_LABEL = { claude: 'Claude Code', codex: 'Codex' };
+
+/**
+ * A BATCH ON ANOTHER CLI (2026-11-06, D21/D30, E7): the person chose the other
+ * CLI for every child, so each part starts with card_orchestrator's
+ * start_cli_agent instead of a native spawn — when this machine has that CLI
+ * ready (`crossCli`, the CLIs the controller offers); otherwise the parts are
+ * the lead's own, and it says why.
+ */
+const otherCliWords = (policy, crossCli) => {
+  const cli = policy.runtime, name = CLI_LABEL[cli] ?? cli;
+  if (!crossCli.includes(cli)) return `The person chose ${name} for the children, and ${name} is not ready on this machine, so no child can start on it: do the parts yourself, and say so in your update.`;
+  const at = [policy.model, policy.effort && `${policy.effort} effort`].filter(Boolean).join(' at ');
+  return `Run every child on ${name}${at ? `, ${at}` : ''}: the person chose it for the whole batch. Start each part with card_orchestrator.start_cli_agent (cli "${cli}", a title, its kind and the whole brief, naming no other model or effort), never with a native spawn, then read each with cli_agent_result until it is done, stopped or limited. A limited child hit ${name}'s own plan limit: its words say so; retry it later with followup_cli_agent or do its part yourself.`;
+};
+
+/** The words this run's split policy adds to the orchestrator's contract. */
+export function splitContract(policy, { runtime = 'claude', model = null, effort = null, crossCli = [] } = {}) {
+  if (!policy) return '';
+  const card = { model, effort };
+  const batch = () => policy.runtime && policy.runtime !== runtime ? otherCliWords(policy, crossCli) : choiceWords(policy, runtime, card);
+  if (policy.mode === 'approved') return `THE PERSON APPROVED YOUR SPLIT for this turn: start the parts you proposed ${policy.runtime && policy.runtime !== runtime ? 'now' : 'as native subagents now, as above'}. ${batch()}`;
+  if (policy.mode === 'always') return `SPLITS ARE PRE-APPROVED ON THIS AGENT (its Always use subagents switch): split independent parts as above without proposing first. ${batch()} This switch starts no workflow or other mode of the CLI; it only skips the person's question.`;
+  return `SUBAGENTS THAT EDIT FILES NEED THE PERSON'S YES. For children that edit files this replaces "this contract is the authorization" above. When parts of the card's work can run side by side and would edit files, do not spawn them: write any code they share first, as above, then propose the split and stop. End your turn with this JSON as your final answer, in place of delivered or blocked:
+{"status":"split","split":{"reason":"one or two sentences on why these parts can run side by side","parts":[{"title":"Port gizmo shaders","touches":["src/gizmo.frag","src/gizmo.ts"],"edits":true},{"title":"Audit textures","touches":["assets/textures/**"],"edits":false}]},"progress":"…"}
+Name every part you would give a child (at most 12), the paths or areas it touches (at most 8), and whether it edits files or only reads. The person answers "Use N subagents" — your next turn then says the split is approved and which model and effort the children run on — or "${SPLIT_SOLO_LABEL}", which means: do every part yourself with no child that edits files, and do not propose this split again. ${runtime === 'codex' ? 'On Codex the gate cannot tell a reading child from an editing one, so every spawn waits for that answer: do lookups yourself.' : 'A read-only lookup needs no approval: spawn it with the Explore or Plan agent type; the gate holds every other spawn.'} Children already running keep going: write the proposal as your final answer once they finish. A split is not a question for blocked JSON.`;
+}

package/bin/lib/subagentBounds.mjs

@@ -13,8 +13,34 @@
  *  shared `SUBAGENT_STATUSES`. */
 
 export const SUBAGENT_CAP = 32;
+export const WORKFLOW_AGENT_CAP = 200;
+export const WORKFLOW_CAP = 32;
 /** In the order the trace relay sends them. */
 export const SUBAGENT_FIELD_CAPS = Object.freeze({ kind: 80, title: 200, now: 400, brief: 24_000 });
 export const SUBAGENT_STATUSES = Object.freeze(['running', 'waiting', 'asked', 'stopped', 'done']);
 /** A child that has finished or been stopped: the controller revives neither. */
 export const SETTLED_SUBAGENT_STATUSES = Object.freeze(['done', 'stopped']);
+
+/** WHAT EACH CHILD'S RECORD CARRIES BEYOND ITS DESCRIPTOR (2026-11-06, S4.1),
+ *  and its own step budget. Before this a child was id/kind/title/brief/now
+ *  and a status, its steps shared the turn's 400 with the lead and every
+ *  sibling, and a 33rd child vanished without a count. The server keeps the
+ *  same numbers (`agentTraceAgents.ts`, check-app-parity rule 38):
+ *   · `SUBAGENT_STEP_CAP` — the newest steps each child keeps of its own,
+ *     past which its oldest are said as "N earlier not kept";
+ *   · `SUBAGENT_RESULT_CAP` — its final message, as its CLI handed it back;
+ *   · `SUBAGENT_RUNS_CAP` — the turns one resumed child is remembered in;
+ *   · `SUBAGENT_KEY_MAX` — its stable identity across turns;
+ *   · `SUBAGENT_CLIS` — the CLIs whose children are recorded (a CLI outside
+ *     the list is unknown and the field is absent).
+ *  `OUTSIDE_*` bounds the lead's shell-outs to another CLI ("Outside" rows,
+ *  D23): shown, never blocked, never counted toward the 32. */
+export const SUBAGENT_STEP_CAP = 120;
+export const SUBAGENT_RESULT_CAP = 8_000;
+export const SUBAGENT_RUNS_CAP = 16;
+export const SUBAGENT_KEY_MAX = 160;
+export const SUBAGENT_CLIS = Object.freeze(['claude', 'codex']);
+export const OUTSIDE_CAP = 32;
+export const OUTSIDE_COMMAND_CAP = 600;
+export const OUTSIDE_CLIS = Object.freeze(['claude', 'codex', 'gemini']);
+export const OUTSIDE_STATUSES = Object.freeze(['running', 'done', 'failed']);

package/bin/lib/subagentLedger.mjs

@@ -0,0 +1,110 @@
+/**
+ * WHICH TURNS EACH OF AN AGENT'S SUBAGENTS APPEARED IN (2026-11-06, S4.1,
+ * D26). A child resumed in a later turn — Claude's `Agent({ resume })` of
+ * its native agent id, a Codex follow-up to its child thread — is the same
+ * child, and the chat shows it once ("continued in run 3"). Each turn's
+ * trace keeps its own bounded record; this ledger is how that record knows
+ * the earlier turns, by the stable `key` turnSubagents.mjs gives it.
+ *
+ * Kept beside the agent's resume markers, in the worktree's private git dir
+ * (workAgentResume.mjs): a child can only be resumed where its conversation
+ * is, so this is exactly as durable as the resume it describes. Codex
+ * children also keep the task paths they answered to, so a follow-up by
+ * path reaches its thread in a later turn (codexSubagents.mjs
+ * `knownTargets`).
+ *
+ * BEST EFFORT BOTH WAYS, like the markers: unreadable is unknown (runs
+ * carry no field), unwritable costs the next turn its history.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { CLAUDE_SESSION_RE, CODEX_THREAD_RE, CODEX_CHILD_THREAD_RE } from './conversationIds.mjs';
+import { SUBAGENT_KEY_MAX, SUBAGENT_RUNS_CAP } from './subagentBounds.mjs';
+
+/** Children remembered per agent; the oldest go first. */
+export const LEDGER_KEYS = 128;
+const LEDGER_BYTES = 256 * 1024;
+const NAMES = 4;
+const TURN_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+function readLedger(path) {
+  if (!path || !existsSync(path)) return new Map();
+  try {
+    const raw = readFileSync(path, 'utf8');
+    if (raw.length > LEDGER_BYTES) return null;
+    const v = JSON.parse(raw);
+    if (!v || typeof v !== 'object' || Array.isArray(v)) return null;
+    const out = new Map();
+    for (const [key, entry] of Object.entries(v).slice(-LEDGER_KEYS)) {
+      if (key.length > SUBAGENT_KEY_MAX || !entry || typeof entry !== 'object') continue;
+      const r = Array.isArray(entry.r) ? entry.r.filter(t => typeof t === 'string' && TURN_RE.test(t)).slice(-SUBAGENT_RUNS_CAP) : [];
+      const n = Array.isArray(entry.n) ? entry.n.filter(s => typeof s === 'string' && s.length <= 160).slice(-NAMES) : [];
+      const c = entry.c;
+      const valid = c && ['codex', 'claude'].includes(c.cli) &&
+        (c.cli === 'codex' ? CODEX_THREAD_RE : CLAUDE_SESSION_RE).test(c.native ?? '') &&
+        key === `${c.cli}:${c.native}` && typeof c.wt === 'string' && c.wt.startsWith('/') && c.wt.length <= 4096;
+      out.set(key, { r, n, ...(valid ? { c } : {}) });
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/** One turn's view of the agent's ledger at `path` (null: no git dir). */
+export function subagentLedger(path, turnId) {
+  const ledger = path ? readLedger(path) : null;
+  let dirty = false;
+  return {
+    /** Null when the ledger is unknown: the trace then sends no runs. */
+    runsOf: ledger && TURN_RE.test(turnId ?? '') ? (key, { title } = {}) => {
+      if (typeof key !== 'string' || !key || key.length > SUBAGENT_KEY_MAX) return null;
+      const entry = ledger.get(key) ?? { r: [], n: [] };
+      if (!entry.r.includes(turnId)) { entry.r = [...entry.r, turnId].slice(-SUBAGENT_RUNS_CAP); dirty = true; }
+      if (typeof title === 'string' && title && title.length <= 160 && !entry.n.includes(title)) { entry.n = [...entry.n, title].slice(-NAMES); dirty = true; }
+      // Most recently seen last, so the bound sheds the longest unheard.
+      ledger.delete(key); ledger.set(key, entry);
+      while (ledger.size > LEDGER_KEYS) ledger.delete(ledger.keys().next().value);
+      return [...entry.r];
+    } : null,
+    /** A Codex child's earlier names → its thread, for this turn's reader. */
+    codexTargets() {
+      const out = new Map();
+      for (const [key, { n }] of ledger ?? []) {
+        const thread = key.startsWith('codex:') ? key.slice(6) : '';
+        if (!CODEX_CHILD_THREAD_RE.test(thread)) continue;
+        for (const name of n) out.set(name, thread);
+      }
+      return out;
+    },
+    /** Cross-CLI identity is measured at init, never reconstructed from a title. */
+    rememberCli(key, child) {
+      if (!ledger || !key || key.length > SUBAGENT_KEY_MAX) return;
+      const entry = ledger.get(key) ?? { r: [], n: [] };
+      entry.c = { ...child, id: entry.c?.id ?? child.id };
+      ledger.delete(key); ledger.set(key, entry);
+      while (ledger.size > LEDGER_KEYS) ledger.delete(ledger.keys().next().value);
+      dirty = true;
+      this.persist();
+    },
+    cliChild(id, wt) {
+      for (const [key, entry] of ledger ?? []) {
+        if (entry.c?.wt === wt && (key === id || entry.c.id === id)) return { ...entry.c, key };
+      }
+      return null;
+    },
+    persist() {
+      if (!dirty || !path || !ledger) return;
+      try {
+        let data = JSON.stringify(Object.fromEntries(ledger));
+        while (Buffer.byteLength(data) > LEDGER_BYTES && ledger.size) {
+          ledger.delete(ledger.keys().next().value);
+          data = JSON.stringify(Object.fromEntries(ledger));
+        }
+        writeFileSync(path, data);
+        dirty = false;
+      } catch {
+        /* the next turn's children carry no history */
+      }
+    },
+  };
+}