claude-code-session-manager 0.35.16 → 0.35.18

package/src/main/__tests__/prd-group-allocator.test.cjs

@@ -0,0 +1,119 @@
+/**
+ * prd-group-allocator.test.cjs — regression test for gh-issue-4 / PRD
+ * (allocateParallelGroup): two projects authoring PRDs concurrently under
+ * the shared prds/ directory both computed the same max-NN and allocated
+ * the same new parallel group (05-11 vs 06-09 on 2026-07-14, then 545 vs
+ * 545 again on 2026-07-15 between session-manager and sigma). NN is both
+ * the filename counter and the parallel-group key the scheduler parses,
+ * so a collision silently merges two unrelated projects' PRDs into one
+ * group.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/prd-group-allocator.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  allocateParallelGroup,
+  maxParallelGroupInUse,
+  parsePrdRaw,
+  _resetCache,
+} = require('../scheduler/prdParser.cjs');
+
+function mkTmpPrdsDir() {
+  return fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prd-alloc-'));
+}
+
+test('allocateParallelGroup returns max+1 on an empty directory', async () => {
+  const dir = await mkTmpPrdsDir();
+  const nn = await allocateParallelGroup(dir);
+  assert.strictEqual(nn, 1);
+});
+
+test('allocateParallelGroup scans the FULL directory, not a narrowed glob — reproduces the 577-PRD/max-544 live directory shape', async () => {
+  const dir = await mkTmpPrdsDir();
+  // Live directory (2026-07-18) holds an unpadded legacy name and a max of 544.
+  await fsp.writeFile(path.join(dir, '54-scheduler-memory-guard-cap3.md'), '# x\n');
+  await fsp.writeFile(path.join(dir, '110-some-slug.md'), '# x\n'); // would be missed by '^10[0-9]'
+  await fsp.writeFile(path.join(dir, '544-latest-prd.md'), '# x\n');
+  await fsp.writeFile(path.join(dir, '9-old-single-digit.md'), '# x\n');
+
+  const max = await maxParallelGroupInUse(dir);
+  assert.strictEqual(max, 544, 'must see 544 as the max even though 110 sorts before it lexically and 54/9 are unpadded');
+
+  const nn = await allocateParallelGroup(dir);
+  assert.strictEqual(nn, 545);
+});
+
+test('two concurrent allocateParallelGroup callers never receive the same new NN (the core race from the incident)', async () => {
+  const dir = await mkTmpPrdsDir();
+  await fsp.writeFile(path.join(dir, '544-latest-prd.md'), '# x\n');
+
+  const CONCURRENCY = 12;
+  const results = await Promise.all(
+    Array.from({ length: CONCURRENCY }, () => allocateParallelGroup(dir)),
+  );
+
+  const distinct = new Set(results);
+  assert.strictEqual(distinct.size, CONCURRENCY, `expected ${CONCURRENCY} distinct NNs, got collisions: ${results.join(',')}`);
+  for (const nn of results) {
+    assert.ok(nn > 544, `allocated NN ${nn} must not collide with existing on-disk NN 544`);
+  }
+});
+
+test('reservation markers are counted toward max-NN so a crash mid-allocation cannot be re-issued by a later caller', async () => {
+  const dir = await mkTmpPrdsDir();
+  await fsp.writeFile(path.join(dir, '544-latest-prd.md'), '# x\n');
+
+  const first = await allocateParallelGroup(dir); // 545, leaves .reserved-545 on disk
+  assert.strictEqual(first, 545);
+
+  // Simulate the caller never authoring 545-slug.md (crash between reserve
+  // and author). A later allocation must still move past 545, not reissue it.
+  const second = await allocateParallelGroup(dir);
+  assert.strictEqual(second, 546);
+});
+
+test('deliberate parallel siblings sharing one existing NN are unaffected by the allocator (main regression risk)', async () => {
+  const dir = await mkTmpPrdsDir();
+  // Three independent PRDs deliberately opting into the SAME group, exactly
+  // as /develop's SKILL.md contract allows — authored directly by filename,
+  // never through allocateParallelGroup.
+  await fsp.writeFile(path.join(dir, '545-scheduler-tick-stall-after-job-failure.md'), '---\ncwd: ~/Projects/session-manager\n---\nBody A\n');
+  await fsp.writeFile(path.join(dir, '545-filetree-show-hidden-default-and-persist.md'), '---\ncwd: ~/Projects/session-manager\n---\nBody B\n');
+  await fsp.writeFile(path.join(dir, '545-editor-tab-close-shortcut-and-close-right.md'), '---\ncwd: ~/Projects/session-manager\n---\nBody C\n');
+
+  const files = await fsp.readdir(dir);
+  const parsed = await Promise.all(
+    files.filter((f) => f.endsWith('.md')).map((f) => parsePrdRaw(path.join(dir, f))),
+  );
+  assert.strictEqual(parsed.length, 3);
+  for (const p of parsed) {
+    assert.strictEqual(p.parallelGroup, 545, 'siblings must keep sharing group 545 — the allocator must not renumber existing files');
+  }
+
+  // A brand-new PRD (not a deliberate sibling) allocated afterward must NOT
+  // land in 545 — it gets the next free group instead.
+  const nn = await allocateParallelGroup(dir);
+  assert.strictEqual(nn, 546);
+});
+
+test('module-level PRD dir-mtime cache in prdParser is unaffected by reservation markers (hidden files stay invisible to listPrdFiles)', async () => {
+  const dir = await mkTmpPrdsDir();
+  _resetCache();
+  await fsp.writeFile(path.join(dir, '1-a.md'), '# x\n');
+  const { listPrdFiles } = require('../scheduler/prdParser.cjs');
+  const before = await listPrdFiles(dir);
+  assert.strictEqual(before.length, 1);
+
+  await allocateParallelGroup(dir); // writes a .reserved-2 marker
+  _resetCache();
+  const after = await listPrdFiles(dir);
+  assert.strictEqual(after.length, 1, 'reservation markers must not appear as PRD files');
+});

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

@@ -0,0 +1,82 @@
+/**
+ * prdCreate.test.cjs — unit tests for the create-PRD body builder (PRD 549,
+ * gh-issue-6). Pure-function tests only; the HTTP route + auth/cwd-boundary
+ * behavior is covered by adminServer.test.cjs.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/prdCreate.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const {
+  deriveSlugFromTitle,
+  buildPrdBody,
+  readStandards,
+  PRD_CREATE_SLUG_RE,
+} = require('../lib/prdCreate.cjs');
+
+test('deriveSlugFromTitle lowercases, kebab-cases, and strips non-alnum runs', () => {
+  assert.strictEqual(deriveSlugFromTitle('Add Foo Bar!! Baz'), 'add-foo-bar-baz');
+  assert.strictEqual(deriveSlugFromTitle('  leading/trailing  '), 'leading-trailing');
+});
+
+test('deriveSlugFromTitle output always satisfies PRD_CREATE_SLUG_RE', () => {
+  const slug = deriveSlugFromTitle('Some Title 123');
+  assert.ok(PRD_CREATE_SLUG_RE.test(slug));
+});
+
+test('readStandards reads the real standards.md and returns non-empty text', async () => {
+  const text = await readStandards();
+  assert.ok(text.includes('Execution discipline'));
+});
+
+test('buildPrdBody emits required frontmatter keys and body sections in order', async () => {
+  const standards = await readStandards();
+  const body = buildPrdBody({
+    title: 'Do the thing',
+    cwd: '~/Projects/session-manager',
+    estimateMinutes: 15,
+    goal: 'Build the thing.',
+    acceptanceCriteria: ['thing exists', 'tests pass'],
+    implementationNotes: 'See file.cjs:10.',
+    outOfScope: ['not this'],
+  }, standards);
+
+  assert.ok(body.startsWith('---\n'));
+  assert.match(body, /title: Do the thing/);
+  assert.match(body, /cwd: ~\/Projects\/session-manager/);
+  assert.match(body, /estimateMinutes: 15/);
+
+  const goalIdx = body.indexOf('# Goal');
+  const acIdx = body.indexOf('# Acceptance criteria');
+  const implIdx = body.indexOf('# Implementation notes');
+  const oosIdx = body.indexOf('# Out of scope');
+  const standardsIdx = body.indexOf('## Engineering standards');
+  assert.ok(goalIdx > 0 && goalIdx < acIdx && acIdx < implIdx && implIdx < oosIdx && oosIdx < standardsIdx,
+    'sections must appear in Goal -> AC -> Implementation notes -> Out of scope -> Engineering standards order');
+
+  assert.match(body, /- \[ \] thing exists/);
+  assert.match(body, /- \[ \] tests pass/);
+  assert.match(body, /- not this/);
+  assert.ok(body.includes('Execution discipline'), 'must inline the standards.md content verbatim');
+});
+
+test('buildPrdBody omits parallelGroup frontmatter key when not supplied', () => {
+  const body = buildPrdBody({
+    title: 't', cwd: '~/x', estimateMinutes: 5, goal: 'g',
+    acceptanceCriteria: ['a'], implementationNotes: 'n',
+  }, 'standards text');
+  assert.ok(!/parallelGroup:/.test(body));
+});
+
+test('readStandards result is byte-identical to the on-disk file (single source of truth)', async () => {
+  const path = require('node:path');
+  const onDisk = fs.readFileSync(
+    path.join(__dirname, '..', '..', '..', 'plugins', 'session-manager-dev', 'skills', 'develop', 'standards.md'),
+    'utf8',
+  );
+  assert.strictEqual(await readStandards(), onDisk);
+});

package/src/main/__tests__/pty-write-result.test.cjs

@@ -0,0 +1,46 @@
+/**
+ * pty-write-result.test.cjs — unit tests for PtyManager.write()'s return contract.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/pty-write-result.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { manager } = require('../pty.cjs');
+
+test('write to an existing session succeeds', () => {
+  const tabId = 'tab-existing';
+  const proc = { write: () => {} };
+  manager.sessions.set(tabId, { proc, cwd: '/tmp', created: 0 });
+  try {
+    const result = manager.write({ tabId, data: 'hello' });
+    expect(result).toEqual({ ok: true });
+  } finally {
+    manager.sessions.delete(tabId);
+  }
+});
+
+test('write to a nonexistent tabId returns no-pty', () => {
+  const result = manager.write({ tabId: 'tab-does-not-exist', data: 'hello' });
+  expect(result).toEqual({ ok: false, reason: 'no-pty' });
+});
+
+test('write where proc.write throws returns the error reason without throwing', () => {
+  const tabId = 'tab-throws';
+  const proc = {
+    write: () => {
+      throw new Error('EPIPE: write after end');
+    },
+  };
+  manager.sessions.set(tabId, { proc, cwd: '/tmp', created: 0 });
+  try {
+    let result;
+    expect(() => {
+      result = manager.write({ tabId, data: 'hello' });
+    }).not.toThrow();
+    expect(result).toEqual({ ok: false, reason: 'EPIPE: write after end' });
+  } finally {
+    manager.sessions.delete(tabId);
+  }
+});

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

@@ -973,3 +973,149 @@ test('halt result + sentinel PASS + committedDuringRun:true → still halt', asy
     rmdir(tmp);
   }
 });
+
+// ─── -merge-main postcondition exemption tests (2026-07-18 feedback) ──────────
+
+const { isMergeMainSlug, extractMergeMainPrNumber } = require('../runVerify.cjs');
+
+test('isMergeMainSlug matches the NN-prXXX-merge-main and NN-fix-prXXX-merge-main conventions', () => {
+  assert.equal(isMergeMainSlug('565-pr188-merge-main'), true);
+  assert.equal(isMergeMainSlug('571-fix-pr141-merge-main'), true);
+  assert.equal(isMergeMainSlug('523-fix-bounded-fix-plan-retry'), false);
+  assert.equal(isMergeMainSlug('406-browser-capture-panel-ui'), false);
+  assert.equal(isMergeMainSlug(''), false);
+  assert.equal(isMergeMainSlug(undefined), false);
+});
+
+test('extractMergeMainPrNumber prefers "PR #<n>" in text, falls back to slug', () => {
+  assert.equal(extractMergeMainPrNumber('565-pr188-merge-main', 'title: Merge current main into sigma PR #188 (round 2)'), 188);
+  assert.equal(extractMergeMainPrNumber('565-pr188-merge-main', 'no pr mention here'), 188);
+  assert.equal(extractMergeMainPrNumber('non-standard-slug', 'no pr mention here'), null);
+});
+
+// (1) -merge-main + PASS + no commit + gh reports MERGEABLE/non-CONFLICTING → verified, no issue
+test('merge-main exemption: gh reports MERGEABLE → pass_no_commit_target_verified, no issue pushed', async () => {
+  const tmp = makeTmpDir();
+  try {
+    const slug = '565-pr188-merge-main';
+    writeLog(tmp, slug, noOpRunEvents('PR #188 was already merged into main by another actor.\nSCHEDULER_VERDICT: PASS'));
+    const prdPath = writePrd(tmp, slug, '# Merge current main into sigma PR #188');
+    let ghCalls = 0;
+    const ghExecImpl = (cmd, args, opts) => {
+      ghCalls++;
+      assert.equal(cmd, 'gh');
+      assert.deepEqual(args, ['pr', 'view', '188', '--json', 'mergeable,mergeStateStatus']);
+      assert.equal(opts.cwd, '/tmp/sigma');
+      return JSON.stringify({ mergeable: 'MERGEABLE', mergeStateStatus: 'BEHIND' });
+    };
+    const verdict = await verifyRun({
+      runDir: tmp,
+      prdPath,
+      queueEntry: { slug, status: 'running', cwd: '/tmp/sigma' },
+      allJobs: [],
+      committedDuringRun: false,
+      ghExecImpl,
+    });
+    assert.equal(ghCalls, 1);
+    assert.equal(verdict.verdict, 'pass_no_commit_target_verified', `expected verified verdict, got ${verdict.verdict}: ${verdict.reason}`);
+    assert.equal(verdict.downgradeTo, null);
+    assert.equal(verdict.verifiedPrNumber, 188);
+  } finally {
+    rmdir(tmp);
+  }
+});
+
+// (2) -merge-main + PASS + no commit + gh reports CONFLICTING → falls through to pass_no_commit
+test('merge-main exemption: gh reports CONFLICTING → falls through to pass_no_commit', async () => {
+  const tmp = makeTmpDir();
+  try {
+    const slug = '565-pr188-merge-main';
+    writeLog(tmp, slug, noOpRunEvents('PR #188 needs no further work.\nSCHEDULER_VERDICT: PASS'));
+    const prdPath = writePrd(tmp, slug, '# Merge current main into sigma PR #188');
+    const ghExecImpl = () => JSON.stringify({ mergeable: 'MERGEABLE', mergeStateStatus: 'CONFLICTING' });
+    const verdict = await verifyRun({
+      runDir: tmp,
+      prdPath,
+      queueEntry: { slug, status: 'running', cwd: '/tmp/sigma' },
+      allJobs: [],
+      committedDuringRun: false,
+      ghExecImpl,
+    });
+    assert.equal(verdict.verdict, 'pass_no_commit', `expected fallback to pass_no_commit, got ${verdict.verdict}: ${verdict.reason}`);
+    assert.equal(verdict.downgradeTo, 'needs_review');
+  } finally {
+    rmdir(tmp);
+  }
+});
+
+// (3) -merge-main + PASS + no commit + gh call fails/times out → falls through to pass_no_commit, never throws
+test('merge-main exemption: gh call throws → falls through to pass_no_commit, never throws', async () => {
+  const tmp = makeTmpDir();
+  try {
+    const slug = '565-pr188-merge-main';
+    writeLog(tmp, slug, noOpRunEvents('PR #188 needs no further work.\nSCHEDULER_VERDICT: PASS'));
+    const prdPath = writePrd(tmp, slug, '# Merge current main into sigma PR #188');
+    const ghExecImpl = () => { throw new Error('gh: command not found'); };
+    const verdict = await verifyRun({
+      runDir: tmp,
+      prdPath,
+      queueEntry: { slug, status: 'running', cwd: '/tmp/sigma' },
+      allJobs: [],
+      committedDuringRun: false,
+      ghExecImpl,
+    });
+    assert.equal(verdict.verdict, 'pass_no_commit', `expected fallback to pass_no_commit, got ${verdict.verdict}: ${verdict.reason}`);
+    assert.equal(verdict.downgradeTo, 'needs_review');
+  } finally {
+    rmdir(tmp);
+  }
+});
+
+// (4) non-merge-main slug, PASS + no commit → unchanged pass_no_commit behavior, zero gh invocations
+test('merge-main exemption: non-merge-main slug never attempts a gh call', async () => {
+  const tmp = makeTmpDir();
+  try {
+    const slug = '406-browser-capture-panel-ui';
+    writeLog(tmp, slug, noOpRunEvents('All acceptance criteria verified.\nSCHEDULER_VERDICT: PASS'));
+    const prdPath = writePrd(tmp, slug, '# Browser capture panel UI');
+    let ghCalls = 0;
+    const ghExecImpl = () => { ghCalls++; return JSON.stringify({ mergeable: 'MERGEABLE', mergeStateStatus: 'CLEAN' }); };
+    const verdict = await verifyRun({
+      runDir: tmp,
+      prdPath,
+      queueEntry: { slug, status: 'running', cwd: '/tmp/proj' },
+      allJobs: [],
+      committedDuringRun: false,
+      ghExecImpl,
+    });
+    assert.equal(ghCalls, 0, 'gh must never be invoked for a non-merge-main slug');
+    assert.equal(verdict.verdict, 'pass_no_commit', `expected unchanged pass_no_commit, got ${verdict.verdict}: ${verdict.reason}`);
+    assert.equal(verdict.downgradeTo, 'needs_review');
+  } finally {
+    rmdir(tmp);
+  }
+});
+
+// (5) -merge-main slug but a real commit DID land → unaffected, path unreachable, zero gh invocations
+test('merge-main exemption: commit landed → path unreachable, zero gh invocations, verdict clean', async () => {
+  const tmp = makeTmpDir();
+  try {
+    const slug = '565-pr188-merge-main';
+    writeLog(tmp, slug, noOpRunEvents('Merged and pushed.\nSCHEDULER_VERDICT: PASS'));
+    const prdPath = writePrd(tmp, slug, '# Merge current main into sigma PR #188');
+    let ghCalls = 0;
+    const ghExecImpl = () => { ghCalls++; return JSON.stringify({ mergeable: 'MERGEABLE', mergeStateStatus: 'CLEAN' }); };
+    const verdict = await verifyRun({
+      runDir: tmp,
+      prdPath,
+      queueEntry: { slug, status: 'running', cwd: '/tmp/sigma' },
+      allJobs: [],
+      committedDuringRun: true,
+      ghExecImpl,
+    });
+    assert.equal(ghCalls, 0, 'gh must never be invoked when a commit already landed');
+    assert.equal(verdict.verdict, 'clean', `expected clean (commit landed, sentinel PASS), got ${verdict.verdict}: ${verdict.reason}`);
+  } finally {
+    rmdir(tmp);
+  }
+});

package/src/main/__tests__/scheduler-committed-in-window.test.cjs

@@ -1,11 +1,13 @@
 /**
  * scheduler-committed-in-window.test.cjs — unit tests for committedInWindow.
  *
- * Run: timeout 300 npx vitest run src/main/__tests__/scheduler-committed-in-window.test.cjs
+ * Run: timeout 120 node --test src/main/__tests__/scheduler-committed-in-window.test.cjs
  */
 
 'use strict';
 
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
@@ -42,7 +44,7 @@ test('committedInWindow returns true for a commit landed on a non-checked-out br
     git(dir, ['checkout', '-q', '-b', 'other-branch-at-exit']);
 
     const result = await committedInWindow(dir, startedAt, finishedAt);
-    expect(result).toBe(true);
+    assert.strictEqual(result, true);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -55,7 +57,7 @@ test('committedInWindow returns false when the window covers no commit', async (
     const farFutureEnd = new Date(Date.now() + 366 * 24 * 60 * 60 * 1000).toISOString();
 
     const result = await committedInWindow(dir, farFutureStart, farFutureEnd);
-    expect(result).toBe(false);
+    assert.strictEqual(result, false);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }

package/src/main/__tests__/scheduler-tick-cancel-token.test.cjs

@@ -0,0 +1,54 @@
+/**
+ * scheduler-tick-cancel-token.test.cjs — regression test for the 2026-07-14
+ * scheduler stall (PRD 543/544): the tick loop stopped picking up pending
+ * jobs after a job's run paused the queue (e.g. a rate limit), because the
+ * pause's cancelToken.cancelled flag was only ever reset inside
+ * runDueJobs() — clearPause() (used by the poll-loop's auth/network
+ * auto-recovery and the manual "Resume" button) never reset it, so every
+ * subsequent tickQueue() call short-circuited on the stale flag forever,
+ * even though queue.json's `paused` field was correctly null.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/scheduler-tick-cancel-token.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { applyPauseCleared, pickNextBatch } = require('../scheduler.cjs');
+
+test('clearPause un-cancels the tick guard so the next pending job still starts', () => {
+  // A job's run pauses the queue (e.g. rate limit) — setPaused() cancels the
+  // in-flight tick batch.
+  const cancelToken = { cancelled: true };
+
+  // The pause is cleared via a recovery path OTHER than runDueJobs() (the
+  // poll-loop's auth/network auto-recovery, or the manual "Resume" button —
+  // both call clearPause() directly). Before the fix, this left
+  // cancelToken.cancelled stuck at true forever.
+  applyPauseCleared(true, cancelToken);
+
+  assert.strictEqual(
+    cancelToken.cancelled,
+    false,
+    'clearPause must un-cancel the tick guard, or every future tick short-circuits forever even though paused=null',
+  );
+
+  // With the guard cleared, the next tick's batch-picking proceeds normally
+  // and starts the next pending job after the failed one.
+  const jobs = [
+    { slug: '543-chat-mode-data-table-rendering', status: 'failed', cwd: '/proj' },
+    { slug: '544-committed-in-window-test-runner-consistency', status: 'pending', cwd: '/proj' },
+  ];
+  const { batch } = pickNextBatch(jobs, new Set(), 3);
+  assert.strictEqual(batch.length, 1);
+  assert.strictEqual(batch[0].slug, '544-committed-in-window-test-runner-consistency');
+});
+
+test('applyPauseCleared is a no-op when the queue was not actually paused', () => {
+  const cancelToken = { cancelled: false };
+  applyPauseCleared(false, cancelToken);
+  assert.strictEqual(cancelToken.cancelled, false);
+});
+
+console.log('scheduler-tick-cancel-token tests: PASS');

package/src/main/__tests__/scheduler-transient-failure.test.cjs

@@ -0,0 +1,141 @@
+/**
+ * scheduler-transient-failure.test.cjs — classifying network-outage vs. real
+ * code failures so a transient outage (PRD 543/545: ENOTFOUND) gets a bounded
+ * requeue instead of burning a whole run + an auto-fix investigation on an
+ * outage that has nothing to do with the code.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/scheduler-transient-failure.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  detectNetworkErrorInLog,
+  detectRateLimitInLog,
+  classifyFailureOutcome,
+  TRANSIENT_RETRY_CAP,
+} = require('../scheduler.cjs');
+
+// Real tail captured from the 543 incident run (2026-07-14T14-40-39-306Z),
+// per the PRD's "reuse it, don't re-derive" instruction.
+const NETWORK_OUTAGE_LOG_TAIL = String.raw`
+{"type":"result","subtype":"success","is_error":true,"api_error_status":null,"duration_ms":592749,"duration_api_ms":83313,"num_turns":19,"result":"API Error: Unable to connect to API (ENOTFOUND)","stop_reason":"stop_sequence","session_id":"85b1a3f4-3625-4f2d-a9f0-b3994f062b39","total_cost_usd":0.75,"terminal_reason":"api_error","uuid":"cc041889-4497-4fca-9f83-73e3dae6de54"}
+`;
+
+const RATE_LIMIT_LOG_TAIL = String.raw`
+{"type":"result","subtype":"error","is_error":true,"api_error_status":429,"rateLimitType":"five_hour","result":"You've hit your limit","uuid":"abc"}
+`;
+
+const REAL_CODE_FAILURE_LOG_TAIL = String.raw`
+{"type":"result","subtype":"error","is_error":true,"result":"Error: expected 2 but got 3\n  at test/foo.test.ts:12:5","terminal_reason":"error_max_turns","uuid":"def"}
+`;
+
+function writeTmpLog(contents) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-transient-log-'));
+  const p = path.join(dir, 'run.log');
+  fs.writeFileSync(p, contents);
+  return p;
+}
+
+test('detectNetworkErrorInLog fires only on terminal_reason:api_error + a network-class error', () => {
+  const p = writeTmpLog(NETWORK_OUTAGE_LOG_TAIL);
+  try {
+    assert.strictEqual(detectNetworkErrorInLog(p), true);
+  } finally {
+    fs.rmSync(path.dirname(p), { recursive: true, force: true });
+  }
+});
+
+test('detectNetworkErrorInLog does not fire on a genuine code failure (no terminal_reason:api_error)', () => {
+  const p = writeTmpLog(REAL_CODE_FAILURE_LOG_TAIL);
+  try {
+    assert.strictEqual(detectNetworkErrorInLog(p), false);
+  } finally {
+    fs.rmSync(path.dirname(p), { recursive: true, force: true });
+  }
+});
+
+test('detectNetworkErrorInLog does not fire on a rate-limit log (rateLimited handling stays separate)', () => {
+  const p = writeTmpLog(RATE_LIMIT_LOG_TAIL);
+  try {
+    assert.strictEqual(detectNetworkErrorInLog(p), false);
+    // And the reverse: the rate-limit detector doesn't fire on the network log.
+    assert.strictEqual(detectRateLimitInLog(p), true);
+  } finally {
+    fs.rmSync(path.dirname(p), { recursive: true, force: true });
+  }
+});
+
+test('detectRateLimitInLog does not fire on a network-outage log', () => {
+  const p = writeTmpLog(NETWORK_OUTAGE_LOG_TAIL);
+  try {
+    assert.strictEqual(detectRateLimitInLog(p), false);
+  } finally {
+    fs.rmSync(path.dirname(p), { recursive: true, force: true });
+  }
+});
+
+test('classifyFailureOutcome: ENOTFOUND-class network error with a clean tree retries (bounded)', () => {
+  const decision = classifyFailureOutcome({
+    exitCode: 1,
+    networkError: true,
+    durationMs: 594_000,
+    transientRetries: 0,
+    newlyDirtyCount: 0,
+  });
+  assert.strictEqual(decision.action, 'retry');
+  assert.strictEqual(decision.transientKind, 'network');
+  assert.strictEqual(decision.retries, 0);
+});
+
+test('classifyFailureOutcome: network error with uncommitted work left behind refuses to requeue', () => {
+  const decision = classifyFailureOutcome({
+    exitCode: 1,
+    networkError: true,
+    durationMs: 594_000,
+    transientRetries: 0,
+    newlyDirtyCount: 2,
+  });
+  assert.strictEqual(decision.action, 'fail-dirty');
+  assert.strictEqual(decision.newlyDirtyCount, 2);
+});
+
+test('classifyFailureOutcome: retry cap exhausted fails without auto-fix, never loops unboundedly', () => {
+  const decision = classifyFailureOutcome({
+    exitCode: 1,
+    networkError: true,
+    durationMs: 594_000,
+    transientRetries: TRANSIENT_RETRY_CAP,
+    newlyDirtyCount: 0,
+  });
+  assert.strictEqual(decision.action, 'fail-cap');
+  assert.strictEqual(decision.retries, TRANSIENT_RETRY_CAP);
+});
+
+test('classifyFailureOutcome: a genuine code failure (non-network exit 1) is still terminal + investigated', () => {
+  const decision = classifyFailureOutcome({
+    exitCode: 1,
+    networkError: false,
+    durationMs: 30_000,
+    transientRetries: 0,
+    newlyDirtyCount: 0,
+  });
+  assert.strictEqual(decision.action, 'investigate');
+});
+
+test('classifyFailureOutcome: signal-kill transient (exit 143, short run) still retries as before', () => {
+  const decision = classifyFailureOutcome({
+    exitCode: 143,
+    networkError: false,
+    durationMs: 60_000,
+    transientRetries: 0,
+    newlyDirtyCount: 0,
+  });
+  assert.strictEqual(decision.action, 'retry');
+  assert.strictEqual(decision.transientKind, 'exit=143');
+});