claude-code-session-manager 0.80.0 → 0.82.0

package/src/main/__tests__/runVerify-blocked-by-foreign-wip.test.cjs

@@ -0,0 +1,58 @@
+/**
+ * runVerify-blocked-by-foreign-wip.test.cjs — scanSentinel's new
+ * BLOCKED_BY_FOREIGN_WIP token and the scanForeignWipPathsClaim evidence-line
+ * scanner (the executor-facing half of "give the executor a first-class
+ * verdict for a sibling job's in-flight file, but validate the claim").
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/runVerify-blocked-by-foreign-wip.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { scanSentinel, scanForeignWipPathsClaim } = require('../runVerify.cjs');
+
+function resultEventFor(text) {
+  return { kind: 'result', seq: 0, subtype: 'success', resultText: text };
+}
+
+test('scanSentinel: recognizes BLOCKED_BY_FOREIGN_WIP alongside PASS/FAIL', () => {
+  expect(scanSentinel(resultEventFor('SCHEDULER_VERDICT: PASS'), [])).toBe('pass');
+  expect(scanSentinel(resultEventFor('SCHEDULER_VERDICT: FAIL bad thing'), [])).toBe('fail');
+  expect(scanSentinel(resultEventFor('SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP'), [])).toBe('blocked_by_foreign_wip');
+});
+
+test('scanSentinel: BLOCKED_BY_FOREIGN_WIP only matches at line start, like PASS/FAIL', () => {
+  expect(scanSentinel(resultEventFor('I saw a SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP mention mid-sentence'), [])).toBe(null);
+});
+
+test('scanSentinel: falls back to the last tool_result content when no resultEvent matches', () => {
+  const events = [
+    { kind: 'tool_result', seq: 1, toolUseId: 'a', content: 'nothing here' },
+    { kind: 'tool_result', seq: 2, toolUseId: 'b', content: 'SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP\nFOREIGN_WIP_PATHS: src/foo.ts' },
+  ];
+  expect(scanSentinel(null, events)).toBe('blocked_by_foreign_wip');
+});
+
+test('scanForeignWipPathsClaim: extracts a comma-separated FOREIGN_WIP_PATHS line from resultEvent', () => {
+  const text = 'SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP\nFOREIGN_WIP_PATHS: src/foo.ts, src/bar.ts';
+  expect(scanForeignWipPathsClaim(resultEventFor(text), [])).toEqual(['src/foo.ts', 'src/bar.ts']);
+});
+
+test('scanForeignWipPathsClaim: dedupes and trims whitespace', () => {
+  const text = 'FOREIGN_WIP_PATHS:  src/foo.ts ,src/foo.ts, src/bar.ts ';
+  expect(scanForeignWipPathsClaim(resultEventFor(text), [])).toEqual(['src/foo.ts', 'src/bar.ts']);
+});
+
+test('scanForeignWipPathsClaim: returns [] when no FOREIGN_WIP_PATHS line is present', () => {
+  expect(scanForeignWipPathsClaim(resultEventFor('SCHEDULER_VERDICT: FAIL nope'), [])).toEqual([]);
+  expect(scanForeignWipPathsClaim(null, [])).toEqual([]);
+});
+
+test('scanForeignWipPathsClaim: falls back to the last tool_result content', () => {
+  const events = [
+    { kind: 'tool_result', seq: 1, toolUseId: 'a', content: 'FOREIGN_WIP_PATHS: src/stale.ts' },
+    { kind: 'tool_result', seq: 2, toolUseId: 'b', content: 'FOREIGN_WIP_PATHS: src/latest.ts' },
+  ];
+  expect(scanForeignWipPathsClaim(null, events)).toEqual(['src/latest.ts']);
+});

package/src/main/__tests__/runVerify-policy-denial.test.cjs

@@ -0,0 +1,89 @@
+/**
+ * runVerify-policy-denial.test.cjs — a PreToolUse hook denial (`Blocked: ...`
+ * tool_result) must not downgrade an otherwise-clean run, but a genuine
+ * late-run failure must still downgrade normally.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/runVerify-policy-denial.test.cjs
+ */
+
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+const { verifyRun } = require('../runVerify.cjs');
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'run-verify-policy-denial-test-'));
+}
+
+function rmdir(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function writeLog(dir, slug, events) {
+  const lines = ['[scheduler] starting ' + slug + ' at 2026-09-02T00:00:00.000Z'];
+  for (const ev of events) lines.push(JSON.stringify(ev));
+  lines.push('[scheduler] exit code=0 (raw code=0 signal=null) duration=47s');
+  fs.writeFileSync(path.join(dir, `${slug}.log`), lines.join('\n') + '\n');
+}
+
+function writePrd(dir, slug, body) {
+  const text = `---\ntitle: Test PRD\ncwd: /tmp\nestimateMinutes: 30\n---\n${body}\n`;
+  fs.writeFileSync(path.join(dir, `${slug}.md`), text);
+  return path.join(dir, `${slug}.md`);
+}
+
+test('PreToolUse policy denial (Blocked: ...) in final 20% → clean, surfaced as annotation', async () => {
+  const tmp = makeTmpDir();
+  try {
+    const slug = '1106-policy-denial-exempt';
+    const events = [];
+    for (let k = 0; k < 8; k++) {
+      events.push({ type: 'assistant', message: { role: 'assistant', content: [
+        { type: 'tool_use', id: `t${k}`, name: 'Read', input: { description: `read ${k}` } }] } });
+      events.push({ type: 'user', message: { role: 'user', content: [
+        { type: 'tool_result', tool_use_id: `t${k}`, content: 'ok', is_error: false }] } });
+    }
+    events.push({ type: 'assistant', message: { role: 'assistant', content: [
+      { type: 'tool_use', id: 'tgit', name: 'Bash', input: { command: 'git stash', description: 'stash before checkout' } }] } });
+    events.push({ type: 'user', message: { role: 'user', content: [
+      { type: 'tool_result', tool_use_id: 'tgit',
+        content: 'Blocked: `stash` in what this hook believes is a SHARED working tree (/home/bilko/Projects/session-manager).',
+        is_error: true }] } });
+    events.push({ type: 'result', subtype: 'success', result: 'All acceptance criteria verified.\nSCHEDULER_VERDICT: PASS' });
+
+    writeLog(tmp, slug, events);
+    const prdPath = writePrd(tmp, slug, '# Policy denial exempt');
+    const verdict = await verifyRun({ runDir: tmp, prdPath, queueEntry: { slug, status: 'running' }, allJobs: [], committedDuringRun: true });
+    assert.equal(verdict.verdict, 'clean', `policy denial must not flag, got ${verdict.verdict}: ${verdict.reason}`);
+    assert.ok(
+      Array.isArray(verdict.annotations) && verdict.annotations.some((a) => a.verdict === 'policy_denial'),
+      `expected a policy_denial annotation, got ${JSON.stringify(verdict.annotations)}`,
+    );
+  } finally { rmdir(tmp); }
+});
+
+test('genuine late-run failure (not a policy denial) still downgrades to transcript_errors', async () => {
+  const tmp = makeTmpDir();
+  try {
+    const slug = '1106-genuine-failure-still-flags';
+    const events = [];
+    for (let k = 0; k < 8; k++) {
+      events.push({ type: 'assistant', message: { role: 'assistant', content: [
+        { type: 'tool_use', id: `t${k}`, name: 'Read', input: { description: `read ${k}` } }] } });
+      events.push({ type: 'user', message: { role: 'user', content: [
+        { type: 'tool_result', tool_use_id: `t${k}`, content: 'ok', is_error: false }] } });
+    }
+    events.push({ type: 'assistant', message: { role: 'assistant', content: [
+      { type: 'tool_use', id: 'ttest', name: 'Bash', input: { command: 'npm test', description: 'run tests' } }] } });
+    events.push({ type: 'user', message: { role: 'user', content: [
+      { type: 'tool_result', tool_use_id: 'ttest', content: 'FAILED: 1 test failed', is_error: true }] } });
+    events.push({ type: 'result', subtype: 'success', result: 'All acceptance criteria verified.' });
+
+    writeLog(tmp, slug, events);
+    const prdPath = writePrd(tmp, slug, '# Genuine failure still flags');
+    const verdict = await verifyRun({ runDir: tmp, prdPath, queueEntry: { slug, status: 'running' }, allJobs: [], committedDuringRun: true });
+    assert.equal(verdict.verdict, 'transcript_errors', `genuine failure must still flag, got ${verdict.verdict}: ${verdict.reason}`);
+  } finally { rmdir(tmp); }
+});

package/src/main/__tests__/scheduler-already-satisfied-on-main.test.cjs

@@ -0,0 +1,105 @@
+/**
+ * scheduler-already-satisfied-on-main.test.cjs — PRD 1136.
+ *
+ * Two live rows (1133-reaper-must-verify-integration-before-completed,
+ * 1134-land-stranded-sm-job-branches) were false-negatived on 2026-09-06:
+ * their work had already landed on main before their runs dispatched, so
+ * each run exited 0, made no commit, and left a clean tree — the exact
+ * 'silent_no_op' shape commitGuardVerdict parks as needs_review ("finish
+ * protocol incomplete"). Both then auto-minted a redundant `-fix-` child
+ * queued to re-do already-shipped work.
+ *
+ * This exercises the full finalize decision chain — commitGuardVerdict
+ * (unchanged) feeding resolveCommitGuardOutcome (new) — entirely at the
+ * pure-function level, per standards.md's TDD guidance and the PRD's own
+ * implementation note to prefer a pure isAlreadySatisfiedOnMain-style helper
+ * over driving the whole spawnJob pipeline.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-already-satisfied-on-main.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { commitGuardVerdict, selectAutoFixTargets } = require('../scheduler.cjs');
+const { resolveCommitGuardOutcome, isAlreadySatisfiedOnMain } = require('../lib/reaperHelpers.cjs');
+
+const noSiblingOnDisk = () => false;
+
+// AC 1: exit 0 / no commit / clean tree, with a commit on main newer than
+// queuedAt touching the PRD's declared paths → completed, naming the sha.
+test('silent_no_op + a satisfying commit on main → completed-shaped verdict naming the sha, not needs_review', () => {
+  const guardVerdict = commitGuardVerdict({
+    newlyDirty: [],
+    siblingRunning: false,
+    jobSelfCommitted: false,
+    legitimateNoOp: false,
+    isFixPlanJob: false,
+    verifyResult: null,
+  });
+  expect(guardVerdict.verdict).toBe('silent_no_op'); // sanity: this is the shape 1133/1134 hit
+
+  const outcome = resolveCommitGuardOutcome(guardVerdict, ['5de4134abc123']);
+  expect(outcome.verdict).toBe('already_satisfied_on_main');
+  expect(outcome.verdict).not.toBe('needs_review');
+  expect(outcome.satisfyingSha).toBe('5de4134abc123');
+  expect(outcome.reason).toMatch(/5de4134abc123/);
+});
+
+// AC 2: the inverse — same clean-tree/no-commit shape, but NO commit on main
+// satisfies it → still parks as the existing 'finish protocol incomplete'
+// verdict. The gate must not be weakened into always-passing.
+test('silent_no_op + NO satisfying commit on main → unchanged silent_no_op verdict, still parks needs_review', () => {
+  const guardVerdict = commitGuardVerdict({
+    newlyDirty: [],
+    siblingRunning: false,
+    jobSelfCommitted: false,
+    legitimateNoOp: false,
+    isFixPlanJob: false,
+    verifyResult: null,
+  });
+
+  const outcome = resolveCommitGuardOutcome(guardVerdict, []);
+  expect(outcome).toBe(guardVerdict); // untouched — same object, not just same shape
+  expect(outcome.verdict).toBe('silent_no_op');
+  expect(outcome.downgradeTo).toBe('needs_review');
+  expect(outcome.reason).toMatch(/finish protocol incomplete/);
+});
+
+test('resolveCommitGuardOutcome never touches the uncommitted_changes shape, satisfied or not', () => {
+  const guardVerdict = commitGuardVerdict({
+    newlyDirty: ['src/main/someFeature.cjs'],
+    siblingRunning: false,
+    jobSelfCommitted: false,
+    legitimateNoOp: false,
+    verifyResult: null,
+  });
+  expect(guardVerdict.verdict).toBe('uncommitted_changes');
+
+  const outcome = resolveCommitGuardOutcome(guardVerdict, ['5de4134abc123']);
+  expect(outcome).toBe(guardVerdict);
+  expect(outcome.verdict).toBe('uncommitted_changes');
+});
+
+test('resolveCommitGuardOutcome: null guardVerdict (no violation) passes through as null', () => {
+  expect(resolveCommitGuardOutcome(null, ['5de4134'])).toBeNull();
+});
+
+// AC 3: a job terminalised via the already-satisfied path never becomes a
+// fix-plan target — selectAutoFixTargets only ever considers needs_review
+// rows, and the already-satisfied path never produces one.
+test('a job whose status is completed (the already-satisfied outcome) is never selected for an auto-fix child', () => {
+  const jobs = [{
+    slug: '1133-reaper-must-verify-integration-before-completed',
+    status: 'completed',
+    runId: '2026-09-06T13-03-00-000Z',
+    verifierVerdict: 'already_satisfied_on_main',
+  }];
+  const targets = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  expect(targets).toEqual([]);
+});
+
+test('isAlreadySatisfiedOnMain picks the newest (first) satisfying commit when several land', () => {
+  const verdict = isAlreadySatisfiedOnMain(['newest111', 'older222']);
+  expect(verdict.sha).toBe('newest111');
+});

package/src/main/__tests__/scheduler-blocked-by-foreign-wip.test.cjs

@@ -0,0 +1,107 @@
+/**
+ * scheduler-blocked-by-foreign-wip.test.cjs — validateForeignWipBlockClaim
+ * (the manifest-membership check that stops an executor from laundering a
+ * real regression into a BLOCKED_BY_FOREIGN_WIP verdict) and
+ * requeueForeignWipBlockedJobs (reconcile()'s auto-clear-and-resume pass).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-blocked-by-foreign-wip.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const {
+  validateForeignWipBlockClaim,
+  requeueForeignWipBlockedJobs,
+  FOREIGN_WIP_BLOCK_STREAK_LIMIT,
+} = require('../scheduler.cjs');
+
+// ─── validateForeignWipBlockClaim ──────────────────────────────────────────
+
+test('validateForeignWipBlockClaim: ok when every claimed path is in preRunDirtyPaths', () => {
+  const job = { preRunDirtyPaths: ['src/a.ts', 'src/b.ts'] };
+  const v = validateForeignWipBlockClaim(['src/a.ts'], job);
+  expect(v.ok).toBe(true);
+  expect(v.validPaths).toEqual(['src/a.ts']);
+  expect(v.invalidPaths).toEqual([]);
+});
+
+test('validateForeignWipBlockClaim: ok when every claimed path is in carriedPaths', () => {
+  const job = { carriedPaths: ['config/settings.json'] };
+  const v = validateForeignWipBlockClaim(['config/settings.json'], job);
+  expect(v.ok).toBe(true);
+  expect(v.validPaths).toEqual(['config/settings.json']);
+});
+
+test('validateForeignWipBlockClaim: rejects an unlisted path — the launder-a-regression case', () => {
+  // The job's real, disclosed foreign-WIP manifest never mentioned this path
+  // — an executor naming it anyway must not get away with claiming a block.
+  const job = { preRunDirtyPaths: ['src/a.ts'] };
+  const v = validateForeignWipBlockClaim(['src/a.ts', 'src/my-own-broken-file.ts'], job);
+  expect(v.ok).toBe(false);
+  expect(v.validPaths).toEqual(['src/a.ts']);
+  expect(v.invalidPaths).toEqual(['src/my-own-broken-file.ts']);
+});
+
+test('validateForeignWipBlockClaim: rejects a claim naming ONLY an unlisted path', () => {
+  const job = { preRunDirtyPaths: ['src/a.ts'] };
+  const v = validateForeignWipBlockClaim(['src/totally-unrelated.ts'], job);
+  expect(v.ok).toBe(false);
+  expect(v.invalidPaths).toEqual(['src/totally-unrelated.ts']);
+});
+
+test('validateForeignWipBlockClaim: rejects an empty claim (no evidence at all)', () => {
+  const job = { preRunDirtyPaths: ['src/a.ts'] };
+  expect(validateForeignWipBlockClaim([], job).ok).toBe(false);
+  expect(validateForeignWipBlockClaim(null, job).ok).toBe(false);
+});
+
+test('validateForeignWipBlockClaim: rejects against an empty/missing manifest', () => {
+  expect(validateForeignWipBlockClaim(['src/a.ts'], {}).ok).toBe(false);
+  expect(validateForeignWipBlockClaim(['src/a.ts'], null).ok).toBe(false);
+});
+
+// ─── requeueForeignWipBlockedJobs ──────────────────────────────────────────
+
+test('requeueForeignWipBlockedJobs: promotes skipped/blocked job to pending once its paths are clean', async () => {
+  const job = {
+    slug: '10-foo', status: 'skipped', cwd: '/repo', blockedByForeignWip: true,
+    foreignWipBlockedPaths: ['src/a.ts'], statusHistory: [],
+  };
+  await requeueForeignWipBlockedJobs([job], { getDirtyPaths: async () => [] });
+  expect(job.status).toBe('pending');
+  expect(job.blockedByForeignWip).toBeUndefined();
+  expect(job.foreignWipBlockedPaths).toBeUndefined();
+});
+
+test('requeueForeignWipBlockedJobs: leaves the job parked while any blocked path is still dirty', async () => {
+  const job = {
+    slug: '10-foo', status: 'skipped', cwd: '/repo', blockedByForeignWip: true,
+    foreignWipBlockedPaths: ['src/a.ts', 'src/b.ts'], statusHistory: [],
+  };
+  await requeueForeignWipBlockedJobs([job], { getDirtyPaths: async () => ['src/a.ts'] });
+  expect(job.status).toBe('skipped');
+  expect(job.blockedByForeignWip).toBe(true);
+});
+
+test('requeueForeignWipBlockedJobs: ignores jobs not in the blocked-skipped shape', async () => {
+  const skippedNotBlocked = { slug: '1', status: 'skipped', cwd: '/repo', statusHistory: [] };
+  const runningBlocked = { slug: '2', status: 'running', cwd: '/repo', blockedByForeignWip: true, foreignWipBlockedPaths: ['x'], statusHistory: [] };
+  const getDirtyPaths = async () => [];
+  await requeueForeignWipBlockedJobs([skippedNotBlocked, runningBlocked], { getDirtyPaths });
+  expect(skippedNotBlocked.status).toBe('skipped');
+  expect(runningBlocked.status).toBe('running');
+});
+
+test('requeueForeignWipBlockedJobs: leaves the row alone when the cwd is not a git repo (getDirtyPaths → null)', async () => {
+  const job = {
+    slug: '10-foo', status: 'skipped', cwd: '/not-a-repo', blockedByForeignWip: true,
+    foreignWipBlockedPaths: ['src/a.ts'], statusHistory: [],
+  };
+  await requeueForeignWipBlockedJobs([job], { getDirtyPaths: async () => null });
+  expect(job.status).toBe('skipped');
+});
+
+test('FOREIGN_WIP_BLOCK_STREAK_LIMIT is 3', () => {
+  expect(FOREIGN_WIP_BLOCK_STREAK_LIMIT).toBe(3);
+});

package/src/main/__tests__/scheduler-finalize-dispatch-guards.test.cjs

@@ -0,0 +1,229 @@
+/**
+ * scheduler-finalize-dispatch-guards.test.cjs — regression cover for the
+ * 2026-09-06 incident: PRD 1133 (reaper integration check) shipped correctly
+ * in commit 5de4134, but its finalize mutate's silent early-return dropped
+ * three subsequent no-op re-verifications of the same already-shipped slug
+ * with no audit trail, leaving the row stuck 'pending' forever and causing
+ * the dispatcher to re-fire it three more times.
+ *
+ * Covers the three pure decision helpers extracted for this fix:
+ *  - evaluateFinalizeDrop: never silently discard a finalize (row missing,
+ *    or row moved off 'running' by a concurrent cancel) — always says so,
+ *    and still lets a genuinely-landed commit be stamped as a durable fact.
+ *  - evaluateDispatchSidecarReconcile: refuse to re-dispatch a pending row
+ *    whose newest run sidecar already shows a completed-equivalent outcome
+ *    for THIS queueing episode.
+ *  - isQueueRowRegression: detect (never repair) a running->pending change
+ *    whose statusHistory got shorter — evidence of lost state, not a real
+ *    transition.
+ *
+ * HOME is overridden to a tmp dir BEFORE requiring scheduler.cjs, matching
+ * scheduler-reap-dead-running-jobs.test.cjs's pattern — every path this
+ * module touches is baked into a top-level const from os.homedir() at
+ * require time.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-finalize-dispatch-guards.test.cjs
+ */
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'scheduler-finalize-dispatch-guards-test-'));
+process.env.HOME = tmpHome;
+
+const {
+  evaluateFinalizeDrop,
+  evaluateDispatchSidecarReconcile,
+  isQueueRowRegression,
+} = require('../scheduler.cjs');
+
+describe('evaluateFinalizeDrop', () => {
+  it('drops loudly (row-missing) with nothing to stamp when the row vanished from s.jobs', () => {
+    const decision = evaluateFinalizeDrop({
+      rowExists: false,
+      rowStatus: null,
+      rowRunId: null,
+      rowLandedCommit: null,
+      runId: 'run-2',
+      landedCommit: 'deadbeef',
+    });
+    assert.equal(decision.drop, true);
+    assert.equal(decision.reason, 'row-missing');
+    assert.equal(decision.stampLandedCommit, null);
+  });
+
+  it('drops the status change (row-not-running) but stamps landedCommit when this run owns the row', () => {
+    const decision = evaluateFinalizeDrop({
+      rowExists: true,
+      rowStatus: 'failed', // e.g. remote.cancelJob already finalized it (PRD 1024)
+      rowRunId: 'run-2',
+      rowLandedCommit: null,
+      runId: 'run-2',
+      landedCommit: 'deadbeef',
+    });
+    assert.equal(decision.drop, true);
+    assert.equal(decision.reason, 'row-not-running');
+    assert.equal(decision.stampLandedCommit, 'deadbeef');
+  });
+
+  it('stamps landedCommit even when the row carries a different runId, as long as it has none of its own', () => {
+    const decision = evaluateFinalizeDrop({
+      rowExists: true,
+      rowStatus: 'pending',
+      rowRunId: 'some-other-run',
+      rowLandedCommit: null,
+      runId: 'run-2',
+      landedCommit: 'deadbeef',
+    });
+    assert.equal(decision.drop, true);
+    assert.equal(decision.stampLandedCommit, 'deadbeef');
+  });
+
+  it('never overwrites a row that already carries its own newer landedCommit from a different run', () => {
+    const decision = evaluateFinalizeDrop({
+      rowExists: true,
+      rowStatus: 'failed',
+      rowRunId: 'some-other-run',
+      rowLandedCommit: 'already-there',
+      runId: 'run-2',
+      landedCommit: 'deadbeef',
+    });
+    assert.equal(decision.drop, true);
+    assert.equal(decision.stampLandedCommit, null);
+  });
+
+  it('never re-legalizes a cancelled (failed) row back to completed — the PRD-1024 protection', () => {
+    // The finalize call site never even reaches transitionJob for a dropped
+    // finalize; this test documents the contract evaluateFinalizeDrop enforces:
+    // drop:true means the caller MUST NOT change job.status.
+    const decision = evaluateFinalizeDrop({
+      rowExists: true,
+      rowStatus: 'failed',
+      rowRunId: 'run-2',
+      rowLandedCommit: null,
+      runId: 'run-2',
+      landedCommit: 'deadbeef',
+    });
+    assert.equal(decision.drop, true);
+  });
+
+  it('does not drop when the row is still running — the normal finalize path', () => {
+    const decision = evaluateFinalizeDrop({
+      rowExists: true,
+      rowStatus: 'running',
+      rowRunId: 'run-2',
+      rowLandedCommit: null,
+      runId: 'run-2',
+      landedCommit: 'deadbeef',
+    });
+    assert.equal(decision.drop, false);
+    assert.equal(decision.stampLandedCommit, null);
+  });
+});
+
+describe('evaluateDispatchSidecarReconcile', () => {
+  const baseRow = {
+    rowStatus: 'pending',
+    rowRunId: null,
+    statusHistory: [
+      { from: 'running', to: 'pending', at: '2026-09-06T19:30:00.000Z' },
+    ],
+    queuedAt: '2026-09-06T17:02:07.815Z',
+  };
+
+  it('skips dispatch when a prior run of this slug already completed after the last pending transition', () => {
+    const decision = evaluateDispatchSidecarReconcile({
+      ...baseRow,
+      outcome: { status: 'completed', runId: '2026-09-06T19-26-54-681Z', finishedAt: '2026-09-06T19:35:00.000Z' },
+    });
+    assert.equal(decision.skip, true);
+    assert.equal(decision.runId, '2026-09-06T19-26-54-681Z');
+  });
+
+  it('proceeds with dispatch when a deliberate human re-queue postdates the earlier completion', () => {
+    // The re-queue's own pending transition (19:30) is AFTER the completed
+    // sidecar's finishedAt (18:00) — an OLDER episode's completion, not this one.
+    const decision = evaluateDispatchSidecarReconcile({
+      ...baseRow,
+      outcome: { status: 'completed', runId: 'old-run', finishedAt: '2026-09-06T18:00:00.000Z' },
+    });
+    assert.equal(decision.skip, false);
+  });
+
+  it('proceeds with dispatch when there is no sidecar at all (guard is a no-op)', () => {
+    const decision = evaluateDispatchSidecarReconcile({ ...baseRow, outcome: null });
+    assert.equal(decision.skip, false);
+  });
+
+  it('proceeds with dispatch when the sidecar belongs to this row\'s own current runId', () => {
+    const decision = evaluateDispatchSidecarReconcile({
+      ...baseRow,
+      rowRunId: 'run-x',
+      outcome: { status: 'completed', runId: 'run-x', finishedAt: '2026-09-06T19:35:00.000Z' },
+    });
+    assert.equal(decision.skip, false);
+  });
+
+  it('proceeds with dispatch when the row is not pending (e.g. needs_review resume-recovery)', () => {
+    const decision = evaluateDispatchSidecarReconcile({
+      ...baseRow,
+      rowStatus: 'needs_review',
+      outcome: { status: 'completed', runId: 'some-run', finishedAt: '2026-09-06T19:35:00.000Z' },
+    });
+    assert.equal(decision.skip, false);
+  });
+
+  it('proceeds with dispatch when the newest sidecar reports a failed (not completed-equivalent) outcome', () => {
+    const decision = evaluateDispatchSidecarReconcile({
+      ...baseRow,
+      outcome: { status: 'failed', runId: 'some-run', finishedAt: '2026-09-06T19:35:00.000Z' },
+    });
+    assert.equal(decision.skip, false);
+  });
+
+  it('falls back to queuedAt when the row has never been reset (no pending statusHistory entry)', () => {
+    const decision = evaluateDispatchSidecarReconcile({
+      rowStatus: 'pending',
+      rowRunId: null,
+      statusHistory: [],
+      queuedAt: '2026-09-06T17:02:07.815Z',
+      outcome: { status: 'completed', runId: 'some-run', finishedAt: '2026-09-06T19:35:00.000Z' },
+    });
+    assert.equal(decision.skip, true);
+  });
+});
+
+describe('isQueueRowRegression', () => {
+  it('flags a running->pending change whose statusHistory got shorter', () => {
+    assert.equal(
+      isQueueRowRegression({ statusBefore: 'running', statusAfter: 'pending', historyLenBefore: 5, historyLenAfter: 3 }),
+      true,
+    );
+  });
+
+  it('does not flag a running->pending change with a normal appended (equal or longer) history', () => {
+    assert.equal(
+      isQueueRowRegression({ statusBefore: 'running', statusAfter: 'pending', historyLenBefore: 5, historyLenAfter: 6 }),
+      false,
+    );
+    assert.equal(
+      isQueueRowRegression({ statusBefore: 'running', statusAfter: 'pending', historyLenBefore: 20, historyLenAfter: 20 }),
+      false,
+    );
+  });
+
+  it('does not flag a shortened history on transitions other than running->pending', () => {
+    assert.equal(
+      isQueueRowRegression({ statusBefore: 'pending', statusAfter: 'completed', historyLenBefore: 5, historyLenAfter: 3 }),
+      false,
+    );
+    assert.equal(
+      isQueueRowRegression({ statusBefore: 'running', statusAfter: 'completed', historyLenBefore: 5, historyLenAfter: 3 }),
+      false,
+    );
+  });
+});