fix: clarify code queue activity counts

scripts/code-queue-queues-shape-contract-test.ts

@@ -16,6 +16,10 @@ function asArray(value: unknown): unknown[] {
   return value as unknown[];
 }
 
+function manyIds(prefix: string, count: number): string[] {
+  return Array.from({ length: count }, (_, index) => `${prefix}-${String(index + 1).padStart(2, "0")}`);
+}
+
 function fixtureResponse(): JsonRecord {
   return {
     ok: true,
@@ -76,6 +80,66 @@ function fixtureResponse(): JsonRecord {
   };
 }
 
+function splitBrainLiveResponse(): JsonRecord {
+  const liveTaskIds = manyIds("task-running", 8);
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      ok: true,
+      queue: {
+        total: 8,
+        queueCount: 2,
+        activeQueueIds: [],
+        activeTaskIds: [],
+        queuedTaskIds: [],
+        counts: { running: 8 },
+        unreadTerminal: 0,
+        executionDiagnostics: {
+          state: "split-brain",
+          splitBrain: true,
+          splitBrainLive: true,
+          effectiveLiveness: "live",
+          recommendedAction: "continue-supervision",
+          databaseActiveTaskCount: 8,
+          databaseActiveTaskIds: liveTaskIds,
+          schedulerActiveRunSlotCount: 0,
+          schedulerActiveTaskIds: [],
+          activeHeartbeatCount: 8,
+          activeHeartbeatTaskIds: liveTaskIds,
+          heartbeatFreshTaskIds: liveTaskIds,
+          heartbeatExpiredTaskIds: [],
+          heartbeatMissingTaskIds: [],
+          staleRecoveryCandidateTaskIds: [],
+          heartbeatRiskTaskIds: [],
+        },
+      },
+      queues: [
+        {
+          id: "alpha",
+          name: "Alpha",
+          total: 4,
+          counts: { running: 4 },
+          unreadTerminal: 0,
+          activeTaskId: null,
+          runnableTaskId: null,
+          updatedAt: "2026-05-20T00:00:00.000Z",
+        },
+        {
+          id: "beta",
+          name: "Beta",
+          total: 4,
+          counts: { running: 4 },
+          unreadTerminal: 0,
+          activeTaskId: null,
+          runnableTaskId: null,
+          updatedAt: "2026-05-20T00:01:00.000Z",
+        },
+      ],
+    },
+  };
+}
+
 function assertQueuesShape(label: string, result: unknown, expectedView: string): void {
   const data = asRecord(result);
   const queues = asRecord(data.queues);
@@ -100,15 +164,51 @@ function assertQueuesShape(label: string, result: unknown, expectedView: string)
   assertCondition(liveness.schedulerActiveRunSlotCount === 0, `${label} liveness summary should keep master active slot zero visible`, liveness);
   assertCondition(asArray(liveness.heartbeatFreshTaskIds).length === 1, `${label} liveness summary should include bounded fresh heartbeat task ids`, liveness);
   assertCondition(String(liveness.interpretation ?? "").includes("heartbeat is fresh"), `${label} liveness interpretation should explain slot-zero split-brain`, liveness);
+  const activity = asRecord(queues.activity);
+  assertCondition(activity.effectiveActiveTaskCount === 1, `${label} activity should foreground effective active task count`, activity);
+  assertCondition(activity.databaseRunningTaskCount === 1, `${label} activity should distinguish database running tasks`, activity);
+  assertCondition(activity.heartbeatFreshActiveTaskCount === 1, `${label} activity should distinguish heartbeat-fresh active runners`, activity);
+  assertCondition(activity.schedulerLocalActiveQueueCount === 1, `${label} activity should distinguish scheduler-local active queues`, activity);
+  assertCondition(activity.activeQueueIdsScope === "scheduler-local-active-run-slots", `${label} activity should label activeQueueIds scope`, activity);
   assertCondition(Array.isArray(queues.activeTaskIds), `${label} activeTaskIds should be present`, queues);
   assertCondition(Array.isArray(queues.queuedTaskIds), `${label} queuedTaskIds should be present`, queues);
 }
 
