flowviant 0.125.29 → 0.125.31

package/bin/lib/trace.mjs

@@ -62,7 +62,8 @@
 import { THINK_MARKER, scrubNativeText } from './runtimeEvents.mjs';
 import { withoutTurnDeclaration } from './turnDeclaration.mjs';
 import { MAX_MCP_SERVERS, MCP_NAME_MAX, MCP_STATUSES } from './mcpReportBounds.mjs';
-import { SUBAGENT_CAP, SUBAGENT_FIELD_CAPS, SUBAGENT_STATUSES } from './subagentBounds.mjs';
+import { WORKFLOW_AGENT_CAP, WORKFLOW_CAP, OUTSIDE_CAP, OUTSIDE_COMMAND_CAP, OUTSIDE_STATUSES, SETTLED_SUBAGENT_STATUSES, SUBAGENT_CAP, SUBAGENT_CLIS, SUBAGENT_FIELD_CAPS,
+  SUBAGENT_KEY_MAX, SUBAGENT_RESULT_CAP, SUBAGENT_RUNS_CAP, SUBAGENT_STATUSES } from './subagentBounds.mjs';
 
 /** One batch every two seconds — the discipline the tab's narrator keeps, for
  *  the same reason: a turn emits hundreds of entries and nobody is reading them
@@ -111,7 +112,18 @@ function newRunId() {
  * with no such route, a body the server will never accept). Resolving falsy
  * keeps them queued for the next flush.
  */
