fix: name commander active runner count

scripts/src/code-queue.ts

@@ -1359,6 +1359,12 @@ function compactCodeQueueActivity(
     stringListCount(rawDiagnostics.heartbeatRiskTaskIds),
     stringListCount(compactDiagnostics.heartbeatRiskTaskIds),
   ) ?? 0;
+  const staleRecoveryCandidateTaskCount = firstFiniteNumber(
+    rawLiveness.staleRecoveryCandidateTaskCount,
+    compactLiveness.staleRecoveryCandidateTaskCount,
+    stringListCount(rawDiagnostics.staleRecoveryCandidateTaskIds),
+    stringListCount(compactDiagnostics.staleRecoveryCandidateTaskIds),
+  ) ?? 0;
   const schedulerLocalActiveRunSlotCount = firstFiniteNumber(
     rawDiagnostics.schedulerActiveRunSlotCount,
     queue.schedulerActiveRunSlotCount,
@@ -1367,6 +1373,10 @@ function compactCodeQueueActivity(
   );
   const runnableQueueCount = firstFiniteNumber(options.runnableQueueCount, queue.runnableQueueCount);
   const effectiveActiveTaskCount = Math.max(databaseActiveTaskCount, databaseRunningTaskCount, heartbeatFreshActiveTaskCount);
+  const executionState = asString(rawDiagnostics.state ?? compactDiagnostics.state);
+  const effectiveLiveness = asString(rawDiagnostics.effectiveLiveness ?? compactDiagnostics.effectiveLiveness ?? rawLiveness.effectiveLiveness ?? compactLiveness.effectiveLiveness);
+  const recommendedAction = asString(rawDiagnostics.recommendedAction ?? compactDiagnostics.recommendedAction ?? rawLiveness.recommendedAction ?? compactLiveness.recommendedAction);
+  const splitBrain = asBoolean(rawDiagnostics.splitBrain) || asBoolean(compactDiagnostics.splitBrain) || executionState === "split-brain";
   const splitBrainLive = splitBrainLiveFromDiagnostics(rawDiagnostics) || splitBrainLiveFromDiagnostics(compactDiagnostics);
   const effectiveActiveSource = heartbeatFreshActiveTaskCount > 0 && heartbeatFreshActiveTaskCount >= databaseActiveTaskCount
     ? "heartbeat-fresh"
@@ -1378,6 +1388,39 @@ function compactCodeQueueActivity(
   const activeQueueIdsNote = schedulerLocalActiveQueueIds.length === 0 && effectiveActiveTaskCount > 0
     ? "activeQueueIds are scheduler-local only; zero local queue ids does not mean zero active runners when database or heartbeat counts are nonzero."
     : "activeQueueIds are scheduler-local active-run slots; use effectiveActiveTaskCount for commander concurrency decisions.";
+  const recommendedActionIntervenes = recommendedAction.length > 0 && recommendedAction !== "continue-supervision";
+  const interventionRequired = heartbeatRiskTaskCount > 0 || staleRecoveryCandidateTaskCount > 0 || recommendedActionIntervenes || (splitBrain && !splitBrainLive);
+  const splitBrainDisposition = splitBrainLive
+    ? "live-count-as-active"
+    : splitBrain
+      ? "risk-investigate-before-new-work"
+      : "not-split-brain";
+  const splitBrainReason = splitBrainLive
+    ? "database active/running tasks have fresh heartbeat evidence and no heartbeat-risk candidates in the compact summary."
+    : splitBrain
+      ? "split-brain without fresh-heartbeat live evidence is risky; inspect heartbeat risk, stale recovery candidates, and raw diagnostics before changing capacity."
+      : "control-plane and execution-plane activity signals are not split-brain.";
+  const interventionReason = splitBrainLive
+    ? "fresh heartbeat makes split-brain live; count these runners as active and continue supervision."
+    : heartbeatRiskTaskCount > 0
+      ? "heartbeat risk is present; inspect before adding replacement work or recovering tasks."
+      : staleRecoveryCandidateTaskCount > 0
+        ? "stale recovery candidates are present; follow the recovery runbook before changing concurrency."
+        : recommendedActionIntervenes
+          ? `execution diagnostics recommend ${recommendedAction}; intervene before adding work.`
+          : splitBrain
+            ? "split-brain is not proven live; inspect raw diagnostics before treating capacity as available."
+            : "no intervention signal in compact activity summary.";
+  const commanderConcurrency = {
+    activeRunnerCount: effectiveActiveTaskCount,
+    activeRunnerCountField: "activity.effectiveActiveTaskCount",
+    activeRunnerCountSource: effectiveActiveSource,
+    decisionRule: "subtract activeRunnerCount from the commander concurrency target; for a 15-runner policy, remaining slots = 15 - activeRunnerCount.",
+    splitBrainDisposition,
+    splitBrainReason,
+    interventionRequired,
+    interventionReason,
+  };
   return {
     effectiveActiveTaskCount,
     effectiveActiveSource,
@@ -1386,10 +1429,16 @@ function compactCodeQueueActivity(
     heartbeatFreshActiveTaskCount,
     activeHeartbeatTaskCount,
     heartbeatRiskTaskCount,
+    staleRecoveryCandidateTaskCount,
     schedulerLocalActiveQueueCount: schedulerLocalActiveQueueIds.length,
     schedulerLocalActiveRunSlotCount,
     runnableQueueCount,
+    effectiveLiveness: effectiveLiveness || null,
+    recommendedAction: recommendedAction || null,
     splitBrainLive,
+    splitBrainDisposition,
+    splitBrainReason,
+    commanderConcurrency,
     activeQueueIdsScope: "scheduler-local-active-run-slots",
     activeQueueIdsNote,
     interpretation: splitBrainLive
@@ -2454,6 +2503,7 @@ function codexTasksOverviewResult(
   const pagination = taskPage.pagination;
   const diagnostics = supervisorExecutionDiagnostics(asRecord(taskPage.queue)?.executionDiagnostics);
   const activity = compactCodeQueueActivity(asRecord(taskPage.queue) ?? {}, diagnostics);
+  const commanderConcurrency = asRecord(activity.commanderConcurrency) ?? {};
   const visibleSupervisorItems = [...runningSection.items, ...unreadSection.items, ...recentSection.items, ...queuedSection.items];
   const classifierCounts = visibleSupervisorItems.reduce((counts, item) => {
     const key = item.kind;
@@ -2504,12 +2554,14 @@ function codexTasksOverviewResult(
         completedUnread: unreadSection.count,
         recentCompleted: recentSection.count,
         queued: queuedSection.count,
+        commanderActiveRunnerCount: asNumber(commanderConcurrency.activeRunnerCount, 0),
         effectiveActive: asNumber(activity.effectiveActiveTaskCount, 0),
         databaseRunning: asNumber(activity.databaseRunningTaskCount, 0),
         heartbeatFreshActive: asNumber(activity.heartbeatFreshActiveTaskCount, 0),
         schedulerLocalActiveQueues: asNumber(activity.schedulerLocalActiveQueueCount, 0),
       },
       classifierCounts,
+      commanderConcurrency,
       activity,
       executionDiagnostics: diagnostics,
       degraded,
@@ -2803,6 +2855,7 @@ function compactQueuesResponse(body: Record<string, unknown>, options: CodexQueu
   const visible = selected.slice(options.offset, options.offset + options.limit);
   const diagnostics = compactQueueExecutionDiagnostics(queue.executionDiagnostics);
   const activity = compactCodeQueueActivity(queue, diagnostics, { schedulerLocalActiveQueueIds: activeIds, runnableQueueCount: runnableQueues.length });
+  const commanderConcurrency = asRecord(activity.commanderConcurrency) ?? {};
   const activeTaskIds = boundedUniqueStringList(queue.activeTaskIds, Math.min(options.limit, maxTasksLimit));
   const queuedTaskIds = boundedUniqueStringList(queue.queuedTaskIds, Math.min(options.limit, maxTasksLimit));
   const nextOffset = options.offset + visible.length;
@@ -2832,6 +2885,7 @@ function compactQueuesResponse(body: Record<string, unknown>, options: CodexQueu
         activeQueueCount: activeIds.length,
         activeQueueCountScope: "scheduler-local-active-run-slots",
         schedulerLocalActiveQueueCount: activeIds.length,
+        commanderActiveRunnerCount: commanderConcurrency.activeRunnerCount,
         effectiveActiveTaskCount: activity.effectiveActiveTaskCount,
         databaseRunningTaskCount: activity.databaseRunningTaskCount,
         databaseActiveTaskCount: activity.databaseActiveTaskCount,
@@ -2840,6 +2894,7 @@ function compactQueuesResponse(body: Record<string, unknown>, options: CodexQueu
         unreadQueueCount: unreadQueues.length,
         runnableQueueCount: runnableQueues.length,
       },
+      commanderConcurrency,
       activity,
       activeQueueIds: queue.activeQueueIds ?? [],
       activeQueueIdsScope: "scheduler-local-active-run-slots",

scripts/src/help.ts

@@ -287,6 +287,7 @@ function codexHelp(): unknown {
     activityFields: {
       path: "data.queues.activity and data.supervisor.activity",
       effectiveActiveTaskCount: "Commander-facing active count derived from database active/running tasks and heartbeat-fresh runners.",
+      commanderConcurrency: "Use data.supervisor.commanderConcurrency.activeRunnerCount or data.queues.commanderConcurrency.activeRunnerCount for concurrency decisions; the block states the 15-runner arithmetic and intervention signal.",
       schedulerLocalActiveQueueCount: "Only queues currently visible in this scheduler-local active-run slot view; zero does not override DB or heartbeat activity.",
       heartbeatFreshActiveTaskCount: "Heartbeat-effective active runner count used to avoid split-brain zero-active mistakes.",
     },