+function assertSplitBrainLiveActivity(label: string, result: unknown): void {
+  const queues = asRecord(asRecord(result).queues);
+  const totals = asRecord(queues.totals);
+  assertCondition(totals.activeQueueCount === 0, `${label} scheduler-local active queue count should be zero`, totals);
+  assertCondition(totals.schedulerLocalActiveQueueCount === 0, `${label} should preserve zero scheduler-local active queues`, totals);
+  assertCondition(totals.runnableQueueCount === 0, `${label} runnable queue count should be zero`, totals);
+  assertCondition(totals.databaseRunningTaskCount === 8, `${label} should foreground DB running task count`, totals);
+  assertCondition(totals.databaseActiveTaskCount === 8, `${label} should foreground DB active task count`, totals);
+  assertCondition(totals.heartbeatFreshActiveTaskCount === 8, `${label} should foreground heartbeat-effective active runners`, totals);
+  assertCondition(totals.effectiveActiveTaskCount === 8, `${label} should foreground effective active task count`, totals);
+  assertCondition(asArray(queues.activeQueueIds).length === 0, `${label} activeQueueIds should remain the scheduler-local list`, queues);
+  assertCondition(queues.activeQueueIdsScope === "scheduler-local-active-run-slots", `${label} activeQueueIds should be scoped`, queues);
+  assertCondition(String(queues.activeQueueIdsNote ?? "").includes("scheduler-local only"), `${label} activeQueueIds note should explain local-only semantics`, queues);
+  const activity = asRecord(queues.activity);
+  assertCondition(activity.effectiveActiveTaskCount === 8, `${label} activity should expose effective active count`, activity);
+  assertCondition(activity.effectiveActiveSource === "heartbeat-fresh", `${label} activity should choose heartbeat-fresh source`, activity);
+  assertCondition(activity.databaseRunningTaskCount === 8, `${label} activity should expose DB running count`, activity);
+  assertCondition(activity.heartbeatFreshActiveTaskCount === 8, `${label} activity should expose heartbeat-effective active count`, activity);
+  assertCondition(activity.schedulerLocalActiveQueueCount === 0, `${label} activity should expose scheduler-local queue count`, activity);
+  assertCondition(activity.schedulerLocalActiveRunSlotCount === 0, `${label} activity should expose scheduler-local slot count`, activity);
+  assertCondition(activity.runnableQueueCount === 0, `${label} activity should expose runnable queue count`, activity);
+  assertCondition(activity.splitBrainLive === true, `${label} activity should preserve split-brain live`, activity);
+  assertCondition(String(activity.activeQueueIdsNote ?? "").includes("zero local queue ids does not mean zero active runners"), `${label} activity note should prevent zero-active misread`, activity);
+  assertCondition(String(activity.interpretation ?? "").includes("continue supervision"), `${label} activity interpretation should keep supervision action`, activity);
+}
+
 export function runCodeQueueQueuesShapeContract(): JsonRecord {
   const fetcher = (path: string): JsonRecord => {
     assertCondition(path === "/api/microservices/code-queue/proxy/api/queues", "codex queues should use stable proxy path", { path });
     return fixtureResponse();
   };
+  const splitBrainFetcher = (path: string): JsonRecord => {
+    assertCondition(path === "/api/microservices/code-queue/proxy/api/queues", "codex queues should use stable proxy path", { path });
+    return splitBrainLiveResponse();
+  };
 
   const summary = codexQueuesQueryForTest([], fetcher);
   assertQueuesShape("summary", summary, "summary");
@@ -140,6 +240,11 @@ export function runCodeQueueQueuesShapeContract(): JsonRecord {
   assertCondition(offsetFullQueues.hasPrevious === true, "offset full should expose previous page", offsetFullQueues);
   assertCondition(asRecord(asArray(offsetFullQueues.items)[0]).id === "gamma", "offset full should return second page rows", offsetFullQueues);
 
+  const splitSummary = codexQueuesQueryForTest([], splitBrainFetcher);
+  assertSplitBrainLiveActivity("split-brain summary", splitSummary);
+  const splitFull = codexQueuesQueryForTest(["--full"], splitBrainFetcher);
+  assertSplitBrainLiveActivity("split-brain full", splitFull);
+
   return {
     ok: true,
     checks: [
@@ -150,6 +255,7 @@ export function runCodeQueueQueuesShapeContract(): JsonRecord {
       "deprecated full array omitted from default output",
       "full explicit limit remains bounded and paged",
       "offset pagination",
+      "split-brain live activity counts distinguish scheduler-local queues, DB running tasks, and heartbeat-fresh runners",
     ],
   };
 }

scripts/code-queue-supervisor-disclosure-contract-test.ts

@@ -174,11 +174,64 @@ function manyRunningFixtureResponse(path: string): JsonRecord {
   };
 }
 
+function splitBrainLiveSupervisorFixtureResponse(path: string): JsonRecord {
+  if (path.includes("/summary")) return fixtureResponse(path);
+  assertCondition(path.startsWith("/api/microservices/code-queue/proxy/api/tasks/overview"), "unexpected path", { path });
+  const liveTaskIds = manyIds("split-live", 8);
+  const tasks = liveTaskIds.map((taskId, index) => task(
+    taskId,
+    "running",
+    `2026-05-22T01:${String(50 - index).padStart(2, "0")}:00.000Z`,
+  ));
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      ok: true,
+      queue: {
+        counts: { running: 8 },
+        activeQueueIds: [],
+        activeTaskIds: [],
+        activeRunSlotCount: 0,
+        databaseActiveTaskCount: 8,
+        executionDiagnostics: {
+          state: "split-brain",
+          splitBrain: true,
+          splitBrainLive: true,
+          effectiveLiveness: "live",
+          recommendedAction: "continue-supervision",
+          databaseActiveTaskCount: 8,
+          databaseActiveTaskIds: liveTaskIds,
+          schedulerActiveRunSlotCount: 0,
+          schedulerActiveTaskIds: [],
+          activeHeartbeatCount: 8,
+          activeHeartbeatTaskIds: liveTaskIds,
+          heartbeatFreshTaskIds: liveTaskIds,
+          heartbeatExpiredTaskIds: [],
+          heartbeatMissingTaskIds: [],
+          staleRecoveryCandidateTaskIds: [],
+          heartbeatRiskTaskIds: [],
+        },
+      },
+      pagination: {
+        limit: 200,
+        returned: 8,
+        total: 8,
+        hasMore: false,
+        nextBeforeId: null,
+        includeActive: true,
+      },
+      tasks,
+    },
+  };
+}
+
 export function runCodeQueueSupervisorDisclosureContract(): JsonRecord {
   const supervisor = codexTasksQueryForTest(["--view", "supervisor", "--limit", "20"], fixtureResponse);
   const full = codexTasksQueryForTest(["--view", "full", "--limit", "20"], fixtureResponse);
   const runningFiltered = codexTasksQueryForTest(["--status", "running", "--limit", "40"], manyRunningFixtureResponse);
   const unreadFiltered = codexTasksQueryForTest(["--unread", "--limit", "20"], fixtureResponse);
+  const splitBrainLive = codexTasksQueryForTest(["--view", "supervisor", "--limit", "20"], splitBrainLiveSupervisorFixtureResponse);
 
   const supervisorBody = JSON.stringify(supervisor);
   const fullBody = JSON.stringify(full);
@@ -200,6 +253,9 @@ export function runCodeQueueSupervisorDisclosureContract(): JsonRecord {
   const diagnostics = asRecord(supervisorView.executionDiagnostics);
   const listBudget = asRecord(diagnostics.listBudget);
   const omittedCounts = asRecord(listBudget.omittedCounts);
+  const splitBrainLiveView = asRecord(asRecord(splitBrainLive).supervisor);
+  const splitBrainLiveActivity = asRecord(splitBrainLiveView.activity);
+  const splitBrainLiveCounts = asRecord(splitBrainLiveView.counts);
 
   assertCondition(supervisorBody.length < fullBody.length * 0.55, "supervisor output should be materially smaller than full output", { supervisorChars: supervisorBody.length, fullChars: fullBody.length });
   assertCondition(supervisorBody.length < 45_000, "supervisor output should remain bounded even with large diagnostics", { supervisorChars: supervisorBody.length });
@@ -237,6 +293,20 @@ export function runCodeQueueSupervisorDisclosureContract(): JsonRecord {
   assertCondition(runningFilteredBody.length < 14_000, "running status filter output should remain bounded", { chars: runningFilteredBody.length });
   assertCondition(asArray(unreadFilteredSection.items).length <= 3, "unread list should be locally paged below --limit", unreadFilteredSection);
   assertCondition(unreadFilteredBody.length < 14_000, "unread output should remain bounded", { chars: unreadFilteredBody.length });
+  assertCondition(splitBrainLiveCounts.running === 8, "split-brain supervisor should preserve DB running task count", splitBrainLiveCounts);
+  assertCondition(splitBrainLiveCounts.effectiveActive === 8, "split-brain supervisor should foreground effective active count", splitBrainLiveCounts);
+  assertCondition(splitBrainLiveCounts.databaseRunning === 8, "split-brain supervisor should distinguish database running tasks", splitBrainLiveCounts);
+  assertCondition(splitBrainLiveCounts.heartbeatFreshActive === 8, "split-brain supervisor should distinguish heartbeat-effective active runners", splitBrainLiveCounts);
+  assertCondition(splitBrainLiveCounts.schedulerLocalActiveQueues === 0, "split-brain supervisor should preserve zero scheduler-local active queues", splitBrainLiveCounts);
+  assertCondition(splitBrainLiveActivity.effectiveActiveTaskCount === 8, "split-brain supervisor activity should expose effective active count", splitBrainLiveActivity);
+  assertCondition(splitBrainLiveActivity.effectiveActiveSource === "heartbeat-fresh", "split-brain supervisor activity should prefer heartbeat-fresh source", splitBrainLiveActivity);
+  assertCondition(splitBrainLiveActivity.databaseRunningTaskCount === 8, "split-brain supervisor activity should expose DB running count", splitBrainLiveActivity);
+  assertCondition(splitBrainLiveActivity.heartbeatFreshActiveTaskCount === 8, "split-brain supervisor activity should expose heartbeat-fresh active count", splitBrainLiveActivity);
+  assertCondition(splitBrainLiveActivity.schedulerLocalActiveQueueCount === 0, "split-brain supervisor activity should expose scheduler-local queue count", splitBrainLiveActivity);
+  assertCondition(splitBrainLiveActivity.schedulerLocalActiveRunSlotCount === 0, "split-brain supervisor activity should expose scheduler-local slot count", splitBrainLiveActivity);
+  assertCondition(splitBrainLiveActivity.splitBrainLive === true, "split-brain supervisor activity should mark live split-brain", splitBrainLiveActivity);
+  assertCondition(String(splitBrainLiveActivity.activeQueueIdsNote ?? "").includes("zero local queue ids does not mean zero active runners"), "split-brain supervisor activity should explain activeQueueIds are local-only", splitBrainLiveActivity);
+  assertCondition(String(splitBrainLiveActivity.interpretation ?? "").includes("continue supervision"), "split-brain supervisor activity should not imply scheduler stoppage", splitBrainLiveActivity);
 
   return {
     ok: true,
@@ -249,6 +319,7 @@ export function runCodeQueueSupervisorDisclosureContract(): JsonRecord {
       "running finalResponse rows labeled awaiting terminal/judge",
       "drill-down commands preserved",
       "full view remains detailed",
+      "split-brain live supervisor activity distinguishes scheduler-local, database, and heartbeat counts",
     ],
     supervisorChars: supervisorBody.length,
     fullChars: fullBody.length,

scripts/src/code-queue.ts

@@ -433,6 +433,10 @@ function asNumber(value: unknown, fallback = 0): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
 function asBoolean(value: unknown): boolean {
   return value === true || value === 1 || value === "1" || value === "true";
 }
@@ -1304,6 +1308,100 @@ function compactQueueExecutionDiagnostics(value: unknown): Record<string, unknow
   };
 }
 
+function firstFiniteNumber(...values: unknown[]): number | null {
+  for (const value of values) {
+    const number = finiteNumber(value);
+    if (number !== null) return number;
+  }
+  return null;
+}
+
+function stringListCount(value: unknown): number | null {
+  return Array.isArray(value) ? stringList(value).length : null;
+}
+
+function compactCodeQueueActivity(
+  queue: Record<string, unknown>,
+  diagnostics: Record<string, unknown> | null,
+  options: { schedulerLocalActiveQueueIds?: string[]; runnableQueueCount?: number | null } = {},
+): Record<string, unknown> {
+  const rawDiagnostics = asRecord(queue.executionDiagnostics) ?? {};
+  const compactDiagnostics = diagnostics ?? {};
+  const rawLiveness = asRecord(rawDiagnostics.liveness) ?? {};
+  const compactLiveness = asRecord(compactDiagnostics.liveness) ?? {};
+  const counts = asRecord(queue.counts) ?? {};
+  const schedulerLocalActiveQueueIds = options.schedulerLocalActiveQueueIds ?? stringList(queue.activeQueueIds);
+  const databaseRunningTaskCount = firstFiniteNumber(counts.running) ?? 0;
+  const databaseJudgingTaskCount = firstFiniteNumber(counts.judging) ?? 0;
+  const databaseActiveTaskCount = firstFiniteNumber(
+    rawDiagnostics.databaseActiveTaskCount,
+    queue.databaseActiveTaskCount,
+    compactDiagnostics.databaseActiveTaskCount,
+    stringListCount(rawDiagnostics.databaseActiveTaskIds),
+    stringListCount(queue.databaseActiveTaskIds),
+    databaseRunningTaskCount + databaseJudgingTaskCount,
+  ) ?? 0;
+  const heartbeatFreshActiveTaskCount = firstFiniteNumber(
+    rawLiveness.heartbeatFreshTaskCount,
+    compactLiveness.heartbeatFreshTaskCount,
+    stringListCount(rawDiagnostics.heartbeatFreshTaskIds),
+    stringListCount(compactDiagnostics.heartbeatFreshTaskIds),
+  ) ?? 0;
+  const activeHeartbeatTaskCount = firstFiniteNumber(
+    rawDiagnostics.activeHeartbeatCount,
+    compactDiagnostics.activeHeartbeatCount,
+    stringListCount(rawDiagnostics.activeHeartbeatTaskIds),
+    heartbeatFreshActiveTaskCount,
+  ) ?? 0;
+  const heartbeatRiskTaskCount = firstFiniteNumber(
+    rawLiveness.heartbeatRiskTaskCount,
+    compactLiveness.heartbeatRiskTaskCount,
+    stringListCount(rawDiagnostics.heartbeatRiskTaskIds),
+    stringListCount(compactDiagnostics.heartbeatRiskTaskIds),
+  ) ?? 0;
+  const schedulerLocalActiveRunSlotCount = firstFiniteNumber(
+    rawDiagnostics.schedulerActiveRunSlotCount,
+    queue.schedulerActiveRunSlotCount,
+    queue.activeRunSlotCount,
+    compactDiagnostics.schedulerActiveRunSlotCount,
+  );
+  const runnableQueueCount = firstFiniteNumber(options.runnableQueueCount, queue.runnableQueueCount);
+  const effectiveActiveTaskCount = Math.max(databaseActiveTaskCount, databaseRunningTaskCount, heartbeatFreshActiveTaskCount);
+  const splitBrainLive = splitBrainLiveFromDiagnostics(rawDiagnostics) || splitBrainLiveFromDiagnostics(compactDiagnostics);
+  const effectiveActiveSource = heartbeatFreshActiveTaskCount > 0 && heartbeatFreshActiveTaskCount >= databaseActiveTaskCount
+    ? "heartbeat-fresh"
+    : databaseActiveTaskCount > 0
+      ? "database-active"
+      : schedulerLocalActiveQueueIds.length > 0 || (schedulerLocalActiveRunSlotCount ?? 0) > 0
+        ? "scheduler-local"
+        : "none";
+  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.";
+  return {
+    effectiveActiveTaskCount,
+    effectiveActiveSource,
+    databaseRunningTaskCount,
+    databaseActiveTaskCount,
+    heartbeatFreshActiveTaskCount,
+    activeHeartbeatTaskCount,
+    heartbeatRiskTaskCount,
+    schedulerLocalActiveQueueCount: schedulerLocalActiveQueueIds.length,
+    schedulerLocalActiveRunSlotCount,
+    runnableQueueCount,
+    splitBrainLive,
+    activeQueueIdsScope: "scheduler-local-active-run-slots",
+    activeQueueIdsNote,
+    interpretation: splitBrainLive
+      ? "split-brain live: database-active tasks have fresh scheduler heartbeat; continue supervision."
+      : heartbeatRiskTaskCount > 0
+        ? "heartbeat risk is present; investigate before retry or recovery."
+        : effectiveActiveTaskCount > 0
+          ? "active work is present; compare database, heartbeat, and scheduler-local counts before changing concurrency."
+          : "no active work observed by database, heartbeat, or scheduler-local signals.",
+  };
+}
+
 function supervisorExecutionDiagnostics(value: unknown): Record<string, unknown> | null {
   const diagnostics = compactExecutionDiagnostics(value);
   if (diagnostics === null) return null;
@@ -2355,6 +2453,7 @@ function codexTasksOverviewResult(
   const queuedSection = buildSupervisorTaskSection(queuedTasks, summaries, sectionLimit, sectionNextCommand(queuedTasks, sectionLimit, options, nextCommand), fullCommand);
   const pagination = taskPage.pagination;
   const diagnostics = supervisorExecutionDiagnostics(asRecord(taskPage.queue)?.executionDiagnostics);
+  const activity = compactCodeQueueActivity(asRecord(taskPage.queue) ?? {}, diagnostics);
   const visibleSupervisorItems = [...runningSection.items, ...unreadSection.items, ...recentSection.items, ...queuedSection.items];
   const classifierCounts = visibleSupervisorItems.reduce((counts, item) => {
     const key = item.kind;
@@ -2405,8 +2504,13 @@ function codexTasksOverviewResult(
         completedUnread: unreadSection.count,
         recentCompleted: recentSection.count,
         queued: queuedSection.count,
+        effectiveActive: asNumber(activity.effectiveActiveTaskCount, 0),
+        databaseRunning: asNumber(activity.databaseRunningTaskCount, 0),
+        heartbeatFreshActive: asNumber(activity.heartbeatFreshActiveTaskCount, 0),
+        schedulerLocalActiveQueues: asNumber(activity.schedulerLocalActiveQueueCount, 0),
       },
       classifierCounts,
+      activity,
       executionDiagnostics: diagnostics,
       degraded,
       commands: {
@@ -2698,6 +2802,7 @@ function compactQueuesResponse(body: Record<string, unknown>, options: CodexQueu
   const selected = options.full ? queues : Array.from(new Map([...activeQueues, ...unreadQueues, ...runnableQueues, ...nonemptyQueues].map((row) => [String(row.id), row])).values());
   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 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;
@@ -2725,11 +2830,20 @@ function compactQueuesResponse(body: Record<string, unknown>, options: CodexQueu
         totalTasks: queue.total ?? null,
         queueCount: queue.queueCount ?? queues.length,
         activeQueueCount: activeIds.length,
+        activeQueueCountScope: "scheduler-local-active-run-slots",
+        schedulerLocalActiveQueueCount: activeIds.length,
+        effectiveActiveTaskCount: activity.effectiveActiveTaskCount,
+        databaseRunningTaskCount: activity.databaseRunningTaskCount,
+        databaseActiveTaskCount: activity.databaseActiveTaskCount,
+        heartbeatFreshActiveTaskCount: activity.heartbeatFreshActiveTaskCount,
         nonemptyQueueCount: nonemptyQueues.length,
         unreadQueueCount: unreadQueues.length,
         runnableQueueCount: runnableQueues.length,
       },
+      activity,
       activeQueueIds: queue.activeQueueIds ?? [],
+      activeQueueIdsScope: "scheduler-local-active-run-slots",
+      activeQueueIdsNote: activity.activeQueueIdsNote,
       activeTaskIds: activeTaskIds.items,
       activeTaskIdsCount: activeTaskIds.count,
       activeTaskIdsTruncated: activeTaskIds.truncated,

scripts/src/help.ts

@@ -56,14 +56,14 @@ export function rootHelp(): unknown {
       { command: "codex skills-sync --dry-run [--full]", description: "Inspect the controlled runner skills hostPath lifecycle contract without copying files, restarting services, reading secrets, or mutating live runner paths." },
       { command: "codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N]", description: "Read-only PR admission check against the D601 scheduler/runner token, GitHub egress, repo visibility, skills lifecycle health, optional push dry-run, and PR body/create dry-run guard." },
       { command: "codex task <taskId> [--detail] [--trace --tail|--from-start|--after-seq N|--before-seq N --limit N] [--full]", description: "Fetch the bounded review view by default; --detail is still capped, while --full/trace/output explicitly expand evidence." },
-      { command: "codex tasks [--view supervisor|full] [--queue id] [--status status[,status]] [--unread|--unread-only] [--limit N] [--before-id id]", description: "Show the low-noise supervisor view by default: compact task rows, tiny local sections, diagnostics, and drill-down commands; use --view full for detailed rows." },
+      { command: "codex tasks [--view supervisor|full] [--queue id] [--status status[,status]] [--unread|--unread-only] [--limit N] [--before-id id]", description: "Show the low-noise supervisor view by default: compact task rows, tiny local sections, activity counts, diagnostics, and drill-down commands; use --view full for detailed rows." },
       { command: "codex output <taskId> [--tail|--from-start|--after-seq N|--before-seq N --limit N] [--full-text]", description: "Fetch paged raw Code Queue output records; default caps large limits/text previews, --full-text explicitly expands one seq window." },
       { command: "codex read <taskId>", description: "Mark one reviewed terminal task read; never run automatically as part of listing." },
       { command: "codex dev-ready", description: "Fetch execution-container readiness, including sanitized skill injection status from /api/dev-ready." },
       { command: "codex judge <taskId> --attempt N [--dry-run] [--include-prompt]", description: "Replay one stored Code Queue attempt through the same judge context builder and MiniMax judge call path used by the live queue worker." },
       { command: "codex steer <taskId> [prompt|--prompt-file path|--prompt-stdin] [--dry-run] [--no-retry|--retry-attempts N]", description: "Push a corrective prompt into a running Code Queue task; retryable tunnel aborts get bounded retry diagnostics, and real success does not echo prompt text." },
       { command: "codex interrupt|cancel <taskId>", description: "Request interrupt for a running Code Queue task, or cancel a queued/retry_wait task, through the same private proxy." },
-      { command: "codex (queues [--full|--all] | queue create <queueId> | queue merge <sourceQueueId> --into <targetQueueId> | move <taskId> --queue <queueId>)", description: "List low-noise queue summaries by default; full queue rows require --full/--all." },
+      { command: "codex (queues [--full|--all] | queue create <queueId> | queue merge <sourceQueueId> --into <targetQueueId> | move <taskId> --queue <queueId>)", description: "List low-noise queue summaries by default, including effective activity counts that distinguish scheduler-local queues, DB running tasks, and heartbeat-fresh runners; full queue rows require --full/--all." },
       { command: "job list [--limit N] [--include-command]", description: "List async jobs from .state/jobs with a bounded default page." },
       { command: "job status <jobId|latest> [--tail-bytes N]", description: "Show job state with bounded stdout/stderr tails." },
       { command: "debug health", description: "Probe internal core, nodes, system/Docker status, frontend, provider ingress, and public boundary." },
@@ -284,7 +284,13 @@ function codexHelp(): unknown {
       defaultPolicy: "low-noise JSON by default; write commands confirm persistence, list/detail/output commands return bounded summaries with drill-down commands",
       expand: ["codex task <taskId> --full", "codex task <taskId> --trace --limit N", "codex output <taskId> --after-seq N --limit N --full-text", "codex tasks --view full --limit N", "codex skills-sync --dry-run --full"],
     },
-    description: "Operate Code Queue through the stable backend-core private proxy path. Real submit/steer success is a low-noise write confirmation and does not echo prompt text.",
+    activityFields: {
+      path: "data.queues.activity and data.supervisor.activity",
+      effectiveActiveTaskCount: "Commander-facing active count derived from database active/running tasks and heartbeat-fresh runners.",
+      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.",
+    },
+    description: "Operate Code Queue through the stable backend-core private proxy path with bounded activity summaries for queue and supervisor views. Real submit/steer success is a low-noise write confirmation and does not echo prompt text.",
   };
 }