claude-code-session-manager 0.57.1 → 0.59.0

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/chatRunner.cjs

@@ -52,6 +52,7 @@ const { extractJson } = require('./lib/extractJson.cjs');
 const { classifyPromptTicket } = require('./lib/classifyPromptTicket.cjs');
 const sessionSlots = require('./lib/sessionSlots.cjs');
 const opsErrorLog = require('./lib/opsErrorLog.cjs');
+const agentModelResolve = require('./lib/agentModelResolve.cjs');
 
 // ─── Stop-signal protocol ──────────────────────────────────────────────────
 // Single source of truth for the sentinel and parser. The renderer (PRD 320)
@@ -522,10 +523,18 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     // instruction to every prompt
     const fullPrompt = STOP_SIGNAL_INSTRUCTION + CHAT_MODE_TRUTH_INSTRUCTION + prompt;
 
+    // sessionId is the Epic's claudeSessionId for an Epic-backed tab (see
+    // comment above childEnv) — resolve that Epic's agentType persona model
+    // so Chat and Terminal views of the same Epic launch with the same
+    // model. Never throws; falls back to the hardcoded 'sonnet' literal when
+    // there's no Epic, no agentType, or the persona has no model/'inherit' —
+    // --model must never be left unpinned (CLAUDE.md model-pinning rule).
+    const model = agentModelResolve.resolveEpicModel({ cwd, claudeSessionId: sessionId });
+
     // Build argv as an array — no shell: true, no string interpolation
     const args = [
       '-p', fullPrompt,
-      '--model', 'sonnet',           // pinned per "claude -p model pinning" rule
+      '--model', model,
       '--dangerously-skip-permissions',
       '--output-format', 'stream-json',
       '--verbose',

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

@@ -32,6 +32,7 @@ const { appendAuditEvent } = require('./lib/auditLog.cjs');
 const chatRunner = require('./chatRunner.cjs');
 const promptSessionEvents = require('./promptSessionEvents.cjs');
 const activeIndexMerge = require('./lib/activeIndexMerge.cjs');
+const promptSessionsCreateEpic = require('./lib/promptSessionsCreateEpic.cjs');
 const agentLibrary = require('./agentLibrary.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
@@ -68,8 +69,6 @@ const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
 const filesIpc = require('./files.cjs');
 const { registerDocEditHandlers, attachWindow: attachDocEditWindow } = require('./docEdit.cjs');
-const searchIpc = require('./search.cjs');
-const repoAnalyzer = require('./repoAnalyzer.cjs');
 const webRemote = require('./webRemote.cjs');
 const { listExchanges } = require('./exchanges.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
@@ -819,6 +818,7 @@ registerHistoryDashboardHandlers();
 pluginInstall.registerPluginInstallHandlers();
 memoryTool.registerMemoryHandlers();
 activeIndexMerge.registerActiveIndexMergeHandlers();
+promptSessionsCreateEpic.registerPromptSessionsCreateEpicHandlers();
 registerMemoryAggregateIpc();
 registerProjectBriefIpc();
 registerProjectPagesIpc();
@@ -841,8 +841,6 @@ agentMemory.registerAgentMemoryHandlers();
 git.register(ipcMain);
 filesIpc.registerFilesHandlers();
 registerDocEditHandlers();
-searchIpc.registerSearchHandlers();
-repoAnalyzer.register(ipcMain);
 webRemote.registerRemoteHandlers();
 chatRunner.registerChatHandlers();
 
@@ -1023,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,6 +8,7 @@
 const { z } = require('zod');
 const os = require('node:os');
 const path = require('node:path');
+const { PromptSessionSchema, EpicTagSchema, EpicSourceSchema, EpicIntakeSectionSchema } = require('./lib/promptSessionSchema.cjs');
 
 // ──────────────────────────────────────────── PTY
 const ptySpawn = z.object({
@@ -182,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) });
 
@@ -229,9 +247,35 @@ const configParseImports = z.object({ path: z.string().min(1).max(4096) });
 // Real epic ids are `${slugify(goalText)}-${uuid8}` (epicMint.cjs) — max 64
 // mirrors slugify's 48-char cap plus the "-" + 8 hex chars suffix, rounded up.
 const PROMPT_SESSION_ID_RE = /^(?!__proto__$|constructor$|prototype$)[A-Za-z0-9_-]{1,64}$/;
+
+// Per-ROW validation, not per-BATCH. persistActiveIndex (state/promptSessions.ts)
+// sends every open Epic for a cwd in ONE call, so validating the map with a
+// single parse meant one malformed/legacy row rejected the whole payload —
+// every other legitimate Epic for that cwd silently stopped persisting (the
+// renderer only logs the failure). Dropping just the offending row matches how
+// the rest of this pipeline already fails: per-id (activeIndexMerge.cjs's
+// tombstone/resurrection handling), never per-batch.
+const dropInvalidSessions = (raw) => {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return raw;
+  const kept = Object.create(null);
+  for (const id of Object.keys(raw)) {
+    if (!PROMPT_SESSION_ID_RE.test(id)) {
+      console.warn(`[ipc] merge-active-index: dropping session with invalid id ${JSON.stringify(id)}`);
+      continue;
+    }
+    const parsed = PromptSessionSchema.safeParse(raw[id]);
+    if (!parsed.success) {
+      console.warn(`[ipc] merge-active-index: dropping malformed session ${id} — ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+      continue;
+    }
+    kept[id] = raw[id];
+  }
+  return kept;
+};
+
 const promptSessionsMergeActiveIndex = z.object({
   cwd: z.string().min(1).max(4096),
-  sessions: z.record(z.string().regex(PROMPT_SESSION_ID_RE), z.unknown()).refine(
+  sessions: z.preprocess(dropInvalidSessions, z.record(z.string().regex(PROMPT_SESSION_ID_RE), PromptSessionSchema)).refine(
     (v) => Object.keys(v).length <= 2000,
     { message: 'too many sessions in one merge payload' },
   ),
@@ -247,6 +291,24 @@ const promptSessionsMergeActiveIndex = z.object({
   source: z.literal('epics'),
 });
 
+// Renderer entry point for main's ensureEpic() (lib/promptSessionsCreateEpic.cjs)
+// — additive step 1 of a two-PRD chain; unused by the app until the next PRD
+// routes state/promptSessions.ts's createPromptSession through it. `tag`/
+// `source` reuse promptSessionSchema.cjs's own enums rather than retyping
+// the value lists a third time.
+const promptSessionsCreateEpic = z.object({
+  cwd: z.string().min(1).max(4096),
+  goalText: z.string().min(1).max(20000),
+  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
 const sessionsPayload = z.object({
   tabs: z.array(z.object({
@@ -345,7 +407,11 @@ const schedulerCreatePrd = z.object({
   // forgot to pass sourcePromptId explicitly.
   originClaudeSessionId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   // User-selected Feature/Bug tag (PRD 774) carried from the originating
-  // PromptTicket — deterministic, never LLM-classified.
+  // PromptTicket — deterministic, never LLM-classified. NOT the same value
+  // set as PromptSession's Epic-mission `tag` (lib/promptSessionSchema.cjs's
+  // EpicTagSchema) — that one also includes 'bilko-host-publisher'. Keep
+  // these two enums in sync deliberately if their meanings ever converge;
+  // don't assume editing one updates the other.
   tag: z.enum(['feature', 'bug', 'discussion', 'build', 'project-home-builder']).optional(),
 });
 
@@ -395,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'
@@ -413,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();
@@ -921,6 +986,8 @@ module.exports = {
     transcriptTabId,
     transcriptPath,
     transcriptUsageFor,
+    transcriptPage,
+    transcriptReadRef,
     configPath,
     configWriteJson,
     configWriteText,
@@ -971,6 +1038,7 @@ module.exports = {
     promptSessionTranscriptAppend,
     promptSessionTranscriptRead,
     promptSessionsMergeActiveIndex,
+    promptSessionsCreateEpic,
     auditLogAppend,
     agentMemoryList,
     agentMemoryGet,

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, []);
+});