claude-code-session-manager 0.35.13 → 0.35.14

package/src/main/browserView.cjs

@@ -21,6 +21,11 @@ const crypto = require('crypto');
 const { WebContentsView } = require('electron');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { readJson, writeJson } = require('./config.cjs');
+const {
+  parseKeyCombo,
+  computeScrollDelta,
+  computeScreenshotScale,
+} = require('./lib/browserAgentActions.cjs');
 
 // ── History + zoom persistence (PRD 402) ──────────────────────────────
 // Both files live under ~/.claude/session-manager/browser/, inside
@@ -70,6 +75,10 @@ const views = new Map();
 // main-window nav lock without weakening the lock itself.
 const browserViewContentsIds = new Set();
 let win = null;
+// Last viewId shown via show() — the renderer's proxy for "which sub-tab is
+// active", since WebContentsView exposes setVisible() but no getter. Used to
+// default viewId-optional browser-agent-server routes to the active tab.
+let lastShownViewId = null;
 
 // ── Recorder engine (PRD 408) ─────────────────────────────────────────
 // viewId <-> webContents.id so the record-event channel (sent from the
@@ -248,6 +257,7 @@ function show({ viewId }) {
   const view = views.get(viewId);
   if (!view) return { ok: false };
   view.setVisible(true);
+  lastShownViewId = viewId;
   return { ok: true };
 }
 
