claude-code-session-manager 0.76.0 → 0.77.0

package/src/main/__tests__/scheduler-quiet-machine-lease.test.cjs

@@ -0,0 +1,222 @@
+/**
+ * scheduler-quiet-machine-lease.test.cjs — PRD 1107: the exclusive
+ * quiet-machine lease must be released on EVERY spawnJob exit path,
+ * including a killed job (SIGKILL/exit 137), not just a clean exit — the
+ * same finally block that already releases the sessionSlots token. Drives
+ * spawnJob end-to-end against a real git fixture repo with a stub `claude`
+ * binary that exits 137 mid-run (same pattern as
+ * scheduler-inplace-salvage.test.cjs), then asserts:
+ *   1. the lease is released once the job settles, and
+ *   2. an ordinary pending job — held behind the lease while it was held —
+ *      is now eligible to dispatch.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-quiet-machine-lease.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+let tmpHome;
+let originalHome;
+let originalDisable;
+let spawnJob;
+let quietMachineLease;
+let pickNextBatch;
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init', '-q'], dir);
+  git(['config', 'user.email', 'test@example.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), 'hello\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
+
+// See scheduler-inplace-salvage.test.cjs's identical helper: readQueue()'s
+// per-project discovery walks ~/.claude/projects/*/*.jsonl transcripts for a
+// `cwd` field to find known project queue.json shards.
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function writeProjectQueue(cwd, jobs) {
+  const stateDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs }, null, 2));
+  return path.join(stateDir, 'queue.json');
+}
+
+// Stub `claude` binary that exits 137 (SIGKILL) with no result:success event,
+// simulating a leased job killed mid-run before it could finish and release
+// naturally through its own clean-exit path. Dirties the tree first (like
+// scheduler-inplace-salvage.test.cjs's stub) so the scheduler classifies this
+// as a genuine kill-with-partial-work, not an auto-retryable transient blip
+// with no evidence of real execution.
+function writeKilledClaudeStub() {
+  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-quiet-killed-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
+  const body = `
+    const fs = require('fs');
+    const path = require('path');
+    fs.writeFileSync(path.join(process.cwd(), 'job-output.txt'), 'work in progress when killed\\n', 'utf8');
+    process.exit(137);
+  `;
+  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
+  return stubPath;
+}
+
+let reapDeadRunningJobs;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-quiet-lease-'));
+  process.env.HOME = tmpHome;
+  originalDisable = process.env.SM_JOB_WORKTREE_DISABLE;
+  process.env.SM_JOB_WORKTREE_DISABLE = '1';
+  ({ spawnJob, reapDeadRunningJobs } = require('../scheduler.cjs'));
+  ({ pickNextBatch } = require('../lib/schedulerBatch.cjs'));
+  quietMachineLease = require('../lib/quietMachineLease.cjs');
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  if (originalDisable === undefined) delete process.env.SM_JOB_WORKTREE_DISABLE;
+  else process.env.SM_JOB_WORKTREE_DISABLE = originalDisable;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  delete process.env.SM_CLAUDE_BIN;
+  quietMachineLease.__resetForTests();
+});
+
+test('a killed quietMachine job releases the exclusive lease, and an ordinary job dispatches on the next pick', async () => {
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-quiet-lease-project-'));
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  const quietSlug = `1107-test-quiet-killed-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const ordinarySlug = `1107-test-ordinary-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, `${quietSlug}.md`), '---\nquietMachine: true\n---\nMeasure timing without contention, then get killed.', 'utf8');
+  fs.writeFileSync(path.join(prdsDir, `${ordinarySlug}.md`), 'An ordinary PRD queued behind the quiet job.', 'utf8');
+
+  const queuePath = writeProjectQueue(projectCwd, [
+    { slug: quietSlug, status: 'pending', cwd: projectCwd, quietMachine: true },
+    { slug: ordinarySlug, status: 'pending', cwd: projectCwd, createdAt: new Date().toISOString() },
+  ]);
+
+  process.env.SM_CLAUDE_BIN = writeKilledClaudeStub();
+
+  const runId = `run-${quietSlug}`;
+  const runDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId);
+  fs.mkdirSync(runDir, { recursive: true });
+
+  try {
+    // Before spawnJob ever runs, demonstrate that a held lease (as it would
+    // be while quietSlug is genuinely running) blocks EVERY dispatch,
+    // including the ordinary sibling job sitting right behind it in the same
+    // project. Uses a standalone dummy holder so it doesn't interact with
+    // spawnJob's own acquire/release of the real lease below.
+    expect(quietMachineLease.acquire('dummy-holder-simulating-in-flight-run')).toBe(true);
+    const heldPick = pickNextBatch(
+      [
+        { slug: quietSlug, status: 'running', cwd: projectCwd, quietMachine: true },
+        { slug: ordinarySlug, status: 'pending', cwd: projectCwd, createdAt: new Date().toISOString() },
+      ],
+      new Set([quietSlug]),
+      5,
+      { leaseHeld: quietMachineLease.isHeld(), machineInUse: 1, now: Date.now() },
+    );
+    expect(heldPick.batch).toEqual([]);
+    quietMachineLease.release('dummy-holder-simulating-in-flight-run');
+
+    // Now the real thing: spawnJob acquires the lease itself for quietSlug,
+    // runs the killed stub, and must release it on this exit path.
+    await spawnJob({ slug: quietSlug, cwd: projectCwd, quietMachine: true }, runId, runDir, projectCwd);
+
+    const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+    const quietRow = jobs.find((j) => j.slug === quietSlug);
+    expect(quietRow).toBeTruthy();
+    expect(quietRow.exitCode).toBe(137);
+    expect(quietRow.quietMachine).toBe(true);
+
+    // The lease was released on this killed-job exit path — spawnJob's own
+    // finally block, the same one that releases the sessionSlots token.
+    expect(quietMachineLease.isHeld()).toBe(false);
+
+    // With the lease free again, the ordinary sibling job is now eligible.
+    const nextPick = pickNextBatch(
+      [
+        { slug: quietSlug, status: 'failed', cwd: projectCwd, quietMachine: true },
+        { slug: ordinarySlug, status: 'pending', cwd: projectCwd, createdAt: new Date().toISOString() },
+      ],
+      new Set(),
+      5,
+      { leaseHeld: quietMachineLease.isHeld(), machineInUse: 0, now: Date.now() },
+    );
+    expect(nextPick.batch.map((j) => j.slug)).toEqual([ordinarySlug]);
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+}, 30_000);
+
+test('reapDeadRunningJobs releases a quietMachine job\'s lease too — the process vanished without spawnJob\'s own finally ever running', async () => {
+  // This reaper exists exactly for the case spawnJob's own finally never
+  // runs (the process dies without the completion mutate() finishing) — see
+  // reapDeadRunningJobs's header comment. A quietMachine row reaped through
+  // THIS path must release the lease itself, or it stays wedged forever.
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-quiet-lease-reap-project-'));
+  registerActiveProject(projectCwd);
+
+  const slug = `1107-test-reaped-quiet-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug,
+      status: 'running',
+      cwd: projectCwd,
+      quietMachine: true,
+      runId: `run-${slug}`,
+      runtime: { pid: 999999 }, // guaranteed-dead pid (see reaperHelpers tests)
+    },
+  ]);
+  const runDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', `run-${slug}`);
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(runDir, `${slug}.log`),
+    '{"type":"result","subtype":"success","result":"done","is_error":false}\n',
+  );
+
+  // Simulate the lease as held by this row, exactly as it would be if
+  // spawnJob's own acquire ran but its finally never got the chance to.
+  expect(quietMachineLease.acquire(slug)).toBe(true);
+
+  try {
+    await reapDeadRunningJobs();
+
+    const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+    const row = jobs.find((j) => j.slug === slug);
+    expect(row).toBeTruthy();
+    expect(row.status).toBe('completed');
+
+    // The lease must be released here too, not just in spawnJob's finally.
+    expect(quietMachineLease.isHeld()).toBe(false);
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});

package/src/main/__tests__/scheduler-reap-dead-running-jobs.test.cjs

@@ -32,12 +32,34 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 
 const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'reap-dead-running-jobs-test-'));
 process.env.HOME = tmpHome;
 
 const { reapDeadRunningJobs, PIDLESS_SPAWN_GRACE_MS } = require('../scheduler.cjs');
 const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+// queueStore's cwd discovery is cached for 30s (queueStore.cjs's CACHE_MS) —
+// a project registered by THIS test after an earlier test already populated
+// that cache (and didn't itself bust it, e.g. because it found nothing
+// reapable and returned before ever calling writeQueue) would otherwise be
+// invisible to readQueue() for the rest of that window. Bust explicitly
+// after registering a new project so each test sees its own fixture.
+const { bustCwdCache } = require('../lib/queueStore.cjs');
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init', '-q'], dir);
+  git(['config', 'user.email', 'test@example.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), 'hello\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
 
 function registerActiveProject(cwd) {
   const projectsDir = path.join(tmpHome, '.claude', 'projects');
@@ -86,6 +108,7 @@ test('reapDeadRunningJobs reconciles a queue.json row stuck at status:running wi
   assert.equal(jobs[0].status, 'completed', 'job must be reconciled from disk state, not skipped via the runningSet gate');
   assert.equal(jobs[0].exitCode, 0);
   assert.equal(jobs[0].runtime, undefined);
+  assert.equal(jobs[0].gateOutcome, 'passed', 'a success result event maps to gateOutcome:passed');
 });
 
 test('reapDeadRunningJobs reaps a pidless row older than PIDLESS_SPAWN_GRACE_MS with an empty run dir as failed, not completed, and audits it', async () => {
@@ -117,6 +140,7 @@ test('reapDeadRunningJobs reaps a pidless row older than PIDLESS_SPAWN_GRACE_MS
   assert.equal(jobs[0].status, 'failed', 'an empty run dir must never be reaped as completed');
   assert.match(jobs[0].error, /no runtime\.pid recorded/);
   assert.equal(jobs[0].runtime, undefined);
+  assert.equal(jobs[0].gateOutcome, 'never_ran', 'a pidless reap means the gate never had a chance to run');
 
   const auditText = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').slice(auditSizeBefore);
   const auditLines = auditText.trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
@@ -160,3 +184,126 @@ test('reapDeadRunningJobs is a no-op when no job is actually running in queue.js
   assert.equal(jobs.length, 1);
   assert.equal(jobs[0].status, 'completed');
 });
+
+test('reapDeadRunningJobs salvages a delta-scoped in-place patch (PRD 1098) when the row carries a persisted guardBaseline', async () => {
+  const projectCwd = path.join(tmpHome, 'e-project');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  // Pre-existing WIP present at the recorded pre-run baseline — must never
+  // appear in the salvaged patch.
+  fs.writeFileSync(path.join(projectCwd, 'human-wip.txt'), 'human wip\n', 'utf8');
+
+  const runId = 'run-vanished-inplace';
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug: 'vanished-inplace',
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 }, // guaranteed-dead pid
+      // Includes the untracked session-manager-operations/ dir itself (git
+      // status --porcelain reports an untracked DIRECTORY, not the file
+      // inside it) — writeProjectQueue below writes queue.json INSIDE this
+      // same git repo, so it's part of the true pre-run baseline exactly
+      // like human-wip.txt.
+      guardBaseline: ['human-wip.txt', 'session-manager-operations/'],
+    },
+  ]);
+  const runDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId);
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(path.join(runDir, 'vanished-inplace.log'), '{"type":"result","subtype":"success","result":"done","is_error":false}\n');
+
+  // The job's own delta, dirtied before its process vanished.
+  fs.writeFileSync(path.join(projectCwd, 'README.md'), 'hello\nedited by job\n', 'utf8');
+  fs.writeFileSync(path.join(projectCwd, 'job-output.txt'), 'job work\n', 'utf8');
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === 'vanished-inplace');
+  assert.equal(row.status, 'completed');
+  assert.ok(row.salvagePatch, 'a salvage patch must be recorded on the row');
+  assert.ok(fs.existsSync(row.salvagePatch));
+  const patch = fs.readFileSync(row.salvagePatch, 'utf8');
+  assert.match(patch, /README\.md/);
+  assert.match(patch, /edited by job/);
+  assert.match(patch, /job-output\.txt/);
+  assert.doesNotMatch(patch, /human wip/, 'baseline WIP must never leak into the salvaged patch');
+  assert.equal(row.leftoverCount, 2, 'the reaper must attribute the job\'s own delta (README.md + job-output.txt), never the baseline WIP');
+  assert.deepEqual(new Set(row.leftoverPaths), new Set(['README.md', 'job-output.txt']));
+});
+
+test('reapDeadRunningJobs: a failed reap with a persisted guardBaseline names the leftover count in its transition reason and error', async () => {
+  const projectCwd = path.join(tmpHome, 'g-project');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  const runId = 'run-vanished-failed';
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug: 'vanished-failed',
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 },
+      // Includes the untracked session-manager-operations/ dir itself — see
+      // the comment on the salvage test above for why.
+      guardBaseline: ['session-manager-operations/'],
+    },
+  ]);
+  // Empty run dir → classifyRunOutcome finds no result event → 'no_result' → failed.
+  fs.mkdirSync(path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId), { recursive: true });
+
+  fs.writeFileSync(path.join(projectCwd, 'partial-work.txt'), 'unfinished\n', 'utf8');
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === 'vanished-failed');
+  assert.equal(row.status, 'failed');
+  assert.equal(row.leftoverCount, 1);
+  assert.deepEqual(row.leftoverPaths, ['partial-work.txt']);
+  assert.match(row.error, /left 1 files uncommitted/, 'the leftover count must be visible in the error string, not just a separate field');
+  const lastTransition = row.statusHistory[row.statusHistory.length - 1];
+  assert.match(lastTransition.reason, /left 1 files uncommitted/);
+});
+
+test('reapDeadRunningJobs skips in-place salvage (no whole-tree dump) when the row has no persisted guardBaseline', async () => {
+  const projectCwd = path.join(tmpHome, 'f-project');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  fs.writeFileSync(path.join(projectCwd, 'human-wip.txt'), 'human wip\n', 'utf8');
+  fs.writeFileSync(path.join(projectCwd, 'README.md'), 'hello\nedited by job\n', 'utf8');
+
+  const runId = 'run-vanished-no-baseline';
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug: 'vanished-no-baseline',
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 },
+      // No guardBaseline field — simulates a row whose owning process
+      // vanished before spawnJob's dispatch-time persist-mutate ever ran, so
+      // there's no safe way to distinguish this job's own dirt from the
+      // human's pre-existing WIP above.
+    },
+  ]);
+  const runDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId);
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(path.join(runDir, 'vanished-no-baseline.log'), '{"type":"result","subtype":"success","result":"done","is_error":false}\n');
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === 'vanished-no-baseline');
+  assert.equal(row.status, 'completed');
+  assert.equal(row.salvagePatch, undefined, 'must skip salvage entirely rather than ever dumping the whole tree');
+  assert.equal(row.leftoverPaths, undefined, 'no baseline means no safe attribution — must not guess');
+  assert.equal(row.leftoverCount, undefined);
+});

package/src/main/__tests__/scheduler-shared-tree-guard.test.cjs

@@ -0,0 +1,212 @@
+/**
+ * scheduler-shared-tree-guard.test.cjs — the shared-tree stash guard added
+ * for the 2026-09-01 social-signals-trader incident: a headless PRD executor
+ * ran a blanket `git stash` in a working tree shared with a live trading
+ * service, silently reverting an uncommitted operator config edit with no
+ * error anywhere.
+ *
+ * evaluateSharedTreeGuard is the pure diff (no I/O); checkSharedTreeGuard is
+ * the orchestrator that also restores a single unambiguous stash, using the
+ * same module.exports spy pattern computeCommittedDuringRun/committedInWindow
+ * use so the underlying git calls never actually run.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-shared-tree-guard.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, vi, afterEach } from 'vitest';
+const scheduler = require('../scheduler.cjs');
+const { evaluateSharedTreeGuard, checkSharedTreeGuard } = scheduler;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+test('evaluateSharedTreeGuard: no-op when nothing changed', () => {
+  const result = evaluateSharedTreeGuard({
+    stashBefore: ['aaa stash@{0} WIP on main: aaa old'],
+    stashAfter: ['aaa stash@{0} WIP on main: aaa old'],
+    dirtyBefore: ['data/spread_config.json'],
+    dirtyAfter: ['data/spread_config.json'],
+    pathsCommittedDuringRun: [],
+  });
+  expect(result.newStashes).toEqual([]);
+  expect(result.reverted).toEqual([]);
+});
+
+test('evaluateSharedTreeGuard: flags one new stash entry not present in the baseline', () => {
+  const result = evaluateSharedTreeGuard({
+    stashBefore: [],
+    stashAfter: ['bbb stash@{0} WIP on fix/x: bbb f5ae98f'],
+    dirtyBefore: [],
+    dirtyAfter: [],
+    pathsCommittedDuringRun: [],
+  });
+  expect(result.newStashes).toEqual([{ hash: 'bbb', ref: 'stash@{0}', subject: 'WIP on fix/x: bbb f5ae98f' }]);
+});
+
+test('evaluateSharedTreeGuard: two new stash entries both surface (caller decides ambiguity, not this function)', () => {
+  const result = evaluateSharedTreeGuard({
+    stashBefore: [],
+    stashAfter: [
+      'bbb stash@{0} WIP on fix/x: bbb newest',
+      'ccc stash@{1} WIP on fix/x: ccc older',
+    ],
+    dirtyBefore: [],
+    dirtyAfter: [],
+    pathsCommittedDuringRun: [],
+  });
+  expect(result.newStashes).toHaveLength(2);
+  expect(result.newStashes.map((e) => e.ref)).toEqual(['stash@{0}', 'stash@{1}']);
+});
+
+test('evaluateSharedTreeGuard: baseline-dirty path clean after the run with no commit to explain it is flagged reverted', () => {
+  const result = evaluateSharedTreeGuard({
+    stashBefore: [],
+    stashAfter: [],
+    dirtyBefore: ['data/spread_config.json'],
+    dirtyAfter: [],
+    pathsCommittedDuringRun: [],
+  });
+  expect(result.reverted).toEqual(['data/spread_config.json']);
+});
+
+test('evaluateSharedTreeGuard: baseline-dirty path clean after the run but touched by a commit made during the run is NOT flagged', () => {
+  const result = evaluateSharedTreeGuard({
+    stashBefore: [],
+    stashAfter: [],
+    dirtyBefore: ['src/foo.js'],
+    dirtyAfter: [],
+    pathsCommittedDuringRun: ['src/foo.js'],
+  });
+  expect(result.reverted).toEqual([]);
+});
+
+test('checkSharedTreeGuard: no-op when nothing changed returns null', async () => {
+  vi.spyOn(scheduler, 'stashList').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha1');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue([]);
+  const restoreSpy = vi.spyOn(scheduler, 'restoreSpecificStash');
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: [],
+    headBefore: 'sha1',
+    slug: 'job-1',
+  });
+  expect(result).toBeNull();
+  expect(restoreSpy).not.toHaveBeenCalled();
+});
+
+test('checkSharedTreeGuard: a single new stash is restored via apply+drop of that specific ref', async () => {
+  vi.spyOn(scheduler, 'stashList').mockResolvedValue(['newhash stash@{0} WIP on main: f5ae98f']);
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha1');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue([]);
+  const restoreSpy = vi.spyOn(scheduler, 'restoreSpecificStash').mockResolvedValue({ ok: true });
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: [],
+    headBefore: 'sha1',
+    slug: 'job-1',
+  });
+  expect(restoreSpy).toHaveBeenCalledWith('/repo', 'stash@{0}');
+  expect(result).toEqual({ restoredStash: 'stash@{0}' });
+});
+
+test('checkSharedTreeGuard: a baseline-dirty path stashed by the job and successfully restored is not ALSO flagged reverted', async () => {
+  vi.spyOn(scheduler, 'stashList').mockResolvedValue(['newhash stash@{0} WIP on main: f5ae98f']);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha1');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'restoreSpecificStash').mockResolvedValue({ ok: true });
+  // uncommittedChanges is queried AFTER the restore attempt in the fixed
+  // implementation — simulate the stashed file reappearing dirty once the
+  // apply+drop succeeds (this is the exact 2026-09-01 incident shape: an
+  // operator's pre-existing dirty file gets swept into the job's stash).
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue(['data/spread_config.json']);
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: ['data/spread_config.json'],
+    headBefore: 'sha1',
+    slug: 'job-1',
+  });
+  expect(result).toEqual({ restoredStash: 'stash@{0}' });
+});
+
+test('checkSharedTreeGuard: two new stashes are reported, not restored (ambiguous)', async () => {
+  vi.spyOn(scheduler, 'stashList').mockResolvedValue([
+    'aaa stash@{0} WIP on main: newest',
+    'bbb stash@{1} WIP on main: older',
+  ]);
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha1');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue([]);
+  const restoreSpy = vi.spyOn(scheduler, 'restoreSpecificStash');
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: [],
+    headBefore: 'sha1',
+    slug: 'job-1',
+  });
+  expect(restoreSpy).not.toHaveBeenCalled();
+  expect(result.ambiguousStashes).toEqual(['stash@{0}', 'stash@{1}']);
+  expect(result.restoredStash).toBeUndefined();
+});
+
+test('checkSharedTreeGuard: a baseline-dirty path reverted with no stash and no commit is flagged reverted', async () => {
+  vi.spyOn(scheduler, 'stashList').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha1');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue([]);
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: ['data/spread_config.json'],
+    headBefore: 'sha1',
+    slug: 'job-1',
+  });
+  expect(result).toEqual({ reverted: ['data/spread_config.json'] });
+});
+
+test('checkSharedTreeGuard: a failed restore is reported as restoreFailed, entry left in place', async () => {
+  vi.spyOn(scheduler, 'stashList').mockResolvedValue(['newhash stash@{0} WIP on main: f5ae98f']);
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha1');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'restoreSpecificStash').mockResolvedValue({ ok: false, error: 'conflict applying stash' });
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: [],
+    headBefore: 'sha1',
+    slug: 'job-1',
+  });
+  expect(result.restoreFailed).toMatch(/stash@\{0\}.*conflict applying stash/);
+});
+
+test('checkSharedTreeGuard never throws when the underlying git calls reject', async () => {
+  vi.spyOn(scheduler, 'stashList').mockRejectedValue(new Error('boom'));
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha1');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue([]);
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: [],
+    headBefore: 'sha1',
+    slug: 'job-1',
+  });
+  expect(result).toBeNull();
+});