claude-code-session-manager 0.58.0 → 0.60.0

package/src/main/__tests__/transcripts-doFlush-array.test.cjs

@@ -0,0 +1,118 @@
+/**
+ * transcripts-doFlush-array.test.cjs — unit tests for transcripts.cjs's
+ * doFlush()/readDelta() handling of classifyLine's array-of-events shape.
+ *
+ * Covers: one line producing several events all land in the getBuffer()
+ * drain flattened (not nested per line), a session with far more than the
+ * old 500-entry ring cap still returns every event via the line-offset
+ * index (the cap is gone), and each event's byte `ref` correctly points
+ * back at its own line in the transcript file on disk.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/transcripts-doFlush-array.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { subscribe, getBuffer, closeTab, transcriptPath } = require('../transcripts.cjs');
+
+let cwd;
+
+beforeEach(() => {
+  cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-doflush-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(cwd, { recursive: true, force: true });
+});
+
+function writeTranscript(cwdArg, sessionId, lines) {
+  const filePath = transcriptPath(cwdArg, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  return filePath;
+}
+
+test('a single multi-block line flattens into multiple buffered events', async () => {
+  const sessionId = 'sess-multi';
+  const tabId = 'tab-multi';
+  writeTranscript(cwd, sessionId, [
+    {
+      type: 'assistant',
+      message: {
+        content: [
+          { type: 'text', text: 'doing two things' },
+          { type: 'tool_use', name: 'Bash', id: 'tu-1', input: { command: 'ls' } },
+          { type: 'tool_use', name: 'Bash', id: 'tu-2', input: { command: 'pwd' } },
+        ],
+      },
+    },
+  ]);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const buf = await getBuffer(tabId);
+  expect(buf).toHaveLength(3);
+  expect(buf.map((e) => e.kind)).toEqual(['assistant', 'tool_use', 'tool_use']);
+  closeTab(tabId);
+});
+
+test('a session with far more than the old 500-entry cap still returns every event — the ring cap is gone', async () => {
+  const sessionId = 'sess-cap';
+  const tabId = 'tab-cap';
+  // 200 lines * 3 events each = 600 events > the old 500 cap.
+  const lines = Array.from({ length: 200 }, (_, i) => ({
+    type: 'assistant',
+    message: {
+      content: [
+        { type: 'text', text: `line ${i}` },
+        { type: 'tool_use', name: 'Bash', id: `tu-${i}-a`, input: { command: 'ls' } },
+        { type: 'tool_use', name: 'Bash', id: `tu-${i}-b`, input: { command: 'pwd' } },
+      ],
+    },
+  }));
+  writeTranscript(cwd, sessionId, lines);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const buf = await getBuffer(tabId);
+  expect(buf).toHaveLength(600);
+  // Nothing evicted — both the genuine first and last events survive.
+  expect(buf[0].data).toBe('line 0');
+  expect(buf[buf.length - 1].data.id).toBe('tu-199-b');
+  closeTab(tabId);
+});
+
+test('each event ref points at its own line — re-reading those bytes reproduces that exact line', async () => {
+  const sessionId = 'sess-ref';
+  const tabId = 'tab-ref';
+  const filePath = writeTranscript(cwd, sessionId, [
+    { type: 'user', message: { content: 'first line — some unicode: héllo 🎉' } },
+    { type: 'assistant', message: { content: 'second line' } },
+  ]);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const buf = await getBuffer(tabId);
+  expect(buf).toHaveLength(2);
+
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    for (const ev of buf) {
+      expect(ev.ref).toBeTruthy();
+      expect(ev.ref.filePath).toBe(filePath);
+      const readBuf = Buffer.alloc(ev.ref.byteLength);
+      fs.readSync(fd, readBuf, 0, ev.ref.byteLength, ev.ref.byteOffset);
+      const parsed = JSON.parse(readBuf.toString('utf8'));
+      expect(parsed.type).toBe(ev.kind);
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  closeTab(tabId);
+});

package/src/main/__tests__/transcripts-paged-reads.test.cjs

@@ -0,0 +1,233 @@
+/**
+ * transcripts-paged-reads.test.cjs — unit tests for the line-offset index +
+ * paged-read API that replaced transcripts.cjs's 500-entry ring buffer
+ * (PRD 979). Covers:
+ *  - scrolling to the top of a >500-event session returns the genuine first
+ *    event via readPage/pageEvents, not a truncated window
+ *  - paging is a bounded positional read, never a whole-file materialization
+ *  - bounded memory: indexing a huge number of lines (plus one multi-MB
+ *    line) keeps the persisted index far smaller than the raw content
+ *  - inode-change rotation and truncation invalidate and rebuild the index
+ *  - a partial trailing line is never indexed until it completes
+ *  - a malformed JSON line still occupies its index slot (line numbering
+ *    stays correct)
+ *  - release()/re-subscribe fast-resume preserves the index, not just offset
+ *  - paging never re-emits to OTEL (only the live doFlush ingest path does)
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/transcripts-paged-reads.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach, vi } from 'vitest';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { subscribe, release, closeTab, transcriptPath, pageEvents } = require('../transcripts.cjs');
+const otel = require('../otel.cjs');
+
+let cwd;
+
+beforeEach(() => {
+  cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-paged-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(cwd, { recursive: true, force: true });
+});
+
+function writeTranscript(cwdArg, sessionId, lines) {
+  const filePath = transcriptPath(cwdArg, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  return filePath;
+}
+
+test('paging to line 0 of a >500-event session returns the genuine first event', async () => {
+  const sessionId = 'sess-page-top';
+  const tabId = 'tab-page-top';
+  const lines = Array.from({ length: 800 }, (_, i) => ({
+    type: 'user',
+    message: { content: [{ type: 'text', text: `event number ${i}` }] },
+  }));
+  writeTranscript(cwd, sessionId, lines);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+
+  const top = await pageEvents(tabId, 0, 0);
+  expect(top.totalLines).toBe(800);
+  expect(top.events).toHaveLength(1);
+  expect(top.events[0].data).toBe('event number 0');
+  expect(top.events[0].lineNumber).toBe(0);
+
+  const bottom = await pageEvents(tabId, 799, 799);
+  expect(bottom.events[0].data).toBe('event number 799');
+
+  closeTab(tabId);
+});
+
+test('bounded memory: indexing many lines plus one multi-MB line keeps the index far smaller than the raw content', async () => {
+  const sessionId = 'sess-bounded';
+  const tabId = 'tab-bounded';
+  const NUM_LINES = 20000;
+  const bigLineIndex = 10000;
+  const bigText = 'x'.repeat(5 * 1024 * 1024); // 5MB single line
+  const lines = Array.from({ length: NUM_LINES }, (_, i) => {
+    if (i === bigLineIndex) {
+      return { type: 'user', message: { content: [{ type: 'text', text: bigText }] } };
+    }
+    return { type: 'user', message: { content: [{ type: 'text', text: `line ${i}` }] } };
+  });
+  writeTranscript(cwd, sessionId, lines);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+
+  const sub = require('../transcripts.cjs').__getSubForTest?.(tabId);
+  // Fall back to reading the module's internal state via pageEvents' totalLines
+  // if the internal accessor isn't exported; either way, assert the ceiling on
+  // what actually persists: the index itself, not the file content.
+  const { totalLines } = await pageEvents(tabId, 0, 0);
+  expect(totalLines).toBe(NUM_LINES);
+
+  // Each index entry is two small integers (byteOffset, byteLength). Even a
+  // generous 64 bytes/entry ceiling for NUM_LINES entries is three orders of
+  // magnitude below the 5MB+ raw content of the one huge line — proving the
+  // index never holds the line's actual text.
+  const CEILING_BYTES = NUM_LINES * 64;
+  expect(CEILING_BYTES).toBeLessThan(bigText.length);
+  if (sub) {
+    const approxIndexBytes = sub.lineIndex.length * 16; // 2 numbers/entry
+    expect(approxIndexBytes).toBeLessThan(CEILING_BYTES);
+    // The big line's text must not appear anywhere in the index entries.
+    for (const entry of sub.lineIndex) {
+      expect(Object.keys(entry).sort()).toEqual(['byteLength', 'byteOffset']);
+    }
+  }
+
+  closeTab(tabId);
+});
+
+test('inode-change rotation invalidates and rebuilds the index — no stale offsets served', async () => {
+  const sessionId = 'sess-rotate';
+  const tabId = 'tab-rotate';
+  const filePath = writeTranscript(cwd, sessionId, [
+    { type: 'user', message: { content: [{ type: 'text', text: 'old-a' }] } },
+    { type: 'user', message: { content: [{ type: 'text', text: 'old-b' }] } },
+  ]);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  let page = await pageEvents(tabId, 0, 1);
+  expect(page.totalLines).toBe(2);
+
+  // Simulate log rotation: unlink + recreate (new inode) with different content.
+  fs.unlinkSync(filePath);
+  fs.writeFileSync(filePath, [{ type: 'user', message: { content: [{ type: 'text', text: 'new-a' }] } }].map((l) => JSON.stringify(l)).join('\n') + '\n');
+
+  // The chokidar watcher on the live sub picks up the rotation and rebuilds
+  // the index via readDelta's inode-change reset — poll (bounded) rather
+  // than assume a fixed debounce delay.
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    page = await pageEvents(tabId, 0, 0);
+    if (page.totalLines === 1 && page.events[0]?.data === 'new-a') break;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  expect(page.totalLines).toBe(1);
+  expect(page.events[0].data).toBe('new-a');
+  closeTab(tabId);
+}, 10000);
+
+test('a partial trailing line is not indexed until it completes', async () => {
+  const sessionId = 'sess-partial';
+  const tabId = 'tab-partial';
+  const filePath = transcriptPath(cwd, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const complete = JSON.stringify({ type: 'user', message: { content: [{ type: 'text', text: 'first' }] } });
+  // No trailing newline — this line is "still being written".
+  fs.writeFileSync(filePath, complete + '\n' + '{"type":"user","message":{"content":[{"type":"text","text":"unfinishe');
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  let page = await pageEvents(tabId, 0, 10);
+  expect(page.totalLines).toBe(1);
+  expect(page.events[0].data).toBe('first');
+
+  closeTab(tabId);
+});
+
+test('a malformed JSON line still occupies its index slot — line numbering stays correct', async () => {
+  const sessionId = 'sess-malformed';
+  const tabId = 'tab-malformed';
+  const filePath = transcriptPath(cwd, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const body = [
+    JSON.stringify({ type: 'user', message: { content: [{ type: 'text', text: 'ok-0' }] } }),
+    'not valid json {{{',
+    JSON.stringify({ type: 'user', message: { content: [{ type: 'text', text: 'ok-2' }] } }),
+  ].join('\n') + '\n';
+  fs.writeFileSync(filePath, body);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const page = await pageEvents(tabId, 0, 2);
+  expect(page.totalLines).toBe(3);
+  // Malformed line 1 produces no event, but line 2's numbering is unaffected.
+  expect(page.events.map((e) => e.lineNumber)).toEqual([0, 2]);
+  expect(page.events[1].data).toBe('ok-2');
+
+  closeTab(tabId);
+});
+
+test('release()/re-subscribe fast-resume preserves the index rather than re-reading from byte 0', async () => {
+  const sessionId = 'sess-resume';
+  const tabId = 'tab-resume';
+  writeTranscript(cwd, sessionId, [
+    { type: 'user', message: { content: [{ type: 'text', text: 'a' }] } },
+    { type: 'user', message: { content: [{ type: 'text', text: 'b' }] } },
+  ]);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const before = await pageEvents(tabId, 0, 1);
+  expect(before.totalLines).toBe(2);
+
+  release(tabId); // view-switch away — sub stays cached
+  // Re-subscribing the same tab should promote it back from the LRU cache
+  // rather than re-reading the transcript from scratch.
+  const res2 = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res2.ok).toBe(true);
+  const after = await pageEvents(tabId, 0, 1);
+  expect(after.totalLines).toBe(2);
+  expect(after.events.map((e) => e.data)).toEqual(['a', 'b']);
+
+  closeTab(tabId);
+});
+
+test('paging never re-emits to OTEL — only the live doFlush ingest path records', async () => {
+  const sessionId = 'sess-otel';
+  const tabId = 'tab-otel';
+  writeTranscript(cwd, sessionId, [
+    { type: 'user', message: { content: 'one' } },
+    { type: 'user', message: { content: 'two' } },
+  ]);
+
+  const spy = vi.spyOn(otel, 'recordTranscriptEvent');
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const callsAfterSubscribe = spy.mock.calls.length;
+  expect(callsAfterSubscribe).toBeGreaterThan(0); // initial drain recorded both events
+
+  // Page over the same range repeatedly — must not add more OTEL calls.
+  await pageEvents(tabId, 0, 1);
+  await pageEvents(tabId, 0, 1);
+  await pageEvents(tabId, 0, 0);
+  expect(spy.mock.calls.length).toBe(callsAfterSubscribe);
+
+  spy.mockRestore();
+  closeTab(tabId);
+});

package/src/main/__tests__/uniquePrdNumbers.test.cjs

@@ -95,12 +95,17 @@ describe('pickForProject dependsOn eligibility (PRD 832)', () => {
     expect(res.reason).toContain('854-base');
   });
 
-  it('legacy same-NN pending jobs keep their wave order untouched', () => {
+  // Contract change: parallelGroup no longer gates batch membership at all
+  // (it was a wave number; PRD 832 made it unique per PRD, which silently
+  // reduced every batch to one job). Legacy same-NN rows are simply eligible
+  // like anything else with no blocking dependsOn — the 828 row is no longer
+  // held back merely for carrying a higher number.
+  it('legacy same-NN pending jobs are eligible alongside higher-numbered ones', () => {
     const a = job('827-one', 'pending', 827);
     const b = job('827-two', 'pending', 827);
     const later = job('828-three', 'pending', 828);
     const res = pickForProject([a, b, later], new Set(), 3);
-    expect(res.batch.map((j) => j.slug).sort()).toEqual(['827-one', '827-two']);
+    expect(res.batch.map((j) => j.slug).sort()).toEqual(['827-one', '827-two', '828-three']);
   });
 });
 

package/src/main/health.cjs

@@ -78,7 +78,11 @@ function evaluateTickLiveness(queueState, heartbeat, now, runningCount) {
   const pending = jobs.filter((j) => j.status === 'pending');
   const running = runningCount ?? jobs.filter((j) => j.status === 'running').length;
   const config = queueState.config || {};
-  const concurrencyCap = config.concurrencyCap ?? Infinity;
+  // The scheduler's private concurrencyCap is retired — the machine-wide
+  // sessionSlots pool is the only limit. Read it lazily so this stays a pure
+  // function of its args when a caller supplies slotCap explicitly.
+  const concurrencyCap = queueState.slotCap
+    ?? (() => { try { return require('./lib/sessionSlots.cjs').totalSlots(); } catch { return Infinity; } })();
 
   if (pending.length === 0) return { stalled: false, reason: 'no-pending-jobs' };
   if (queueState.paused) return { stalled: false, reason: 'paused' };

package/src/main/index.cjs

@@ -1021,7 +1021,7 @@ app.whenReady().then(async () => {
     "img-src 'self' data: blob: smfile:",
     "font-src 'self' data: https://fonts.gstatic.com",
     // schemastore.org is used by Monaco for JSON schema validation
-    // (settings.json, keybindings.json — see App.tsx::installMonacoSchemas).
+    // (settings.json — see App.tsx::installMonacoSchemas).
     // The json.schemastore.org URL redirects to www.schemastore.org, so both
     // hosts must be in the allowlist or CSP blocks the redirect.
     "connect-src 'self' https://api.anthropic.com https://registry.npmjs.org https://json.schemastore.org https://www.schemastore.org",

package/src/main/ipcSchemas.cjs

@@ -8,7 +8,7 @@
 const { z } = require('zod');
 const os = require('node:os');
 const path = require('node:path');
-const { PromptSessionSchema, EpicTagSchema, EpicSourceSchema } = require('./lib/promptSessionSchema.cjs');
+const { PromptSessionSchema, EpicTagSchema, EpicSourceSchema, EpicIntakeSectionSchema } = require('./lib/promptSessionSchema.cjs');
 
 // ──────────────────────────────────────────── PTY
 const ptySpawn = z.object({
@@ -183,6 +183,23 @@ const transcriptUsageFor = z.object({
   sessionIds: z.array(z.string().regex(SESSION_UUID_RE)).max(500),
 });
 
+// Paged read over a subscribed transcript's line-offset index. Bounded line
+// numbers — a page is a scroll window, never an unbounded range request.
+const transcriptPage = z.object({
+  tabId: z.string().min(1).max(128),
+  startLine: z.number().int().min(0),
+  endLine: z.number().int().min(0),
+});
+
+// Single-line full-payload read via a classifier byte reference (expand-to-
+// full path, PRD chat-typed-event-renderers). byteLength bound mirrors
+// transcripts.cjs's MAX_REF_BYTES — one JSONL line, never a whole-file read.
+const transcriptReadRef = z.object({
+  filePath: z.string().min(1).max(4096),
+  byteOffset: z.number().int().min(0),
+  byteLength: z.number().int().min(1).max(64 * 1024 * 1024),
+});
+
 // ──────────────────────────────────────────── Config
 const configPath = z.object({ path: z.string().min(1).max(4096) });
 
@@ -285,6 +302,11 @@ const promptSessionsCreateEpic = z.object({
   tag: EpicTagSchema.optional(),
   agentType: z.string().min(1).max(256).optional(),
   source: EpicSourceSchema.optional(),
+  // The full first-prompt body + its labeled sections (epicIntake.ts's
+  // composeEpicIntake) — both optional, since not every mint caller (e.g. a
+  // future scripted Epic) composes a full opening prompt.
+  openingPrompt: z.string().max(200000).optional(),
+  sections: z.array(EpicIntakeSectionSchema).max(200).optional(),
 });
 
 // ──────────────────────────────────────────── Sessions
@@ -439,7 +461,6 @@ const home = os.homedir();
 const setConfigSchema = z.object({
   enabled: z.boolean().optional(),
   offsetMinutes: z.number().int().min(0).max(180).optional(),
-  concurrencyCap: z.number().int().min(1).max(20).optional(),
   defaultCwd: z.string().max(4096).refine(
     (s) => s === home || s.startsWith(home + path.sep),
     'defaultCwd must be inside home directory'
@@ -457,7 +478,7 @@ const setConfigSchema = z.object({
 // Machine-wide claude -p slot pool cap (sessionSlots.cjs) — deliberately its own
 // schema/channel rather than folded into setConfigSchema: it governs the shared
 // process pool, not any one project's scheduler config, and its range (0-10, 0
-// pauses new launches) differs from concurrencyCap's (1-20).
+// pauses new launches) is the single concurrency control.
 const setSessionSlotsSchema = z.object({
   cap: z.number().int().min(0).max(10),
 }).strict();
@@ -965,6 +986,8 @@ module.exports = {
     transcriptTabId,
     transcriptPath,
     transcriptUsageFor,
+    transcriptPage,
+    transcriptReadRef,
     configPath,
     configWriteJson,
     configWriteText,

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

@@ -92,3 +92,133 @@ test('a FAILED bare-named dep holds the dependent and reports an explicit reason
   assert.match(reason, /depends-gate/);
   assert.match(reason, /874-nav-face-project-home <- leftnav-two-face-framework/);
 });
+
+// ---------------------------------------------------------------------------
+// Parallelism regression coverage.
+//
+// `parallelGroup` used to gate batch membership: the picker fired at most one
+// group per tick and held every higher group while a lower one was in flight.
+// PRD 832 made the number strictly unique per PRD, so every group became a
+// singleton and the batch was always exactly ONE job — measured max
+// concurrency 1 across 25 recorded runs against a 5-slot pool. These tests
+// pin the corrected contract: dependsOn is the only barrier, parallelGroup is
+// a priority hint.
+// ---------------------------------------------------------------------------
+
+test('fires EVERY dependency-eligible job, not one per parallelGroup', () => {
+  const jobs = [
+    job('983-a', 'pending'),
+    job('984-b', 'pending'),
+    job('985-c', 'pending'),
+    job('986-d', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 5);
+  // Pre-fix this returned exactly ['983-a'] — one singleton group.
+  assert.deepEqual(batch.map((j) => j.slug), ['983-a', '984-b', '985-c', '986-d']);
+});
+
+test('a higher-numbered job is NOT held behind an in-flight lower-numbered one', () => {
+  const jobs = [
+    job('979-running', 'running'),
+    job('988-independent', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(['979-running']), 5);
+  // Pre-fix: held by the running-gate ("g979 in flight, holding g988"), which
+  // is how the fix for this very bug ended up stuck behind the bug.
+  assert.deepEqual(batch.map((j) => j.slug), ['988-independent']);
+});
+
+test('dependency-blocked jobs are excluded while independent siblings fire together', () => {
+  const jobs = [
+    job('985-foundation', 'pending'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+    job('987-independent', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch.map((j) => j.slug), ['985-foundation', '987-independent']);
+});
+
+test('a FAILED job holds its transitive dependents but not unrelated jobs', () => {
+  const jobs = [
+    job('980-broken', 'failed'),
+    job('981-direct', 'pending', { dependsOn: ['broken'] }),
+    job('982-transitive', 'pending', { dependsOn: ['direct'] }),
+    job('983-unrelated', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 5);
+  // Pre-fix the cross-group failure gate held 983 too, purely for having a
+  // higher number than the failure.
+  assert.deepEqual(batch.map((j) => j.slug), ['983-unrelated']);
+});
+
+test('parallelGroup orders the batch when eligible jobs exceed free slots', () => {
+  const jobs = [
+    job('990-c', 'pending'),
+    job('988-a', 'pending'),
+    job('989-b', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 2);
+  assert.deepEqual(batch.map((j) => j.slug), ['988-a', '989-b']);
+});
+
+test('zero free slots holds everything with an explicit reason', () => {
+  const jobs = [job('988-a', 'pending'), job('989-b', 'pending')];
+  const { batch, reason } = pick(jobs, new Set(), 0);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /no slots free/);
+});
+
+// ---------------------------------------------------------------------------
+// Per-job hold records (PRD 990). The picker already knew exactly which dep
+// held which row; it only ever reached console.log. These pin it as data.
+// ---------------------------------------------------------------------------
+
+test('reports a per-job hold record naming the blocking dep and its status', () => {
+  const jobs = [
+    job('985-foundation', 'pending'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+  ];
+  const { batch, holds } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch.map((j) => j.slug), ['985-foundation']);
+  assert.deepEqual(holds, [
+    { slug: '986-dependent', dep: 'foundation', depStatus: 'pending' },
+  ]);
+});
+
+test('hold record carries a running dep status', () => {
+  const jobs = [
+    job('985-foundation', 'running'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+  ];
+  const { holds } = pick(jobs, new Set(['985-foundation']), 5);
+  assert.deepEqual(holds, [
+    { slug: '986-dependent', dep: 'foundation', depStatus: 'running' },
+  ]);
+});
+
+test('hold record carries a failed dep status alongside the depends-gate reason', () => {
+  const jobs = [
+    job('985-foundation', 'failed'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+  ];
+  const { batch, reason, holds } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /depends-gate/);
+  assert.deepEqual(holds, [
+    { slug: '986-dependent', dep: 'foundation', depStatus: 'failed' },
+  ]);
+});
+
+test('no holds when nothing is dependency-blocked', () => {
+  const jobs = [job('988-a', 'pending'), job('989-b', 'pending')];
+  const { batch, holds } = pick(jobs, new Set(), 5);
+  assert.equal(batch.length, 2);
+  assert.deepEqual(holds, []);
+});
+
+test('an idle queue reports no holds (empty must not read as blocked)', () => {
+  const jobs = [job('988-a', 'completed')];
+  const { batch, holds } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch, []);
+  assert.deepEqual(holds, []);
+});