@@ -266,6 +276,7 @@ function destroy({ viewId }) {
   recordingViewIds.delete(viewId);
   stepCounters.delete(viewId);
   lastFindText.delete(viewId);
+  if (lastShownViewId === viewId) lastShownViewId = null;
   if (win && !win.isDestroyed()) {
     try { win.contentView.removeChildView(view); } catch { /* already detached */ }
   }
@@ -576,6 +587,181 @@ function stop({ viewId }) {
   return { ok: true };
 }
 
+// ── On-demand single-action agent API (PRD 535 foundation) ────────────
+// Modeled on Anthropic's published computer_use tool schema. Reuses the same
+// dispatch primitives the Recorder replay engine already established above
+// (replayPositionedClick for coordinate clicks, normalizeUrl/withTimeout for
+// navigate) instead of forking a second copy — the difference from replay()
+// is that this drives ONE ad-hoc action at a time by raw coordinate, not a
+// recorded `steps` array by selector.
+function listViews() {
+  const result = [];
+  for (const [viewId, view] of views.entries()) {
+    if (view.webContents.isDestroyed()) continue;
+    result.push({
+      viewId,
+      url: view.webContents.getURL(),
+      title: view.webContents.getTitle(),
+      active: viewId === lastShownViewId,
+    });
+  }
+  return result;
+}
+
+function resolveViewId(viewId) {
+  return viewId || lastShownViewId;
+}
+
+async function dispatchAction(view, params) {
+  const wc = view.webContents;
+  switch (params.action) {
+    case 'left_click': {
+      const [x, y] = Array.isArray(params.coordinate) ? params.coordinate : [];
+      if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        throw new Error('left_click requires coordinate: [x, y]');
+      }
+      await replayPositionedClick(wc, x, y);
+      return { ok: true };
+    }
+    case 'type': {
+      if (typeof params.text !== 'string') throw new Error('type requires text');
+      await wc.insertText(params.text);
+      return { ok: true };
+    }
+    case 'key': {
+      if (typeof params.key !== 'string' || !params.key) throw new Error('key requires key');
+      const { keyCode, modifiers } = parseKeyCombo(params.key);
+      wc.sendInputEvent({ type: 'keyDown', keyCode, modifiers });
+      if (keyCode.length === 1) wc.sendInputEvent({ type: 'char', keyCode, modifiers });
+      wc.sendInputEvent({ type: 'keyUp', keyCode, modifiers });
+      return { ok: true };
+    }
+    case 'scroll': {
+      const [x, y] = Array.isArray(params.coordinate) ? params.coordinate : [0, 0];
+      const { deltaX, deltaY } = computeScrollDelta(params);
+      wc.sendInputEvent({ type: 'mouseWheel', x: Number(x) || 0, y: Number(y) || 0, deltaX, deltaY });
+      return { ok: true };
+    }
+    case 'navigate': {
+      if (typeof params.url !== 'string' || !params.url) throw new Error('navigate requires url');
+      const normalized = normalizeUrl(params.url);
+      if (!normalized.ok) throw new Error(normalized.error);
+      await withTimeout(wc.loadURL(normalized.url), REPLAY_STEP_TIMEOUT_MS, 'navigate');
+      return { ok: true };
+    }
+    default:
+      throw new Error(`unsupported action: ${params.action}`);
+  }
+}
+
+// Single-action entry point (as opposed to replay()'s recorded-steps-array
+// entry point) — resolves viewId (defaulting to the active tab), dispatches
+// exactly one action, and normalizes errors into the { ok, error } shape the
+// rest of this module already uses.
+async function dispatchViewAction(params) {
+  const viewId = resolveViewId(params.viewId);
+  if (!viewId) return { ok: false, error: 'no viewId given and no active tab' };
+  const view = views.get(viewId);
+  if (!view || view.webContents.isDestroyed()) return { ok: false, error: 'unknown viewId' };
+  try {
+    return await dispatchAction(view, params);
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+// On-demand screenshot for the agent API. Reuses wc.capturePage() (same call
+// captureShot() below already uses) but additionally resizes to a fixed
+// logical resolution — Anthropic's computer-use API silently downscales
+// oversized screenshots server-side, which breaks coordinate mapping unless
+// caller and model agree on one fixed max dimension. `scale` in the response
+// lets a caller map a coordinate clicked on the returned image back to the
+// real page: realX = clickedX / scale.
+async function captureShotForAgent({ viewId } = {}) {
+  const id = resolveViewId(viewId);
+  if (!id) return { ok: false, error: 'no viewId given and no active tab' };
+  const view = views.get(id);
+  if (!view || view.webContents.isDestroyed()) return { ok: false, error: 'unknown viewId' };
+  try {
+    const wc = view.webContents;
+    const image = await wc.capturePage();
+    const { width, height } = image.getSize();
+    const target = computeScreenshotScale(width, height);
+    const resized = target.scale < 1 ? image.resize({ width: target.width, height: target.height }) : image;
+    return {
+      ok: true,
+      viewId: id,
+      url: wc.getURL(),
+      title: wc.getTitle(),
+      dataUrl: resized.toDataURL(),
+      scale: target.scale,
+      width: target.width,
+      height: target.height,
+      originalWidth: width,
+      originalHeight: height,
+    };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+// Cheap text/accessibility-style snapshot for the agent API — an alternative
+// to vision-only driving since a real DOM is available here. Follows the
+// same executeJavaScript sandboxing pattern as captureDom() below (plain
+// IIFE returning a plain object, no new capability granted to the page).
+// Kept cheap on purpose: innerText + a capped list of interactive elements
+// with center-point coordinates, no full HTML serialization or computed
+// style walking.
+const AGENT_DOM_TEXT_MAX = 100_000;
+const AGENT_DOM_ELEMENT_LIMIT = 200;
+
+async function captureAgentDom({ viewId } = {}) {
+  const id = resolveViewId(viewId);
+  if (!id) return { ok: false, error: 'no viewId given and no active tab' };
+  const view = views.get(id);
+  if (!view || view.webContents.isDestroyed()) return { ok: false, error: 'unknown viewId' };
+  try {
+    const script = `(() => {
+      const SEL = 'button, a[href], input, textarea, select, [role="button"], [onclick]';
+      const els = Array.from(document.querySelectorAll(SEL)).slice(0, ${AGENT_DOM_ELEMENT_LIMIT});
+      const elements = els.map((el) => {
+        const rect = el.getBoundingClientRect();
+        const label = (el.innerText || el.value || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '').trim().slice(0, 120);
+        return {
+          tag: el.tagName.toLowerCase(),
+          label,
+          x: Math.round(rect.left + rect.width / 2),
+          y: Math.round(rect.top + rect.height / 2),
+        };
+      }).filter((e) => e.x >= 0 && e.y >= 0 && Number.isFinite(e.x) && Number.isFinite(e.y));
+      return {
+        url: location.href,
+        title: document.title,
+        text: document.body ? document.body.innerText : '',
+        elements,
+      };
+    })()`;
+    const result = await view.webContents.executeJavaScript(script);
+    let text = typeof result?.text === 'string' ? result.text : '';
+    let truncated = false;
+    if (text.length > AGENT_DOM_TEXT_MAX) {
+      text = text.slice(0, AGENT_DOM_TEXT_MAX);
+      truncated = true;
+    }
+    return {
+      ok: true,
+      viewId: id,
+      url: result?.url || '',
+      title: result?.title || '',
+      text,
+      truncated,
+      elements: Array.isArray(result?.elements) ? result.elements : [],
+    };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
 // Cap returned capture text so a huge DOM can't blow up the IPC channel.
 const CAPTURE_TEXT_MAX = 500_000;
 
@@ -655,4 +841,14 @@ function registerBrowserView({ mainWindow, ipcMain }) {
   }));
 }
 
-module.exports = { registerBrowserView, attachWindow, views, isBrowserViewContents, getView };
+module.exports = {
+  registerBrowserView,
+  attachWindow,
+  views,
+  isBrowserViewContents,
+  getView,
+  listViews,
+  dispatchViewAction,
+  captureShotForAgent,
+  captureAgentDom,
+};

package/src/main/index.cjs

@@ -26,6 +26,13 @@ const voiceWizard = require('./voiceWizard.cjs');
 const scheduler = require('./scheduler.cjs');
 const { createAdminServer } = require('./adminServer.cjs');
 const adminServer = createAdminServer(scheduler.remote);
+const { createBrowserAgentServer } = require('./browserAgentServer.cjs');
+const browserAgentServer = createBrowserAgentServer({
+  listTabs: () => browserView.listViews(),
+  screenshot: ({ viewId }) => browserView.captureShotForAgent({ viewId }),
+  action: (params) => browserView.dispatchViewAction(params),
+  dom: ({ viewId }) => browserView.captureAgentDom({ viewId }),
+});
 const supervisor = require('./supervisor.cjs');
 const watchers = require('./watchers.cjs');
 const teams = require('./teams.cjs');
@@ -1059,6 +1066,9 @@ app.whenReady().then(async () => {
   adminServer.start().catch((e) => {
     logs.writeLine({ scope: 'admin-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });
+  browserAgentServer.start().catch((e) => {
+    logs.writeLine({ scope: 'browser-agent-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
+  });
   // First-boot default: install the bundled session-manager-dev plugin (its 10
   // dev skills) from the app's own marketplace. One-shot + idempotent; never
   // throws. SM_SEED_DEV_PLUGIN_DISABLE=1 to opt out.
@@ -1149,6 +1159,7 @@ app.on('before-quit', () => {
   transcripts.closeAll();
   watchers.manager.killAll();
   adminServer.stop().catch(() => {});
+  browserAgentServer.stop().catch(() => {});
   // Best-effort flush of any pending OTEL spans. shutdown() has its own 2s
   // ceiling so a wedged exporter can't hold quit.
   otel.shutdown().catch(() => {});

package/src/main/lib/__tests__/browserAgentActions.test.cjs

@@ -0,0 +1,76 @@
+/**
+ * browserAgentActions.test.cjs — unit tests for the pure action-mapping
+ * logic behind the on-demand browser-agent API (PRD 535).
+ *
+ * Run: timeout 120 node --test src/main/lib/__tests__/browserAgentActions.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  parseKeyCombo,
+  computeScrollDelta,
+  computeScreenshotScale,
+  AGENT_SCREENSHOT_MAX_DIM,
+} = require('../browserAgentActions.cjs');
+
+test('parseKeyCombo: plain special key', () => {
+  assert.deepEqual(parseKeyCombo('Return'), { keyCode: 'Enter', modifiers: [] });
+});
+
+test('parseKeyCombo: single modifier + letter', () => {
+  assert.deepEqual(parseKeyCombo('ctrl+s'), { keyCode: 's', modifiers: ['control'] });
+});
+
+test('parseKeyCombo: multiple modifiers', () => {
+  assert.deepEqual(parseKeyCombo('ctrl+shift+p'), { keyCode: 'p', modifiers: ['control', 'shift'] });
+});
+
+test('parseKeyCombo: cmd/meta/option aliases normalize', () => {
+  assert.deepEqual(parseKeyCombo('cmd+option+Escape'), { keyCode: 'Escape', modifiers: ['meta', 'alt'] });
+});
+
+test('parseKeyCombo: unknown modifier throws', () => {
+  assert.throws(() => parseKeyCombo('foo+a'), /unknown modifier/);
+});
+
+test('parseKeyCombo: empty string throws', () => {
+  assert.throws(() => parseKeyCombo(''), /empty key/);
+});
+
+test('computeScrollDelta: up/down/left/right map to signed deltas', () => {
+  assert.deepEqual(computeScrollDelta({ scroll_direction: 'up', scroll_amount: 2 }), { deltaX: 0, deltaY: 200 });
+  assert.deepEqual(computeScrollDelta({ scroll_direction: 'down', scroll_amount: 2 }), { deltaX: 0, deltaY: -200 });
+  assert.deepEqual(computeScrollDelta({ scroll_direction: 'left', scroll_amount: 1 }), { deltaX: 100, deltaY: 0 });
+  assert.deepEqual(computeScrollDelta({ scroll_direction: 'right', scroll_amount: 1 }), { deltaX: -100, deltaY: 0 });
+});
+
+test('computeScrollDelta: defaults scroll_amount to 1 when not finite', () => {
+  assert.deepEqual(computeScrollDelta({ scroll_direction: 'up' }), { deltaX: 0, deltaY: 100 });
+});
+
+test('computeScrollDelta: unsupported direction throws', () => {
+  assert.throws(() => computeScrollDelta({ scroll_direction: 'diagonal' }), /unsupported scroll_direction/);
+});
+
+test('computeScreenshotScale: leaves small images untouched', () => {
+  const result = computeScreenshotScale(800, 600);
+  assert.equal(result.scale, 1);
+  assert.equal(result.width, 800);
+  assert.equal(result.height, 600);
+});
+
+test('computeScreenshotScale: downscales long edge to the fixed max', () => {
+  const result = computeScreenshotScale(2560, 1440);
+  assert.equal(result.width, AGENT_SCREENSHOT_MAX_DIM);
+  assert.ok(result.scale < 1);
+  assert.equal(result.height, Math.round(1440 * result.scale));
+});
+
+test('computeScreenshotScale: portrait image scales on height', () => {
+  const result = computeScreenshotScale(900, 3000);
+  assert.equal(result.height, AGENT_SCREENSHOT_MAX_DIM);
+  assert.ok(result.width < 900);
+});

package/src/main/lib/browserAgentActions.cjs

@@ -0,0 +1,114 @@
+/**
+ * browserAgentActions.cjs — pure mapping logic for the on-demand single-
+ * action browser-agent API (PRD 535). Extracted out of browserView.cjs so
+ * the action -> input-event/scale mapping can be unit-tested without
+ * booting Electron — mirrors how lib/schedulerBatch.cjs was pulled out of
+ * scheduler.cjs for the same reason. Anything that actually touches a live
+ * WebContentsView (sendInputEvent, capturePage, executeJavaScript) stays in
+ * browserView.cjs; this module only computes the values passed to those
+ * calls.
+ */
+
+'use strict';
+
+// Anthropic's computer_use tool scrolls in "clicks"; one click here maps to
+// this many CSS pixels of wheel delta.
+const SCROLL_UNIT_PX = 100;
+
+// Anthropic-tool-use-style key names -> Electron's sendInputEvent keyCode
+// strings. Anything not in this table is passed through as-is (covers plain
+// single characters like "a" or "s").
+const SPECIAL_KEY_MAP = {
+  return: 'Enter',
+  enter: 'Enter',
+  tab: 'Tab',
+  escape: 'Escape',
+  esc: 'Escape',
+  backspace: 'Backspace',
+  delete: 'Delete',
+  space: ' ',
+  up: 'Up',
+  down: 'Down',
+  left: 'Left',
+  right: 'Right',
+  page_up: 'PageUp',
+  pageup: 'PageUp',
+  page_down: 'PageDown',
+  pagedown: 'PageDown',
+  home: 'Home',
+  end: 'End',
+};
+
+const MODIFIER_MAP = {
+  ctrl: 'control',
+  control: 'control',
+  shift: 'shift',
+  alt: 'alt',
+  option: 'alt',
+  cmd: 'meta',
+  meta: 'meta',
+  super: 'meta',
+};
+
+// Parses a computer-use-style key combo ("ctrl+s", "Return", "a") into the
+// { keyCode, modifiers } shape Electron's webContents.sendInputEvent wants.
+function parseKeyCombo(keyStr) {
+  const parts = String(keyStr || '')
+    .split('+')
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (!parts.length) throw new Error('empty key');
+  const last = parts.pop();
+  const modifiers = parts.map((p) => {
+    const mapped = MODIFIER_MAP[p.toLowerCase()];
+    if (!mapped) throw new Error(`unknown modifier: ${p}`);
+    return mapped;
+  });
+  const lowerLast = last.toLowerCase();
+  const keyCode = SPECIAL_KEY_MAP[lowerLast] || last;
+  return { keyCode, modifiers };
+}
+
+// Maps a computer-use-style scroll action to a mouseWheel delta.
+function computeScrollDelta({ scroll_direction, scroll_amount }) {
+  const amount = Number.isFinite(scroll_amount) ? scroll_amount : 1;
+  switch (scroll_direction) {
+    case 'up':
+      return { deltaX: 0, deltaY: amount * SCROLL_UNIT_PX };
+    case 'down':
+      return { deltaX: 0, deltaY: -amount * SCROLL_UNIT_PX };
+    case 'left':
+      return { deltaX: amount * SCROLL_UNIT_PX, deltaY: 0 };
+    case 'right':
+      return { deltaX: -amount * SCROLL_UNIT_PX, deltaY: 0 };
+    default:
+      throw new Error(`unsupported scroll_direction: ${scroll_direction}`);
+  }
+}
+
+// Fixed max long-edge a screenshot is resized to before being returned.
+// Anthropic's computer-use API silently downscales oversized images
+// server-side, which breaks coordinate mapping unless caller and model agree
+// on one fixed logical resolution up front — this is that fixed point.
+const AGENT_SCREENSHOT_MAX_DIM = 1280;
+
+// Given a captured screenshot's real pixel size, returns the target size to
+// resize to plus the scale factor a caller must divide a clicked coordinate
+// on the resized image by to recover the real-page coordinate.
+function computeScreenshotScale(width, height) {
+  const longEdge = Math.max(width, height);
+  const scale = longEdge > AGENT_SCREENSHOT_MAX_DIM ? AGENT_SCREENSHOT_MAX_DIM / longEdge : 1;
+  return {
+    scale,
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale)),
+  };
+}
+
+module.exports = {
+  parseKeyCombo,
+  computeScrollDelta,
+  computeScreenshotScale,
+  AGENT_SCREENSHOT_MAX_DIM,
+  SCROLL_UNIT_PX,
+};

package/src/main/lib/schedulerBatch.cjs

@@ -33,13 +33,15 @@ const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager
  *   runningSet that belong to this project.
  * @param {number} slots - Maximum jobs to return (global remaining slots;
  *   caller enforces the global cap across projects).
- * @returns {object[]} Jobs to spawn for this project this tick.
+ * @returns {{ batch: object[], reason: string | null }} Jobs to spawn for this
+ *   project this tick, plus (when batch is empty because a gate held it) the
+ *   human-readable reason text that would otherwise only reach console.log.
  */
 function pickForProject(projectJobs, runningSlugsInProject, slots) {
   const pending = projectJobs.filter(
     (j) => j.status === 'pending' && !runningSlugsInProject.has(j.slug),
   );
-  if (pending.length === 0) return [];
+  if (pending.length === 0) return { batch: [], reason: null };
 
   const projectCwd = (projectJobs.find((j) => j.cwd) || {}).cwd || DEFAULT_PROJECT_CWD;
 
@@ -57,12 +59,11 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   );
   if (blockingFailures.length > 0) {
     const slugs = blockingFailures.map((j) => j.slug).join(', ');
-    console.log(
-      `[scheduler] failure-gate [${projectCwd}]: holding g${lowestPendingGroup} — ` +
+    const reason = `[scheduler] failure-gate [${projectCwd}]: holding g${lowestPendingGroup} — ` +
       `${blockingFailures.length} failed job(s) in earlier groups [${slugs}]. ` +
-      `Reset to pending or archive to unblock.`,
-    );
-    return [];
+      `Reset to pending or archive to unblock.`;
+    console.log(reason);
+    return { batch: [], reason };
   }
 
   // Groups with at least one job in flight: either tracked in runningSlugsInProject
@@ -84,20 +85,18 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
     const lowestActive = Math.min(...activeGroups);
     if (lowestPendingGroup > lowestActive) {
       // Earlier group still running — wait for it to drain before advancing.
-      console.log(
-        `[scheduler] concurrency [${projectCwd}]: g${lowestActive} in flight, holding g${lowestPendingGroup}`,
-      );
-      return [];
+      const reason = `[scheduler] concurrency [${projectCwd}]: g${lowestActive} in flight, holding g${lowestPendingGroup}`;
+      console.log(reason);
+      return { batch: [], reason };
     }
     if (lowestPendingGroup < lowestActive) {
       // Late-arrival: a lower-numbered (higher-priority) PRD reconciled AFTER
       // a higher-numbered group was already picked. Fire it now in parallel
       // with the active group rather than starving it until drain.
       if (slots <= 0) {
-        console.log(
-          `[scheduler] concurrency [${projectCwd}]: no slots for late-arrival g${lowestPendingGroup}`,
-        );
-        return [];
+        const reason = `[scheduler] concurrency [${projectCwd}]: no slots for late-arrival g${lowestPendingGroup}`;
+        console.log(reason);
+        return { batch: [], reason };
       }
       const batch = pending
         .filter((j) => (j.parallelGroup ?? 99) === lowestPendingGroup)
@@ -106,12 +105,13 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
         `[scheduler] concurrency [${projectCwd}]: firing late-arrival g${lowestPendingGroup} ` +
         `(${batch.length} job(s)) alongside active g${lowestActive}`,
       );
-      return batch;
+      return { batch, reason: null };
     }
     // Backfill slots remaining in the current group.
     if (slots <= 0) {
-      console.log(`[scheduler] concurrency [${projectCwd}]: cap reached, no slots`);
-      return [];
+      const reason = `[scheduler] concurrency [${projectCwd}]: cap reached, no slots`;
+      console.log(reason);
+      return { batch: [], reason };
     }
     const batch = pending
       .filter((j) => (j.parallelGroup ?? 99) === lowestActive)
@@ -121,13 +121,14 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
         `[scheduler] concurrency [${projectCwd}]: backfilling ${batch.length} into g${lowestActive}`,
       );
     }
-    return batch;
+    return { batch, reason: null };
   }
 
   // No active group — start the next group fresh.
   if (slots <= 0) {
-    console.log(`[scheduler] concurrency [${projectCwd}]: cap reached, no slots`);
-    return [];
+    const reason = `[scheduler] concurrency [${projectCwd}]: cap reached, no slots`;
+    console.log(reason);
+    return { batch: [], reason };
   }
   const batch = pending
     .filter((j) => (j.parallelGroup ?? 99) === lowestPendingGroup)
@@ -135,7 +136,7 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   console.log(
     `[scheduler] concurrency [${projectCwd}]: starting g${lowestPendingGroup} with ${batch.length} job(s)`,
   );
-  return batch;
+  return { batch, reason: null };
 }
 
 /**
@@ -150,10 +151,14 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
  * @param {object[]} allJobs - Full queue.json job list.
  * @param {Set<string>} running - In-process running slugs (runningSet).
  * @param {number} cap - concurrencyCap.
- * @returns {object[]} Jobs to spawn this tick.
+ * @returns {{ batch: object[], reason: string | null }} Jobs to spawn this
+ *   tick, plus (when batch is empty because a gate held it) the human-readable
+ *   hold reason that would otherwise only reach console.log.
  */
 function pickNextBatch(allJobs, running, cap) {
-  if (!allJobs.some((j) => j.status === 'pending' && !running.has(j.slug))) return [];
+  if (!allJobs.some((j) => j.status === 'pending' && !running.has(j.slug))) {
+    return { batch: [], reason: null };
+  }
 
   // Global slot accounting: take the higher of in-process running count and
   // queue.json running count (handles orphaned running entries from a previous
@@ -162,10 +167,9 @@ function pickNextBatch(allJobs, running, cap) {
   const effectiveRunning = Math.max(running.size, queueRunningCount);
   let slots = cap - effectiveRunning;
   if (slots <= 0) {
-    console.log(
-      `[scheduler] concurrency: cap ${cap} reached (${effectiveRunning} running), no slots`,
-    );
-    return [];
+    const reason = `[scheduler] concurrency: cap ${cap} reached (${effectiveRunning} running), no slots`;
+    console.log(reason);
+    return { batch: [], reason };
   }
 
   // Group all jobs by project cwd.
@@ -198,15 +202,18 @@ function pickNextBatch(allJobs, running, cap) {
   // slot allocation ties across projects.
   projectCandidates.sort((a, b) => a.lowestPendingForProject - b.lowestPendingForProject);
 
-  // Aggregate batch across projects, consuming global slots as we go.
+  // Aggregate batch across projects, consuming global slots as we go. Track
+  // the first hold reason seen so callers can explain an empty overall batch.
   const batch = [];
+  let heldReason = null;
   for (const { projectJobs, runningSlugsInProject } of projectCandidates) {
     if (slots <= 0) break;
-    const projectBatch = pickForProject(projectJobs, runningSlugsInProject, slots);
-    batch.push(...projectBatch);
-    slots -= projectBatch.length;
+    const projectResult = pickForProject(projectJobs, runningSlugsInProject, slots);
+    batch.push(...projectResult.batch);
+    slots -= projectResult.batch.length;
+    if (heldReason === null && projectResult.reason) heldReason = projectResult.reason;
   }
-  return batch;
+  return { batch, reason: batch.length === 0 ? heldReason : null };
 }
 
 module.exports = { pickForProject, pickNextBatch, DEFAULT_PROJECT_CWD };