-export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run = newRunId(), orchestrationVersion }) {
+/** One native window a brief or result is scrubbed over before its cap. */
+const NATIVE_WINDOW = 65_536;
+const EFFORT_RE = /^[a-z]{1,24}$/;
+const RUN_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * `cli` is the runtime whose children this turn records. `runsOf(key)` is
+ * the agent's subagent ledger (workAgentResume.mjs): the turns a child of
+ * that stable key appeared in, this one included; absent, a child's runs are
+ * unknown and carry no field.
+ */
+export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run = newRunId(), orchestrationVersion, cli, runsOf }) {
   /** Entries not yet delivered. `base` is the ABSOLUTE index of queue[0] in
    *  THIS RUN's stream, so `base + queue.length` is everything this relay has
    *  ever accepted — sent, queued or shed. Absolute for the TURN is the
@@ -124,6 +136,19 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
    *  by the bare-marker collapse in `prose()` and nothing else. */
   let lastEntry = null;
   const agentReadings = new Map();
+  /** Each child's own steps, sent or shed: its record's `steps`, against
+   *  which the server says "N earlier not kept" past its own budget. */
+  const childSteps = new Map();
+  /** Children past the 32, counted and never recorded (bounded: a count). */
+  const unrecorded = new Set();
+  let notRecorded = 0;
+  /** The lead's own entries this run, sent or shed: where a child or an
+   *  Outside row sits in the lead's thread (its `position`). */
+  let leadCount = 0;
+  /** The lead's shell-outs to another CLI ("Outside", D23), by call id. */
+  const outsideRows = new Map();
+  const workflowRows = new Map(), workflowPositions = new Map();
+  let extrasPending = false;
   const mcpSaid = new Set();
   let dirty = orchestrationVersion === 2;
   let markerPending = dirty;
@@ -145,6 +170,8 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
   const push = (entry) => {
     if (stopped || !entry) return;
     lastEntry = entry;
+    if (entry.agentId) childSteps.set(entry.agentId, (childSteps.get(entry.agentId) ?? 0) + 1);
+    else if (entry.k !== 'agent') leadCount += 1;
     queue.push(entry);
     while (queue.length > TRACE_BUFFER) {
       queue.shift();
@@ -156,7 +183,7 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
 
   const drain = async (deadlineMs) => {
     const until = deadlineMs > 0 ? Date.now() + deadlineMs : 0;
-    while (queue.length || markerPending) {
+    while (queue.length || markerPending || extrasPending) {
       if (until && Date.now() > until) {
         dirty = true;
         return;
@@ -164,10 +191,17 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
       const entries = queue.slice(0, TRACE_BATCH);
       const seq = base;
       dirty = false;
+      // The turn's counts and Outside rows ride beside the stream, whole: they
+      // take no seq, so an older server ignoring them sheds no step.
+      const extras = extrasPending;
+      extrasPending = false;
       let ok = false;
       try {
         ok = (await post({ agentId, turnId, run, seq, entries,
           ...(orchestrationVersion === 2 ? { orchestrationVersion } : {}),
+          ...(extras && notRecorded > 0 ? { notRecorded } : {}),
+          ...(extras && outsideRows.size ? { outside: [...outsideRows.values()] } : {}),
+          ...(extras && workflowRows.size ? { workflows: [...workflowRows.values()] } : {}),
         })) !== false;
       } catch {
         ok = false;
@@ -176,6 +210,7 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
         // Held, at the SAME seq: a retry the server has already seen is
         // trimmed against its high-water mark rather than doubled.
         dirty = true;
+        extrasPending ||= extras;
         return;
       }
       markerPending = false;
@@ -201,6 +236,30 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
   // The first report stamps even a silent or immediately failed CLI invocation.
   schedule();
   const scoped = (id) => id ? `${run}:${scrubNativeText(id, 96, scrub)}` : undefined;
+  /** A child's S4.1 detail, each field present only when its source said it. */
+  const cleanKey = v => scrubNativeText(v, SUBAGENT_KEY_MAX, scrub);
+  const detailOf = (update) => {
+    const out = {};
+    const childCli = update.cli ?? cli;
+    if (SUBAGENT_CLIS.includes(childCli)) out.cli = childCli;
+    if (typeof update.key === 'string' && update.key && update.key.length <= SUBAGENT_KEY_MAX) out.key = scrubNativeText(update.key, SUBAGENT_KEY_MAX, scrub);
+    if (update.parent === 'lead') out.parent = 'lead';
+    else if (typeof update.parent === 'string' && update.parent && update.parent !== update.id) out.parent = scoped(update.parent);
+    if (typeof update.model === 'string' && update.model) out.model = scrubNativeText(update.model, 80, scrub);
+    if (typeof update.effort === 'string' && EFFORT_RE.test(update.effort)) out.effort = update.effort;
+    // A subagent on another CLI stopped by its CLI's plan limit (E7 S7.5), cleared when it runs again.
+    if (typeof update.limited === 'boolean') out.limited = update.limited;
+    if (typeof update.parentKey === 'string') out.parentKey = cleanKey(update.parentKey);
+    if (typeof update.phase === 'string') out.phase = scrubNativeText(update.phase, 200, scrub);
+    for (const k of ['tokens', 'toolCalls']) if (Number.isSafeInteger(update[k]) && update[k] >= 0) out[k] = update[k];
+    for (const k of ['startedAt', 'endedAt']) if (typeof update[k] === 'string' && Number.isFinite(Date.parse(update[k]))) out[k] = update[k];
+    if (typeof update.result === 'string' && update.result.trim()) {
+      const full = scrubNativeText(update.result, NATIVE_WINDOW, scrub, NATIVE_WINDOW);
+      out.result = full.slice(0, SUBAGENT_RESULT_CAP);
+      out.resultStatus = update.resultStatus === 'truncated' || update.result.length > NATIVE_WINDOW || full.length > SUBAGENT_RESULT_CAP ? 'truncated' : 'complete';
+    }
+    return out;
+  };
   return {
     agentId: scoped,
     /**
@@ -283,11 +342,44 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
       }
       if (typeof fields.now === 'string') fields.now = fields.now.replace(/\s+/g, ' ').trim();
       if (SUBAGENT_STATUSES.includes(update.status)) fields.status = update.status;
+      Object.assign(fields, detailOf(update));
       const previous = agentReadings.get(update.id) ?? {};
-      if (agentReadings.has(update.id) && Object.entries(fields).every(([k, v]) => previous[k] === v)) return;
-      if (!agentReadings.has(update.id) && agentReadings.size >= SUBAGENT_CAP) return;
+      if (!agentReadings.has(update.id) && fields.kind !== 'workflow' && [...agentReadings.values()].filter(a => a.kind !== 'workflow').length >= SUBAGENT_CAP) {
+        // A 33rd child runs; its record does not (D25): the turn says how many.
+        if (!unrecorded.has(update.id)) {
+          notRecorded += 1;
+          if (unrecorded.size < 4_096) unrecorded.add(update.id);
+          extrasPending = true; dirty = true; schedule();
+        }
+        return;
+      }
+      if (!agentReadings.has(update.id)) {
+        // Where the lead stood when the child was first seen, and when.
+        fields.position = leadCount;
+        fields.startedAt ??= new Date().toISOString();
+      }
+      const key = fields.key ?? previous.key, title = fields.title ?? previous.title;
+      // The ledger learns a child's key (and the names a Codex follow-up may
+      // use for it) and answers the turns it appeared in, this one included.
+      if (key && (key !== previous.key || title !== previous.title) && typeof runsOf === 'function') {
+        let runs = null;
+        try { runs = runsOf(key, { title }); } catch { /* the ledger is a readout */ }
+        if (Array.isArray(runs)) fields.runs = runs.filter(r => typeof r === 'string' && RUN_ID_RE.test(r)).slice(-SUBAGENT_RUNS_CAP);
+      }
+      const status = fields.status ?? previous.status;
+      if (SETTLED_SUBAGENT_STATUSES.includes(status)) { if (!previous.endedAt) fields.endedAt ??= new Date().toISOString(); }
+      const same = (k, v) => k === 'endedAt' ? Boolean(previous.endedAt) : k === 'runs' ? JSON.stringify(previous.runs) === JSON.stringify(v) : previous[k] === v;
+      if (agentReadings.has(update.id) && Object.entries(fields).every(([k, v]) => same(k, v))) return;
       const reading = { ...previous, ...fields };
+      // A child running again (a follow-up) has not ended.
+      if (!SETTLED_SUBAGENT_STATUSES.includes(status)) delete reading.endedAt;
       agentReadings.set(update.id, reading);
+      if (reading.kind === 'workflow') {
+        const siblings = [...agentReadings].filter(([, a]) => a.kind === 'workflow' && a.parentKey === reading.parentKey)
+          .sort((a, b) => (b[1].startedAt ?? '').localeCompare(a[1].startedAt ?? ''));
+        for (const [id] of siblings.slice(WORKFLOW_AGENT_CAP)) agentReadings.delete(id);
+        if (!agentReadings.has(update.id)) return;
+      }
       // A later update repairs metadata whose first report was shed while
       // offline; a delta alone cannot recover the child's prompt or title.
       push({ k: 'agent', id: scoped(update.id), ...reading });
@@ -319,6 +411,38 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
       }
       if (fresh.length) push({ k: 'note', t: scrub(`The CLI reported MCP servers that are not connected: ${fresh.join(', ')}.`).slice(0, TRACE_PROSE_CAP) });
     },
+    /**
+     * ONE SHELL COMMAND THE LEAD RAN THAT STARTS ANOTHER CLI (D23): its row
+     * by call id, updated at its result. Shown and never blocked, never a
+     * subagent and never counted toward the 32. `row` is outsideCli.mjs's.
+     */
+    outside(id, row) {
+      if (stopped || typeof id !== 'string' || !id || !row) return;
+      const previous = outsideRows.get(id);
+      if (!previous && outsideRows.size >= OUTSIDE_CAP) return;
+      const next = { ...(previous ?? {
+        id: scrubNativeText(id, 96, scrub), position: leadCount, startedAt: new Date().toISOString(),
+      }) };
+      if (typeof row.cli === 'string') next.cli = row.cli;
+      if (typeof row.model === 'string' && row.model) next.model = scrubNativeText(row.model, 80, scrub);
+      if (typeof row.command === 'string') next.command = scrubNativeText(row.command, OUTSIDE_COMMAND_CAP, scrub);
+      if (OUTSIDE_STATUSES.includes(row.status)) next.status = row.status;
+      if (next.status && next.status !== 'running' && !next.endedAt) next.endedAt = new Date().toISOString();
+      if (previous && JSON.stringify(previous) === JSON.stringify(next)) return;
+      outsideRows.set(id, next);
+      extrasPending = true; dirty = true; schedule();
+    },
+    workflow(row) {
+      if (stopped || !row) return;
+      if (row.launcherId && workflowPositions.size < WORKFLOW_CAP && !workflowPositions.has(row.launcherId)) workflowPositions.set(row.launcherId, leadCount);
+      if (!row.id || (!workflowRows.has(row.id) && workflowRows.size >= WORKFLOW_CAP)) return;
+      const { launcherId, ...next } = row;
+      next.position = workflowRows.get(row.id)?.position ?? workflowPositions.get(launcherId) ?? leadCount;
+      for (const k of ['id', 'key', 'name', 'description']) if (typeof next[k] === 'string') next[k] = scrubNativeText(next[k], k === 'description' ? 600 : 200, scrub);
+      next.phases = (next.phases ?? []).slice(0, 64).map(p => ({ ...p, title: scrubNativeText(p.title, 200, scrub) }));
+      workflowRows.set(row.id, next);
+      extrasPending = true; dirty = true; schedule();
+    },
     flush,
     /** No more entries, no more timers. The queue survives so a final flush can
      *  still deliver it. */
@@ -326,8 +450,12 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
       if (!stopped && orchestrationVersion === 2) {
         // Even a quiet child retains its identity after another child's noisy
         // stream overflowed the relay. These snapshots remain sequence-safe.
-        for (const [id, reading] of agentReadings) push({ k: 'agent', id: scoped(id), ...reading });
+        for (const [id, reading] of agentReadings) {
+          const steps = childSteps.get(scoped(id));
+          push({ k: 'agent', id: scoped(id), ...reading, ...(steps ? { steps } : {}) });
+        }
       }
+      if (!stopped && (notRecorded > 0 || outsideRows.size || workflowRows.size)) extrasPending = true;
       stopped = true;
       if (timer) {
         clearTimeout(timer);

package/bin/lib/turnDeclaration.mjs

@@ -4,7 +4,7 @@
  * inside prose or another language's fence stay as the CLI wrote them. */
 import { jsonObjectClosers } from './modelJson.mjs';
 
-const statuses = new Set(['delivered', 'blocked', 'prerequisite', 'nothing']);
+const statuses = new Set(['delivered', 'blocked', 'prerequisite', 'split', 'nothing']);
 function declaration(body) {
   const raw = body.trim();
   if (!raw.startsWith('{')) return false;
@@ -13,13 +13,13 @@ function declaration(body) {
     return value && typeof value === 'object' && !Array.isArray(value)
       && ((Object.hasOwn(value, 'summary') && Object.hasOwn(value, 'progress'))
         || (typeof value.status === 'string'
-          && (statuses.has(value.status) || ['summary', 'progress', 'question'].some(key => Object.hasOwn(value, key)))));
+          && (statuses.has(value.status) || ['summary', 'progress', 'question', 'split'].some(key => Object.hasOwn(value, key)))));
   } catch {
     // A truncated/invalid declaration must not fall through as an answer.
     // Require a protocol key at the root's opening and the declared status;
     // arbitrary malformed JSON remains useful diagnostic output.
-    return /^\{\s*"(?:status|summary|progress|question)"\s*:/.test(raw)
-      && /"status"\s*:\s*"(?:delivered|blocked|prerequisite|nothing)"/.test(raw);
+    return /^\{\s*"(?:status|summary|progress|question|split)"\s*:/.test(raw)
+      && /"status"\s*:\s*"(?:delivered|blocked|prerequisite|split|nothing)"/.test(raw);
   }
 }
 

package/bin/lib/turnGaps.mjs

@@ -16,6 +16,7 @@
  * listed. A malformed entry costs that entry alone.
  */
 export const GAP_STATUSES = ['not built', 'partly', 'unverified', 'unowned'];
+export const GAP_DISPOSITIONS = ['required', 'owned', 'optional', 'decision'];
 export const MAX_GAPS = 40;
 export const MAX_GAP_ITEM = 300;
 export const MAX_GAP_WHY = 800;
@@ -32,7 +33,10 @@ export function parseGaps(raw, scrub) {
     const status = typeof g.status === 'string' ? g.status.trim().toLowerCase() : '';
     if (!GAP_STATUSES.includes(status)) continue;
     const why = typeof g.why === 'string' && g.why.trim() ? cut(scrub(g.why.trim()), MAX_GAP_WHY) : null;
-    out.push({ item: cut(scrub(g.item.trim()), MAX_GAP_ITEM), status, ...(why ? { why } : {}) });
+    const disposition = GAP_DISPOSITIONS.includes(g.disposition) ? g.disposition : null;
+    const ownerTaskId = typeof g.ownerTaskId === 'string' && /^[a-zA-Z0-9_-]{1,100}$/.test(g.ownerTaskId) ? g.ownerTaskId : null;
+    out.push({ item: cut(scrub(g.item.trim()), MAX_GAP_ITEM), status, ...(why ? { why } : {}),
+      ...(disposition ? { disposition } : {}), ...(ownerTaskId ? { ownerTaskId } : {}) });
   }
   return out;
 }
@@ -41,7 +45,7 @@ export function parseGaps(raw, scrub) {
 export function gapsMarkdown(gaps) {
   if (!Array.isArray(gaps)) return null;
   if (!gaps.length) return '**Gaps against the request:** none reported.';
-  return ['**Gaps against the request**', ...gaps.map((g) => `- **${g.status}** — ${oneLine(g.item)}${g.why ? `: ${oneLine(g.why)}` : ''}`)].join('\n');
+  return ['**Gaps against the request**', ...gaps.map((g) => `- **${g.status}** — ${oneLine(g.item)}${g.why ? `: ${oneLine(g.why)}` : ''}${g.disposition ? ` (${g.disposition}${g.ownerTaskId ? `: card ${g.ownerTaskId}` : ''})` : ''}`)].join('\n');
 }
 
 const oneLine = (s) => s.replace(/\s*\n\s*/g, ' ');

package/bin/lib/turnSubagents.mjs

@@ -17,6 +17,11 @@
  * bounds and settles its own records, so only an unowned turn is counted
  * here; and native transcript reads are readouts, so the drain at close is
  * bounded and never holds the card's answer.
+ *
+ * EVERY UPDATE NAMES ITS CLI AND, ONCE KNOWN, ITS KEY (2026-11-06, S4.1):
+ * the identity the CLI itself keeps for the child across turns — Claude's
+ * native agent id, Codex's child thread id — so a child resumed in a later
+ * turn is the same record there (workAgentResume.mjs keeps which turns).
  */
 
 import { handleStreamLine } from './claudeStream.mjs';
@@ -24,35 +29,44 @@ import { createClaudeSubagents } from './claudeSubagents.mjs';
 import { createClaudeSubagentProgress } from './claudeSubagentProgress.mjs';
 import { createCodexSubagentReader } from './codexSubagents.mjs';
 import { humanizeClaudeTool } from './runtimeEvents.mjs';
-import { SUBAGENT_CAP } from './subagentBounds.mjs';
+import { SUBAGENT_CAP, SUBAGENT_KEY_MAX } from './subagentBounds.mjs';
+
+/** The child's stable identity, `<cli>:<native id>`, or nothing yet. */
+export function subagentKey(runtime, update) {
+  const native = runtime === 'codex' ? update.id : runtime === 'claude' ? update.nativeId : null;
+  const key = typeof native === 'string' && native ? `${runtime}:${native}` : null;
+  return key && key.length <= SUBAGENT_KEY_MAX ? key : null;
+}
 
 /**
  * `sinks` are the turn's own: its console, activity, tool-event and text
  * sinks, which a Claude child's transcript rows feed as its stream does.
  */
-export function createTurnSubagents({ runtime, cwd, since, env, owned, onSubagent, onSpawnResult, resumeThreadId,
+export function createTurnSubagents({ runtime, cwd, since, env, owned, onSubagent, onWorkflow, onSpawnResult, resumeThreadId, knownSubagents,
   sinks: { emit, onActivity, onToolEvent, appendText, onDetail } }) {
   // An orchestrator bounds its own records and settles them at close
   // (orchestrator.mjs). Counted here by stream id, refused retries used up
   // the 32 and later children's updates were dropped; the exit sweep
   // reported 'stopped' off stream state the controller had already settled.
   const agentStates = new Map();
-  const reportSubagent = (update) => {
-    if (!update?.id) return;
-    if (!owned) {
-      if (!agentStates.has(update.id) && agentStates.size >= SUBAGENT_CAP) return;
+  const reportSubagent = (raw) => {
+    if (!raw?.id) return;
+    const key = subagentKey(runtime, raw);
+    const update = { ...raw, cli: runtime, ...(key ? { key } : {}) };
+    // Past the cap a child is still handed on: the trace relay counts it as
+    // not recorded (its `notRecorded`), and the sweep does not follow it.
+    if (!owned && raw.kind !== 'workflow' && (agentStates.has(update.id) || agentStates.size < SUBAGENT_CAP))
       agentStates.set(update.id, update.status ?? agentStates.get(update.id) ?? 'running');
-    }
     onSubagent?.(update);
   };
-  const subagents = createClaudeSubagents(reportSubagent);
+  const subagents = createClaudeSubagents(reportSubagent, onWorkflow);
   const claudeProgress = runtime === 'claude' && onSubagent ? createClaudeSubagentProgress({
     cwd, since, env,
     onLine: line => handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText,
       answerFromResult: true, subagents, onDetail }),
   }) : null;
   const codexAgents = runtime === 'codex' && onSubagent ? createCodexSubagentReader({
-    since, env,
+    since, env, knownTargets: knownSubagents ?? null,
     onSubagent: reportSubagent,
     onActivity: (activity) => {
       emit(activity.kind === 'error' ? activity.full ?? activity.label : activity.label + '\n', activity);

package/bin/lib/uiReview.mjs

@@ -12,6 +12,7 @@ import { procStat } from './procStat.mjs';
 import { killGroup } from './processGroup.mjs';
 import { unattendedEnv } from './noWindowEnv.mjs';
 import { childEnv } from './childEnv.mjs';
+import { environmentOverlay, readWorktreeEnvironment } from './reviewEnvironment.mjs';
 import { gitRaw } from './git.mjs';
 import { serveMcpStdio } from './mcpStdio.mjs';
 import { scrub, learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs';
@@ -172,8 +173,10 @@ export async function createUiReview({ wt, signal, capture = captureLocalReview,
       record.folder = `${ARTIFACT_DIR}/${name}`;
       record.artifact = `${record.folder}/report.json`;
       scratch = mkdtempSync(join(tmpdir(), 'flowviant-ui-preview-'));
-      const env = unattendedEnv(childEnv({ cwd }), { browserHome: scratch });
-      // No inherited personal home, SDK credentials or browser sessions.
+      const environment = readWorktreeEnvironment(wt);
+      const env = unattendedEnv({ ...childEnv({ cwd }), ...(environment ? environmentOverlay(environment) : {}) }, { browserHome: scratch });
+      // Only explicit scoped bindings join the minimal preview environment;
+      // no inherited personal home, SDK credentials or browser sessions.
       env.HOME = scratch; env.USERPROFILE = scratch; env.XDG_CONFIG_HOME = scratch;
       env.XDG_DATA_HOME = scratch; env.XDG_CACHE_HOME = scratch;
       let output = '';

package/bin/lib/wikiDraft.mjs

@@ -8,6 +8,7 @@ import { ensureRealSubdir } from './ownedDirs.mjs';
 import { isSafePath, assertWikiDraftFits } from './vaultDiff.mjs';
 
 import { wikiScalars as scalars, protectedWikiPage } from './wikiOwnership.mjs';
+import { SYSTEM_ARCHITECTURE_PATH, readSystemArchitecture } from './architectureReport.mjs';
 
 /** Never follow links into an imported vault. A partial read cannot be a draft
  * basis: fail before the CLI starts rather than infer missing pages as deleted. */
@@ -60,6 +61,14 @@ export function beginWikiDraft(vaultDir) {
     discard: () => rmSync(dir, { recursive: true, force: true }),
     publish({ sha, repoFullName }) {
       const candidate = pages(dir, '', new Map(), true);
+      const architecture = candidate.get(SYSTEM_ARCHITECTURE_PATH);
+      const oldArchitecture = before.get(SYSTEM_ARCHITECTURE_PATH);
+      if (!protectedWikiPage(SYSTEM_ARCHITECTURE_PATH, oldArchitecture ?? architecture ?? '')) {
+        const parsed = readSystemArchitecture(architecture ?? '');
+        if (parsed.status === 'invalid' || (oldArchitecture && readSystemArchitecture(oldArchitecture).status === 'available' && parsed.status !== 'available')) {
+          throw new Error('Architecture report is incomplete or invalid; last good wiki retained');
+        }
+      }
       const changes = new Map();
       for (const [path, text] of candidate) {
         const old = before.get(path);

package/bin/lib/work.mjs

@@ -67,6 +67,8 @@ import { placeTurnLockedByLivePid } from './turnLock.mjs';
 import { createWorkLocalCleanup } from './workLocalCleanup.mjs';
 import { createManagedLocalCleanup } from './managedLocalCleanup.mjs';
 import { trackedRepositorySetup } from './repositorySetup.mjs';
+import { sweepWorktreeEnvironments } from './reviewEnvironment.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
 import { createRepositoryPlaces } from './repositoryPlaces.mjs';
 import { createAgentRepositories } from './agentRepositories.mjs';
 import { createWorkProcesses } from './workProcesses.mjs';
@@ -395,6 +397,7 @@ export function createWorkManager({
   // The check and the pre-review are built with only what each one uses; the
   // review entry beat is handed the two and owns only their order.
   const { runCheck } = createWorkAgentCheck({
+    baseRef,
     repoRoot,
     postBestEffort,
     workChildren,
@@ -461,6 +464,23 @@ export function createWorkManager({
     sweepMergedSessionBranch,
   });
 
+  let environmentSweep = null, lastEnvironmentSweep = 0;
+  const reconcileEnvironments = () => {
+    if (environmentSweep || workLanesStopped() || Date.now() - lastEnvironmentSweep < 60_000) return;
+    lastEnvironmentSweep = Date.now();
+    environmentSweep = (async () => {
+      const roots = [...new Set(repositories?.list().map(r => r.repoRoot).filter(Boolean) ?? [repoRoot])];
+      for (const root of roots) {
+        if (workLanesStopped()) break;
+        const result = await sweepWorktreeEnvironments(root, {
+          onSpawn: ch => { workChildren.set(ch, null); groupKillChildren.add(ch); },
+          onClose: ch => { workChildren.delete(ch); groupKillChildren.delete(ch); },
+        });
+        for (const failure of result.errors) warn(envScrub(`Environment ${failure.id}: ${failure.error}`));
+      }
+    })().catch(error => warn(envScrub(error.message))).finally(() => { environmentSweep = null; });
+  };
+
   const { processKillJobs } = createWorkProcesses({
     placeDir,
     reportPlaceWorktrees,
@@ -498,7 +518,7 @@ export function createWorkManager({
     workChildren.size > 0 ||
     workAnswering.size > 0 ||
     pendingWorkReports.size > 0 ||
-    pendingShipReports.size > 0 || cleanupBusy();
+    pendingShipReports.size > 0 || cleanupBusy() || environmentSweep !== null;
 
   return {
     flushWorkReports,
@@ -514,6 +534,7 @@ export function createWorkManager({
     retirePreviews,
     shutdownPreviews,
     retireWorkSessions,
+    reconcileEnvironments,
     reportWorktrees,
     reconcileIdleArtifacts,
     reconcileLocalCleanup,

package/bin/lib/workAgentCheck.mjs

@@ -21,6 +21,9 @@ import { scrub as envScrub } from './uplinkScrub.mjs';
 import { agentBrowserHome, openBrowserHome, unattendedEnv } from './noWindowEnv.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { workLanesStopped } from './standDownGate.mjs';
+import { setupRepository } from './repositorySetup.mjs';
+import { readEnvironmentRecipe } from './reviewEnvironmentConfig.mjs';
+import { holdWorktreeEnvironment } from './reviewEnvironment.mjs';
 
 /**
  * CLEAR THE ARTIFACTS DIRECTORY OF ANYTHING THAT IS NOT AN ARTIFACT, BEFORE
@@ -135,6 +138,7 @@ export function readConfiguredCheck(root) {
 
 export function createWorkAgentCheck({
   repoRoot,
+  baseRef = () => 'HEAD',
   postBestEffort,
   workChildren,
   groupKillChildren,
@@ -184,6 +188,24 @@ export function createWorkAgentCheck({
       await postCheck({ agentId, status: 'none', ...(headSha ? { headSha } : {}) });
       return { status: 'none' };
     }
+    let environment = null, releaseEnvironment = () => {};
+    try {
+      const root = repository?.repoRoot ?? repoRoot;
+      const snapshot = readEnvironmentRecipe(root, repository?.baseRef ?? baseRef());
+      if (snapshot) {
+        // A combined merge has a different worktree/database from its input
+        // agents. Migrate its CURRENT integrated source before its checks.
+        environment = await setupRepository(root, wt, { snapshot,
+          onSpawn: ch => { workChildren.set(ch, agentId); groupKillChildren.add(ch); },
+          onClose: ch => { workChildren.delete(ch); groupKillChildren.delete(ch); } });
+        releaseEnvironment = holdWorktreeEnvironment(environment);
+      }
+    } catch (error) {
+      const text = envScrub(error.message);
+      await postCheck({ agentId, status: 'failed', output: text, ...(headSha ? { headSha } : {}) });
+      return { status: 'failed', text };
+    }
+    try {
     const cleared = clearNonArtifacts(wt);
     if (cleared.length)
       warn(
@@ -241,7 +263,7 @@ export function createWorkAgentCheck({
           shell: true,
           detached: true,
           stdio: ['ignore', 'pipe', 'pipe'],
-          env: checkEnv(process.env, browser.dir),
+          env: checkEnv(environment?.env ?? process.env, browser.dir),
         });
         /**
          * …AND IT IS TRACKED, so a stop or a takeover takes it with them.
@@ -330,6 +352,7 @@ export function createWorkAgentCheck({
       ...(headSha ? { headSha } : {}),
     });
     return out;
+    } finally { releaseEnvironment(); }
   };
 
   return { runCheck };

package/bin/lib/workAgentResume.mjs

@@ -25,6 +25,7 @@
 import { existsSync, writeFileSync } from 'node:fs';
 import { CLAUDE_SESSION_RE, CODEX_THREAD_RE, RESUME_MARKERS } from './conversationIds.mjs';
 import { pinId, readPinnedId } from './resumeMarker.mjs';
+import { subagentLedger } from './subagentLedger.mjs';
 
 /**
  * One agent turn's resume. `sessionMetaPath` is the lane's (a path in the
@@ -32,9 +33,11 @@ import { pinId, readPinnedId } from './resumeMarker.mjs';
  * `resumeThreadId`, the kept `codexHome`, and what the run tells it as the
  * CLI speaks: `sawSession` (Claude's init), `sawThread` (Codex's
  * `thread.started`), `forgetThread` (a lost resume retried fresh), `threadNow`
- * and, once the turn is over, `persist`.
+ * and, once the turn is over, `persist`. `subagents` is the agent's subagent
+ * ledger for this turn (subagentLedger.mjs): which turns each child appeared
+ * in, written with the markers.
  */
-export function agentTurnResume({ rt, wt, agentId, sessionMetaPath }) {
+export function agentTurnResume({ rt, wt, agentId, sessionMetaPath, turnId }) {
   // ONE AGENT IS ONE DIRECTORY, so the CLI's own cwd-keyed resume is exactly
   // right here — the ambiguity that forced per-tab session pinning in the
   // Workbench (many tabs, one place) cannot arise. The marker is what
@@ -86,8 +89,13 @@ export function agentTurnResume({ rt, wt, agentId, sessionMetaPath }) {
   const codexAgentHome =
     rt === 'codex' ? sessionMetaPath(wt, 'flowviant-agent-codex-home', agentId) : null;
 
+  // Its children's turns, kept beside the markers (a child resumes only where
+  // its conversation does), per agent and per CLI: keys never cross CLIs.
+  const subagents = subagentLedger(sessionMetaPath(wt, `flowviant-agent-subagents-${rt}`, agentId), turnId);
+
   return {
     resume,
+    subagents,
     resumeThreadId: codexResumeId || claudeResumeId || undefined,
     codexHome: codexAgentHome,
     /** Claude's session id from its init, pinned at once (a Claude turn only). */
@@ -116,6 +124,7 @@ export function agentTurnResume({ rt, wt, agentId, sessionMetaPath }) {
       // id learned mid-turn is only true once the turn that learned it ends.
       // Best-effort — the next turn runs fresh.
       pinId(codexThreadMarker, CODEX_THREAD_RE, seenThreadId);
+      subagents.persist();
     },
   };
 }

package/bin/lib/workAgentTools.mjs

@@ -28,6 +28,7 @@ import { machineMcpServers } from './claudeMachineMcp.mjs';
 import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
 import { VIDEO_SERVER } from './videoRender.mjs';
 import { BROWSER_SERVER } from './managedBrowser.mjs';
+import { RUNTIME_REVIEW_SERVER } from './runtimeReview.mjs';
 
 /** The servers the daemon itself mounts on a card turn, by the names the
  *  agent calls them: a multi-repository card's add_repository, an
@@ -35,7 +36,7 @@ import { BROWSER_SERVER } from './managedBrowser.mjs';
  *  render_video (2026-10-26), and a code turn's managed browser (2026-10-30).
  *  Never a project server's, whatever the base
  *  `.mcp.json` names. */
-export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review', video: VIDEO_SERVER, browser: BROWSER_SERVER });
+export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review', video: VIDEO_SERVER, browser: BROWSER_SERVER, runtime: RUNTIME_REVIEW_SERVER });
 
 /**
  * The card turn's tools, prepared, and what it is told of them.
@@ -48,13 +49,13 @@ export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositorie
  * from here), the note, the mount's part of the CLI's `mcpEnv` and whether it
  * needs one, and the keys the runner takes the mount as.
  */
-export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, videoConfig = null, browserConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
+export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, videoConfig = null, browserConfig = null, runtimeConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
   // A turn reads the base ref afresh. Changes the agent has made to its
   // own worktree cannot silently change the next turn's tools.
   const source = sources.find((r) => r.wt === wt);
-  const snapshot = readBaseTools(source?.repoRoot ?? repoRoot, source?.baseRef ?? baseRef());
+  const snapshot = readBaseTools(source?.repoRoot ?? repoRoot, source?.baseRef ?? baseRef(), env);
   for (const other of sources.filter((r) => r !== source)) {
-    const base = readBaseTools(other.repoRoot, other.baseRef);
+    const base = readBaseTools(other.repoRoot, other.baseRef, env);
     snapshot.instructions.push(...[...base.instructions, ...base.skillFiles].map((file) => ({ ...file, path: `repositories/${other.folder}/${file.path}` })));
   }
   const projectTools = prepareAgentTools(snapshot, rt, env, wt, { codexHome, fenced: posture !== 'build', turnServers: {
@@ -62,6 +63,7 @@ export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources =
     ...(orchestratorConfig ? { [CARD_TURN_SERVERS.orchestrator]: orchestratorConfig } : {}),
     ...(posture === 'build' && uiReviewConfig ? { [CARD_TURN_SERVERS.uiReview]: uiReviewConfig } : {}),
     ...(posture === 'build' && browserConfig ? { [CARD_TURN_SERVERS.browser]: browserConfig } : {}),
+    ...(posture === 'build' && runtimeConfig ? { [CARD_TURN_SERVERS.runtime]: runtimeConfig } : {}),
     // A video card's render tool rides its fenced posture (videoRender.mjs).
     ...(videoConfig ? { [CARD_TURN_SERVERS.video]: videoConfig } : {}),
   } });