flowviant 0.125.12 → 0.125.15

package/bin/lib/readOnlyRun.mjs

@@ -0,0 +1,172 @@
+/** Native investigation coordination for a held read-only attempt. No card,
+ * board token, project config or personal MCP server enters this capability.
+ * Capture can reuse the same lifecycle with its own attempt identity. */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createOrchestrator } from './orchestrator.mjs';
+import { claudeOrchestrationSafe } from './orchestratorHooks.mjs';
+import { codexSubagentsSafe } from './runtimeCodex.mjs';
+import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
+import { SUBAGENT_CAP, SUBAGENT_FIELD_CAPS } from './subagentBounds.mjs';
+import { runCappedTurn } from './workCappedTurn.mjs';
+import { killGroup } from './processGroup.mjs';
+import { scrub, scrubCut } from './uplinkScrub.mjs';
+import { toml } from './codexToml.mjs';
+import { heldToolArgv } from './heldTool.mjs';
+import { fleetRequest } from './fleetPost.mjs';
+import { DAEMON_INSTANCE } from './config.mjs';
+
+/** Transport failure is unknown, never a fabricated Stop. Only a measured
+ * holder/attempt mismatch cancels a root and its read-only descendants. */
+export async function watchReadOnlyAttempt(url, job, request = fleetRequest) {
+  const controller = new AbortController();
+  let busy = false, closed = false;
+  const check = async () => {
+    if (busy || closed) return;
+    busy = true;
+    try {
+      const r = await request(url, { body: { id: job.id, attempt: job.attempt, instance: DAEMON_INSTANCE }, timeoutMs: 15_000 });
+      if (!closed && r.ok && r.json?.data?.active === false) controller.abort();
+    } catch { /* an unanswered holder read is unknown */
+    } finally { busy = false; }
+  };
+  await check();
+  const timer = setInterval(check, 5_000);
+  timer.unref?.();
+  return { signal: controller.signal, check, stop: () => { closed = true; clearInterval(timer); } };
+}
+
+export const readOnlyCoordinationSafe = (runtime, version) => runtime === 'claude'
+  ? claudeOrchestrationSafe(version) : runtime === 'codex' && codexSubagentsSafe(version);
+
+function coordinationMount(runtime, controller, rootTools) {
+  const servers = { [ORCHESTRATOR_SERVER]: controller.config,
+    ...(rootTools ? { flowviant: { ...controller.config, args: heldToolArgv('__capture-mcp') } } : {}) };
+  if (runtime === 'codex') {
+    return { args: Object.entries(servers).flatMap(([name, config]) => {
+      const key = `mcp_servers.${name}`;
+      return ['-c', `${key}.command=${toml(config.command)}`,
+        '-c', `${key}.args=${JSON.stringify(config.args)}`,
+        '-c', `${key}.env_vars=${JSON.stringify(Object.keys(controller.env))}`,
+        '-c', `${key}.default_tools_approval_mode="approve"`];
+    }), cleanup() {} };
+  }
+  const dir = mkdtempSync(join(tmpdir(), 'flowviant-read-coordination-'));
+  try {
+    const path = join(dir, 'mcp.json');
+    writeFileSync(path, JSON.stringify({ mcpServers: servers }), { mode: 0o600 });
+    return { args: ['--strict-mcp-config', '--mcp-config', path], cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+  } catch (error) { rmSync(dir, { recursive: true, force: true }); throw error; }
+}
+
+/** The root is counted by runCappedTurn's workChildren registration; native
+ * children retain reservations in the SAME admit pool until measured stopped.
+ * Each invocation mints a fresh capability, including diagnosis → retry.
+ * Late callbacks cannot repaint a replacement consult's activity/evidence. */
+export async function createReadOnlyCoordination({ enabled = false, identity, runtime, version, admit, children = {}, signal,
+  contract = '', createController = createOrchestrator, onUnavailable = () => {}, rootTools = null }) {
+  if (!enabled || signal?.aborted || !readOnlyCoordinationSafe(runtime, version)) return null;
+  if (!identity || !['plan', 'capture'].includes(identity.scope) || !identity.id ||
+    !Number.isSafeInteger(identity.attempt) || identity.attempt < 0) {
+    onUnavailable(new Error('Read-only coordination needs a held attempt identity.'));
+    return null;
+  }
+  let controller = null, mount = null, active = true;
+  let root = null, killed = false;
+  const kill = child => { if (killed || !child) return; killed = true; killGroup(child); };
+  const agents = new Map();
+  const nonce = randomUUID();
+  const label = native => {
+    const id = controller?.resolve(native) ?? native;
+    const a = agents.get(id);
+    return scrubCut(a?.title || a?.kind || id, 120);
+  };
+  const trace = {
+    agent(update) {
+      if (!active || signal?.aborted || !agents.has(update.id) && agents.size >= SUBAGENT_CAP) return;
+      const prior = agents.get(update.id) ?? {};
+      const row = { ...prior, id: update.id };
+      for (const [key, cap] of Object.entries(SUBAGENT_FIELD_CAPS)) if (typeof update[key] === 'string') row[key] = scrubCut(update[key], cap);
+      if (update.status) row.status = update.status;
+      agents.set(update.id, row);
+    },
+    // Questions and native choice notes remain inside the CLI coordination;
+    // only observed CLI activity reaches the existing progress line below.
+    prose() {}, handoff() {}, flush: async () => {},
+  };
+  try {
+    controller = await createController({ runtime, readOnlyRun: identity, signal, trace, admit, rootTools,
+      children: { ...children, access: 'read' } });
+    mount = coordinationMount(runtime, controller, rootTools);
+  } catch (error) {
+    await controller?.close(true); rootTools?.close();
+    onUnavailable(error);
+    return null;
+  }
+  return {
+    kill,
+    wrap(turnArgs) {
+      if (turnArgs.profile !== (rootTools ? 'plan' : 'consult') || turnArgs.mcpConfig || turnArgs.mcpArgs?.length ||
+        turnArgs.projectMcpServers?.length || turnArgs.machineMcp || turnArgs.mcpEnv?.FLOWVIANT_MCP_TOKEN)
+        throw new TypeError('Read-only coordination requires a fenced turn without external MCP credentials.');
+      return { ...turnArgs, orchestration: true, readOnlyCoordination: true,
+        system: [turnArgs.system, contract].filter(Boolean).join('\n\n'),
+        ...(runtime === 'claude' ? { claudeVersion: version } : { codexVersion: version }),
+        mcpArgs: mount.args, mcpEnv: controller.env,
+        onSpawn: child => { root = child; turnArgs.onSpawn?.(child); },
+        onInit: init => { if (active && !signal?.aborted) { controller.root(init.sessionId); turnArgs.onInit?.(init); } },
+        onThreadId: id => { if (active && !signal?.aborted) { controller.root(id); turnArgs.onThreadId?.(id); } },
+        ...Object.fromEntries(['onAnswer', 'onUsage', 'onModel', 'onContext', 'onCliFailure', 'onExit'].map(key =>
+          [key, (...args) => { if (active && !signal?.aborted) turnArgs[key]?.(...args); }])),
+        onSubagent: update => { if (active && !signal?.aborted) controller.observe(update); },
+        onSpawnResult: result => { if (active && !signal?.aborted) controller.spawnResult(result); },
+        onActivity: activity => {
+          if (!active || signal?.aborted) return;
+          if (!activity?.agentId) { turnArgs.onActivity?.(activity); return; }
+          controller.attributed(activity.agentId, id => {
+            if (active && !signal?.aborted && activity.label) turnArgs.onActivity?.({ ...activity, label: `${label(id)}: ${activity.label}` });
+          });
+        },
+        onToolEvent: (name, input, meta = {}) => {
+          if (!active || signal?.aborted) return;
+          const push = id => turnArgs.onToolEvent?.(name, input, { ...meta,
+            // Runtime call ids can repeat across children and fresh consults.
+            // A citation in final prose never creates a reader observation.
+            ...(meta.id ? { id: createHash('sha256').update(`${nonce}\0${id ?? 'root'}\0${meta.id}`).digest('hex') } : {}),
+            ...(id ? { agentId: id, agentTitle: label(id) } : {}),
+          });
+          if (meta.agentId) controller.attributed(meta.agentId, push); else push(null);
+        },
+      };
+    },
+    async close(stopped = false) {
+      active = false; kill(root);
+      try { await controller.close(stopped || Boolean(signal?.aborted)); }
+      finally { mount.cleanup(); }
+    },
+  };
+}
+
+/** Scratch planning retains its capped, transcript-removing lifecycle.
+ * Capture consumes the same coordination factory around its own resumable
+ * conversation lifecycle and keeps its transcript. */
+export async function runReadOnlyConsult({ ...options }) {
+  const { turnArgs } = options;
+  if (turnArgs.profile !== 'consult' || turnArgs.mcpConfig || turnArgs.mcpArgs?.length ||
+    turnArgs.projectMcpServers?.length || turnArgs.machineMcp || turnArgs.mcpEnv?.FLOWVIANT_MCP_TOKEN) {
+    options.releaseSlot?.();
+    throw new TypeError('Read-only coordination requires a consult without board, staging or external MCP credentials.');
+  }
+  const coordination = await createReadOnlyCoordination({ ...options, runtime: turnArgs.runtime });
+  if (!coordination) return runCappedTurn(options);
+  try {
+    // The cap composes onSpawn/onInit itself; adapt its wrapper callbacks
+    // beside turnArgs so transcript and root-count bookkeeping stay there.
+    const wrapped = coordination.wrap({ ...turnArgs, onSpawn: options.onSpawn, onInit: options.onInit });
+    const { onSpawn, onInit, ...args } = wrapped;
+    const result = await runCappedTurn({ ...options, turnArgs: args, onSpawn, onInit, killChild: coordination.kill });
+    return { ...result, out: scrub(result.out) };
+  } finally { await coordination.close(); }
+}

package/bin/lib/runTurn.mjs

@@ -197,6 +197,7 @@ function runPlainTurn(opts) {
     const args = rt.args({
       cardTurn: opts.cardTurn === true,
       orchestration: opts.orchestration === true,
+      readOnlyCoordination: opts.readOnlyCoordination === true,
       // The lane's own measurement when it decided to orchestrate, so the
       // hooks and the controller cannot disagree (workAgentTurnExecution.mjs).
       codexVersion: opts.codexVersion ?? measuredRuntimeVersion('codex')?.version,

package/bin/lib/runtimeClaude.mjs

@@ -16,9 +16,9 @@ import { join } from 'node:path';
 import { MODEL, USER_AGENT } from './config.mjs';
 import { NO_SETTING_SOURCES, personalClaudeSettings, releaseTurnSettings, withPersonalSettings, writeTurnSettings } from './claudePersonal.mjs';
 import { machineMcpServers } from './claudeMachineMcp.mjs';
-import { claudePermFor, withMachineMcp, withNativeChildren } from './claudePosture.mjs';
+import { claudePermFor, withMachineMcp, withNativeChildren, withReadOnlyCoordination } from './claudePosture.mjs';
 import { withSettings } from './claudeSettingsArg.mjs';
-import { orchestratorHooks } from './orchestratorHooks.mjs';
+import { orchestratorHooks, claudeOrchestrationSafe } from './orchestratorHooks.mjs';
 import { orchestratesPosture } from './orchestratorPrompt.mjs';
 import { versionAtLeast } from './versionOrder.mjs';
 
@@ -123,7 +123,7 @@ export const CLAUDE_RUNTIME = {
    * strongest form of it available anywhere: `--append-system-prompt` sits
    * above the conversation rather than inside it.
    */
-  args({ writableDirs = [], prompt, system, model, effort, resume, perm: postureList, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, baseMcp = [], mcpCheckout = null, streamInput = false, orchestration = false, claudeVersion = null }) {
+  args({ writableDirs = [], prompt, system, model, effort, resume, perm: postureList, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, baseMcp = [], mcpCheckout = null, streamInput = false, orchestration = false, readOnlyCoordination = false, claudeVersion = null }) {
     // THE CARTOGRAPHER'S FENCE NAMES ITS VAULT (2026-10-10): its one write rule
     // is the vault's absolute path (claudePosture.mjs `wikiPermFor`), so a turn
     // with no vault, or one no rule can name, has no list — refused here in
@@ -193,8 +193,9 @@ export const CLAUDE_RUNTIME = {
     const fenced = profile !== 'build';
     // THE GATE RIDES A CODE OR RESEARCH CARD (2026-10-19, orchestratorPrompt.mjs);
     // a research card's list then admits the children its fence denied.
-    const gated = orchestration && orchestratesPosture(profile);
-    const perm = gated && fenced ? withNativeChildren(postureList) : postureList;
+    const readCoordinator = orchestration && readOnlyCoordination && ['consult', 'plan'].includes(profile) && claudeOrchestrationSafe(claudeVersion);
+    const gated = readCoordinator || orchestration && orchestratesPosture(profile);
+    const perm = readCoordinator ? withReadOnlyCoordination(postureList) : gated && fenced ? withNativeChildren(postureList) : postureList;
     if (fenced) a.push(...NO_SETTING_SOURCES);
     // A FENCED POSTURE NAMES ITS OWN MODE (2026-10-10). Its lists fence only
     // under the CLI's `default` mode, where a tool the list does not name is

package/bin/lib/runtimeCodex.mjs

@@ -281,7 +281,7 @@ export const CODEX_RUNTIME = {
    * limit even when its argv plus environment is far below ARG_MAX. Both exec
    * and exec resume support `-` (verified on Codex 0.160.0, 2026-10-16).
    */
-  args({ streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads, cardTurn = false, codexVersion, orchestration = false }) {
+  args({ streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads, cardTurn = false, codexVersion, orchestration = false, readOnlyCoordination = false }) {
     // Adoption resumes a conversation in ITS OWN CLI's store (claude forks,
     // agy moves) — codex has no adoptable store wired yet. Reaching here
     // with an adopt id is a wiring mistake upstream, and it fails loudly on
@@ -314,7 +314,7 @@ export const CODEX_RUNTIME = {
     const fenced = codexIgnoresUserConfig({ profile, vaultDir });
     // THE GATE RIDES A CODE OR RESEARCH CARD on a CLI whose children inherit
     // the parent's sandbox (2026-10-19, orchestratorPrompt.mjs).
-    const gated = orchestration && orchestratesPosture(fenced ? profile : 'build') && codexSubagentsSafe(codexVersion);
+    const gated = orchestration && (orchestratesPosture(fenced ? profile : 'build') || readOnlyCoordination && ['consult', 'plan'].includes(profile)) && codexSubagentsSafe(codexVersion);
     if (fenced) {
       a.push(...CODEX_FENCES[profile]({ cwd, vaultDir, researchIsolation, knowledgeDir, projectReads, subagents: gated, codexVersion }));
     } else {
@@ -466,7 +466,7 @@ const CODEX_FENCES = {
   // A CONSULT, EXPRESSED THE ONLY WAY CODEX CAN EXPRESS IT — a different
   // shape from Claude's verb allowlist, which is the whole reason `profile` is
   // a promise rather than a flag list. See codexProjectRead.mjs.
-  consult: (opts) => [...projectReadFence(opts.projectReads ?? projectReadBoundary(opts)), ...fencedTail({ codexVersion: opts.codexVersion })],
+  consult: (opts) => [...projectReadFence(opts.projectReads ?? projectReadBoundary(opts)), ...fencedTail({ subagents: opts.subagents, codexVersion: opts.codexVersion })],
   // A PLANNING SESSION. Read-only on the filesystem, exactly like a consult —
   // the writes it makes go through the control plane, not through this box —
   // and for the same reason: its prompt is steered by anything a project
@@ -475,7 +475,7 @@ const CODEX_FENCES = {
   // turn's scoped token. The plan token has the planning tools; a capture
   // token has only staging and transcript tools. The server refuses
   // everything outside that scope.
-  plan: (opts) => [...projectReadFence(opts.projectReads ?? projectReadBoundary(opts)), ...fencedTail({ codexVersion: opts.codexVersion })],
+  plan: (opts) => [...projectReadFence(opts.projectReads ?? projectReadBoundary(opts)), ...fencedTail({ subagents: opts.subagents, codexVersion: opts.codexVersion })],
   wiki: ({ vaultDir, codexVersion }) => codexWikiFence(vaultDir, codexVersion),
   // AN IMAGE CARD (0.114.0): read the repo, write ONLY the worktree's
   // `.flowviant/artifacts/`, generate pictures, and nothing else. MEASURED on

package/bin/lib/turnProfile.mjs

@@ -105,5 +105,6 @@ export function resolveTurnProfile(opts = {}) {
   if (typeof name !== 'string' || !Object.hasOwn(TURN_PROFILES, name)) {
     return { error: `unknown turn profile '${String(name).slice(0, 40)}'` };
   }
+  if (opts.readOnlyCoordination === true && !['consult', 'plan'].includes(name)) return { error: 'read-only coordination requires a consult or capture profile' };
   return { name, ...TURN_PROFILES[name] };
 }

package/bin/lib/work.mjs

@@ -109,7 +109,7 @@ export function createWorkManager({
   baseDir,
   getBaseRef,
   getMcpUrl,
-  getLeaseTtl,
+  getLeaseTtl, exportModel,
   /** "The repo picture changed — look again." See the caller in fleet.mjs. */
   onRepoChanged = () => {},
   /**
@@ -367,7 +367,7 @@ export function createWorkManager({
     sessionMetaPath,
     workChildren,
   });
-  const { runReviewEntry } = createWorkAgentReview({ runCheck, runPrecheck });
+  const { runReviewEntry, runMergeCheck } = createWorkAgentReview({ runCheck, runPrecheck });
   const processAgentRecoveryJobs = createAgentRecovery({ baseDir, repoRoot, fetchPublishedBranch: fetchPublishedBranchAsync, inPlace, placeWtFor, reportSessionWorktree });
   const { processAgentTurnJobs, interruptAgentTurns, settleAgentTurns, agentTurns, agentChildren, agentReported } = createWorkAgentTurns({
     agentRepositories, REJECT_RETRY_MS,
@@ -382,8 +382,8 @@ export function createWorkManager({
     getArtifactsAccepted,
     noteSessionGroup,
     reportSessionWorktree,
-    artifacts,
-    runReviewEntry,
+    artifacts, exportModel,
+    runReviewEntry, runMergeCheck,
     publishAgentBranch, stopAgentPublishing,
     admit,
     workChildren,
@@ -398,7 +398,7 @@ export function createWorkManager({
     baseDir,
     gitNet,
     baseRef,
-    runReviewEntry,
+    runMergeCheck,
     onRepoChanged,
     landed,
     agentRemoteAt,

package/bin/lib/workAgentMerges.mjs

@@ -43,7 +43,7 @@ export function createWorkAgentMerges({
   baseDir,
   gitNet,
   baseRef,
-  runReviewEntry,
+  runMergeCheck,
   onRepoChanged,
   landed,
   agentRemoteAt,
@@ -157,7 +157,7 @@ export function createWorkAgentMerges({
       if (job.repositoryMerge) {
         if (!repositoryPlaces) throw new Error('Project repository worktrees are unavailable.');
         const result = await mergeRepositoryPlace({ job, entries: repositoryPlaces.entries(place), baseDir,
-          check: (r) => runReviewEntry(agentId, r.wt, job.agentName, r),
+          check: (r) => runMergeCheck(agentId, r.wt, r),
           progress: async (states, retry) => {
             const response = await fleetRequest(fleetEndpoint('agent-merge-progress', FLEET_URL), {
               body: { agentId, instance: DAEMON_INSTANCE, states, retry } });
@@ -195,12 +195,12 @@ export function createWorkAgentMerges({
           });
           return;
         }
-        // The branch changed, so the previous check — and the previous
-        // pre-review — answered about a different tree. Re-read it before
-        // anything merges: a failed merge sends the agent BACK to review, which
-        // is a review-entry beat like any other, and a stale reading standing
-        // over a rebased branch is exactly what `precheckSha` exists to void.
-        const check = await runReviewEntry(agentId, wt, job.agentName);
+        // The branch changed, so the previous check answered about a different
+        // tree. Re-run it before anything merges: a failed check sends the
+        // agent BACK to review. The CHECK ALONE (`runMergeCheck`): the earlier
+        // pre-review now reads as stale by `precheckSha`, and a fresh one would
+        // hold this approved merge behind a model call (2026-10-21).
+        const check = await runMergeCheck(agentId, wt);
         if (check?.status === 'failed') {
           await report({ agentId, ok: false, detail: check.text || check.output || 'The repository check failed after folding base.' });
           return;

package/bin/lib/workAgentPlans.mjs

@@ -6,7 +6,7 @@ import { discoveryGuide } from './discoveryContract.mjs';
 import { compareRepositoryBaselines, measureRepositoryBaseline, repositoryBaselineOf } from './repositoryBaseline.mjs';
 import { knowledgeDirFor } from './knowledgeFiles.mjs';
 import { createToolLog } from './workToolLog.mjs';
-import { FLEET_URL, DAEMON_INSTANCE } from './config.mjs';
+import { FLEET_URL, DAEMON_INSTANCE, MODEL } from './config.mjs';
 import { measureAgentFootprint, liveAgentContext } from './agentFootprint.mjs';
 import { parseProposal } from './agentPlan.mjs';
 import { c, note } from './ui.mjs';
@@ -14,9 +14,11 @@ import { runTurn as defaultRunTurn } from './runTurn.mjs';
 import { SYSTEM_PLAN, AGENT_PLAN_KICKOFF, withProjectContext, REPOSITORY_BASELINE_PARAGRAPH } from './prompts.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
 import { canRun, runtimeById, runtimeLabel } from './runtimes.mjs';
-import { detectRuntimes as defaultDetectRuntimes, pickRuntimeFor as defaultPickRuntimeFor } from './runtimeDetection.mjs';
+import { detectRuntimes as defaultDetectRuntimes, pickRuntimeFor as defaultPickRuntimeFor, measuredRuntimeVersion } from './runtimeDetection.mjs';
 import { brainFor } from './workBrain.mjs';
-import { runCappedTurn } from './workCappedTurn.mjs';
+import { runReadOnlyConsult } from './readOnlyRun.mjs';
+import { planningOrchestratorContract } from './orchestratorPrompt.mjs';
+import { knownCodexModels } from './runtimeOfferings.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { claimFleetLease, fleetHeaders } from './fleetPost.mjs';
 import { REPO_PLACE } from './workPlaces.mjs';
@@ -37,6 +39,8 @@ export function createWorkAgentPlans({
   pickRuntimeFor = defaultPickRuntimeFor,
   detectRuntimes = defaultDetectRuntimes,
   authStatus = readClaudeAuthStatus,
+  runtimeVersion = id => measuredRuntimeVersion(id)?.version,
+  runConsult = runReadOnlyConsult,
 }) {
   const AGENT_PLAN_DONE_URL = fleetEndpoint('agent-plan-done', FLEET_URL);
   const AGENT_PLAN_ACTIVITY_URL = fleetEndpoint('agent-plan-activity', FLEET_URL);
@@ -55,10 +59,10 @@ export function createWorkAgentPlans({
   // the CLI path-validates itself, and the `git` readers, which it does not —
   // their path fence is the read guard's refusal (hooks/readGuard.mjs), of
   // `--no-index` and of any git argument aimed off the checkout — and no
-  // Write, no Edit, no mkdir, no rm) and NO MCP is passed at all, so this
-  // turn has no control plane to reach even if the repository it reads tries
-  // to steer it. The proposal comes back as the turn's final message rather
-  // than through a tool, which is exactly what lets that permission set be
+  // Write, no Edit, no mkdir, no rm). Compatible held attempts may receive
+  // only a local read-only coordination capability. No board/staging token,
+  // project/personal server or extra network access is supplied. The proposal
+  // comes back as the turn's final message rather than through a tool, which lets that permission set be
   // this narrow.
   //
   // It takes the checkout's place lock as a READER, beside the operator's own
@@ -287,49 +291,71 @@ export function createWorkAgentPlans({
         discovery.toolLog.baseline = measureRepositoryBaseline({ cwd: repoRoot, baseRef, knowledgeDir });
         discovery.toolLog.captureBaseline = repositoryBaselineOf(job.captureBaseline);
         discovery.toolLog.reconciliation = compareRepositoryBaselines(discovery.toolLog.baseline, discovery.toolLog.captureBaseline);
-        const consult = async (prompt, system) => await runCappedTurn({
-          runTurn,
-          signal: control?.signal,
-          capMs: PLAN_TURN_TIMEOUT_MS,
-          workChildren,
-          releaseSlot,
-          transcriptCwd: repoRoot,
-          turnArgs: {
-            diagnosticPlanId: id,
-            prompt,
-            system,
-            knowledgeDir,
-            // READ-ONLY, and no MCP: `mcpArgs` is omitted entirely rather than
-            // passed empty, so there is no control plane on this turn at all.
-            profile: 'consult',
-            cwd: repoRoot,
-            runtime: rt,
-            ...brainFor(job, rt),
-            answerFromResult: true,
-            work: planWork(job),
-            // The CLI's own tail, forwarded to the press. Same rule as an agent
-            // turn's: throttled, overwritten rather than appended, and never
-            // awaited by the turn.
-            onActivity: (a) => {
-              if (a?.label) narrate(String(a.label));
+        const brain = brainFor(job, rt);
+        let consults = 0;
+        const consult = async (prompt, system, diagnosing = false) => {
+          let rootSlot = releaseSlot;
+          if (consults++ > 0) {
+            // Diagnosis ended its CLI and released its children. A fresh
+            // paid consult must ask the pool again, like every other root.
+            while (admit('churn')) {
+              if (control?.signal.aborted) return { out: '', wedged: false };
+              await new Promise(resolve => setTimeout(resolve, 1_000));
+            }
+            rootSlot = admit.reserve();
+          }
+          return await runConsult({
+            enabled: job.readOnlyOrchestrationVersion === 1 && job.recoveryEnabled === true,
+            identity: { scope: 'plan', id, attempt: job.attempt },
+            version: runtimeVersion(rt),
+            admit,
+            children: { ...brain, model: brain.model ?? (rt === 'claude' ? MODEL : null),
+              ...(rt === 'codex' ? { catalog: knownCodexModels() } : {}) },
+            contract: planningOrchestratorContract({ diagnosis: diagnosing, runtime: rt, ...brain, model: brain.model ?? (rt === 'claude' ? MODEL : null) }),
+            onUnavailable: error => say(`Native investigation coordination unavailable: ${error.message}`),
+            runTurn,
+            signal: control?.signal,
+            capMs: PLAN_TURN_TIMEOUT_MS,
+            workChildren,
+            releaseSlot: rootSlot,
+            transcriptCwd: repoRoot,
+            turnArgs: {
+              diagnosticPlanId: id,
+              prompt,
+              system,
+              knowledgeDir,
+              // The consult fence stays intact. runReadOnlyConsult may mount
+              // only the attempt's local coordination tool, never a board token.
+              profile: 'consult',
+              cwd: repoRoot,
+              runtime: rt,
+              ...brain,
+              answerFromResult: true,
+              work: planWork(job),
+              // The CLI's own tail, forwarded to the press. Same rule as an agent
+              // turn's: throttled, overwritten rather than appended, and never
+              // awaited by the turn.
+              onActivity: (a) => {
+                if (a?.label) narrate(String(a.label));
+              },
+              onToolEvent: discovery.pushToolEvent,
+              // 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 });
+              },
             },
-            onToolEvent: discovery.pushToolEvent,
-            // 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: () => {
+              say(`${runtimeLabel(rt)} started on this machine`);
             },
-          },
-          onSpawn: () => {
-            say(`${runtimeLabel(rt)} started on this machine`);
-          },
-        });
+          });
+        };
         let context = AGENT_PLAN_KICKOFF({ tasks, liveAgents, agentCap: Number.isInteger(job.agentCap) && job.agentCap > 0 ? job.agentCap : 3 });
         if (job.recovery?.start) context += '\nSTART REPAIR: This is a supporting diagnosis for an already approved Start. Return exactly ONE group with the same ordered taskIds, attachment target (or absence) and CLI. Preserve the approval; do not start an unapproved sibling. Diagnose admission/pickup errors and repair planning evidence/context. Ask only a genuine person-only question in the diagnostic JSON. Approval and source revision (data): ' + JSON.stringify(job.recovery.start);
         const system = withProjectContext(SYSTEM_PLAN, { knowledgeDir }) + '\n\n' + discoveryGuide(rt, 'planning') + '\n\n' + REPOSITORY_BASELINE_PARAGRAPH(discovery.toolLog.baseline, discovery.toolLog.captureBaseline, discovery.toolLog.reconciliation);
         if (job.recovery) {
           say(`Diagnosing the failed Plan: ${job.recovery.reason}`);
-          const diagnostic = await consult(context + '\nRetained recovery context (data): ' + JSON.stringify(job.recovery), withProjectContext(PLAN_RECOVERY_SYSTEM, { knowledgeDir }) + '\n' + discoveryGuide(rt, 'planning'));
+          const diagnostic = await consult(context + '\nRetained recovery context (data): ' + JSON.stringify(job.recovery), withProjectContext(PLAN_RECOVERY_SYSTEM, { knowledgeDir }) + '\n' + discoveryGuide(rt, 'planning'), true);
           if (control?.signal.aborted) return;
           if (diagnostic.wedged) { wedged = true; return; }
           const result = parsePlanDiagnosis(diagnostic.out);

package/bin/lib/workAgentReview.mjs

@@ -19,6 +19,8 @@ export function createWorkAgentReview({ runCheck, runPrecheck }) {
    * `runCheck` directly; a second thing to run at the same moment is a second
    * thing three call sites can forget.
    *
+   * THE MERGE PATH IS NOT A REVIEW ENTRY (2026-10-21) — see `runMergeCheck`.
+   *
    * THE CHECK FIRST, ALWAYS. It is a local command whose answer the board wants
    * on the row immediately; the pre-review is a model call that may take
    * minutes. Ordering them the other way would put a label behind a label.
@@ -42,5 +44,26 @@ export function createWorkAgentReview({ runCheck, runPrecheck }) {
     return result;
   };
 
-  return { runReviewEntry };
+  /**
+   * THE CHECK ALONE, for the merge path (2026-10-21): the stale fold before an
+   * approved merge, each repository of a coordinated merge, and a merge
+   * resolve's settle. The check gates there — a failed one sends the agent
+   * back to Review — so it still runs. The pre-review does not: it labels and
+   * never blocks, yet run here it sat inside the place's writer lock ahead of
+   * the push and held an approved merge for up to its five-minute cap. One
+   * merge measured 13:40 check → 13:43 resolve settled → 13:43 check → 13:48
+   * landed, both waits a pre-review, the second wedged and posting nothing.
+   * A person already approved this work; a reading of it nobody is waiting on
+   * cannot be what the landing waits for. A merge that fails back to Review
+   * keeps its earlier reading, which the server marks stale by `precheckSha`.
+   */
+  const runMergeCheck = async (agentId, wt, repository) => {
+    try {
+      return (await runCheck(agentId, wt, repository)) ?? { status: 'unknown' };
+    } catch {
+      return { status: 'unknown' };
+    }
+  };
+
+  return { runReviewEntry, runMergeCheck };
 }