@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.3

package/src/core/__tests__/runner-liveness.test.ts

@@ -0,0 +1,865 @@
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, spyOn } from "bun:test";
+
+import {
+  classifyStaleRunningStatus,
+  isProcessAlive,
+  reconcileInterruptedJob,
+  reconcileOrphanedCurrentJobs,
+  type StaleRunningInput,
+} from "../runner-liveness";
+import { readJobStatusResult, STATUS_FILENAME } from "../status-writer";
+import type { StatusSnapshot } from "../status-writer";
+
+function makeStatusSnapshot(overrides: Partial<StatusSnapshot> = {}): StatusSnapshot {
+  return {
+    id: "job-classifier",
+    state: "running",
+    current: "research",
+    currentStage: null,
+    lastUpdated: "2026-04-01T10:00:00.000Z",
+    tasks: {
+      research: { state: "running" },
+    },
+    files: { artifacts: [], logs: [], tmp: [] },
+    ...overrides,
+  };
+}
+
+const BASE_INPUT = {
+  pid: null,
+  pidAlive: false,
+  staleAfterMs: 30_000,
+} satisfies Omit<StaleRunningInput, "status" | "nowMs">;
+
+describe("classifyStaleRunningStatus", () => {
+  it("returns not_running when task-derived status is not running", () => {
+    const decision = classifyStaleRunningStatus({
+      ...BASE_INPUT,
+      status: makeStatusSnapshot({
+        state: "pending",
+        current: null,
+        tasks: { research: { state: "done" }, analysis: { state: "pending" } },
+      }),
+      nowMs: Date.parse("2026-04-01T10:01:00.000Z"),
+    });
+
+    expect(decision).toEqual({ stale: false, reason: "not_running" });
+  });
+
+  it("returns live_pid when task-derived status is running and the PID is alive", () => {
+    const decision = classifyStaleRunningStatus({
+      ...BASE_INPUT,
+      pid: 123,
+      pidAlive: true,
+      status: makeStatusSnapshot(),
+      nowMs: Date.parse("2026-04-01T10:01:00.000Z"),
+    });
+
+    expect(decision).toEqual({ stale: false, reason: "live_pid" });
+  });
+
+  it("returns fresh_status when running status is newer than the grace window", () => {
+    const decision = classifyStaleRunningStatus({
+      ...BASE_INPUT,
+      status: makeStatusSnapshot(),
+      nowMs: Date.parse("2026-04-01T10:00:10.000Z"),
+    });
+
+    expect(decision).toEqual({ stale: false, reason: "fresh_status" });
+  });
+
+  it("treats missing or unparseable lastUpdated with no live PID as stale", () => {
+    const decision = classifyStaleRunningStatus({
+      ...BASE_INPUT,
+      status: makeStatusSnapshot({ lastUpdated: "" }),
+      nowMs: Date.parse("2026-04-01T10:01:00.000Z"),
+    });
+
+    expect(decision).toMatchObject({ stale: true, ageMs: 0 });
+  });
+
+  it("returns stale when running status is old and no live runner exists", () => {
+    const decision = classifyStaleRunningStatus({
+      ...BASE_INPUT,
+      status: makeStatusSnapshot(),
+      nowMs: Date.parse("2026-04-01T10:01:00.000Z"),
+    });
+
+    expect(decision).toEqual({ stale: true, runningTaskId: "research", ageMs: 60_000 });
+  });
+
+  it("returns stale when age equals exactly the grace window (boundary)", () => {
+    const lastUpdated = "2026-04-01T10:00:00.000Z";
+    const nowMs = Date.parse(lastUpdated) + 30_000;
+    const decision = classifyStaleRunningStatus({
+      ...BASE_INPUT,
+      status: makeStatusSnapshot({ lastUpdated }),
+      nowMs,
+    });
+
+    expect(decision).toMatchObject({ stale: true, ageMs: 30_000 });
+  });
+});
+
+describe("isProcessAlive", () => {
+  it("returns false without probing invalid pids", () => {
+    const killSpy = spyOn(process, "kill").mockImplementation((() => {
+      throw new Error("process.kill should not be called");
+    }) as typeof process.kill);
+
+    try {
+      expect(isProcessAlive(0)).toBe(false);
+      expect(isProcessAlive(-1)).toBe(false);
+      expect(isProcessAlive(1.5)).toBe(false);
+      expect(killSpy).not.toHaveBeenCalled();
+    } finally {
+      killSpy.mockRestore();
+    }
+  });
+
+  it("treats EPERM from process.kill(pid, 0) as alive", () => {
+    const killSpy = spyOn(process, "kill").mockImplementation((() => {
+      const err = new Error("operation not permitted") as NodeJS.ErrnoException;
+      err.code = "EPERM";
+      throw err;
+    }) as typeof process.kill);
+
+    try {
+      expect(isProcessAlive(123)).toBe(true);
+      expect(killSpy).toHaveBeenCalledWith(123, 0);
+    } finally {
+      killSpy.mockRestore();
+    }
+  });
+});
+
+const NOW_MS = Date.parse("2026-06-19T12:00:00.000Z");
+const LOCK_TIMEOUT_MS = 1000;
+const DEAD_PID = 999_999;
+
+interface Fixture {
+  dataDir: string;
+  jobDir: string;
+}
+
+async function makeFixture(opts: {
+  jobId?: string;
+  snapshot?: Record<string, unknown> | null;
+  runnerPid?: number;
+  lease?: Record<string, unknown> | null;
+}): Promise<Fixture> {
+  const jobId = opts.jobId ?? "job-reconcile";
+  const dataDir = await mkdtemp(join(tmpdir(), "pop-reconcile-"));
+  const jobDir = join(dataDir, "current", jobId);
+  await mkdir(jobDir, { recursive: true });
+
+  if (opts.snapshot !== null) {
+    const snapshot = opts.snapshot ?? {
+      id: jobId,
+      state: "running",
+      current: "research",
+      currentStage: null,
+      lastUpdated: "2026-06-19T11:00:00.000Z",
+      tasks: { research: { state: "running" } },
+      files: { artifacts: [], logs: [], tmp: [] },
+    };
+    await writeFile(join(jobDir, STATUS_FILENAME), JSON.stringify(snapshot, null, 2));
+  }
+
+  if (opts.runnerPid !== undefined) {
+    await writeFile(join(jobDir, "runner.pid"), String(opts.runnerPid));
+  }
+
+  if (opts.lease) {
+    const runningJobsDir = join(dataDir, "runtime", "running-jobs");
+    await mkdir(runningJobsDir, { recursive: true });
+    const lease: Record<string, unknown> = {
+      jobId,
+      pid: null,
+      acquiredAt: new Date(NOW_MS).toISOString(),
+      source: "orchestrator",
+      slotPath: join(runningJobsDir, `${jobId}.json`),
+      ...opts.lease,
+    };
+    await writeFile(join(runningJobsDir, `${jobId}.json`), JSON.stringify(lease));
+  }
+
+  return { dataDir, jobDir };
+}
+
+async function readSnapshot(jobDir: string): Promise<Record<string, unknown>> {
+  const result = await readJobStatusResult(jobDir);
+  if (!result.ok) throw new Error(`status not readable: ${result.reason}`);
+  return result.value as unknown as Record<string, unknown>;
+}
+
+describe("reconcileInterruptedJob", () => {
+  let fixtures: Fixture[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      fixtures.map((f) => rm(f.dataDir, { recursive: true, force: true }).catch(() => {})),
+    );
+    fixtures = [];
+  });
+
+  async function setup(opts: Parameters<typeof makeFixture>[0]): Promise<Fixture> {
+    const fixture = await makeFixture(opts);
+    fixtures.push(fixture);
+    return fixture;
+  }
+
+  it("marks task and job failed with the interruption marker when pid is dead and no lease (AC-1, AC-2)", async () => {
+    const { dataDir, jobDir } = await setup({ runnerPid: DEAD_PID });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      code: 1,
+      signal: null,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: true, taskId: "research", reason: "marked-failed" });
+
+    const snapshot = await readSnapshot(jobDir);
+    expect(snapshot["state"]).toBe("failed");
+    const tasks = snapshot["tasks"] as Record<string, Record<string, unknown>>;
+    expect(tasks["research"]?.["state"]).toBe("failed");
+    expect(tasks["research"]?.["error"]).toBe("runner exited without completing this task");
+    expect(tasks["research"]?.["endedAt"]).toBe(new Date(NOW_MS).toISOString());
+    expect(tasks["research"]?.["errorContext"]).toEqual({
+      kind: "runner-interrupted",
+      code: 1,
+      signal: null,
+      source: "child-exit",
+    });
+  });
+
+  it("is a no-op (live-pid) when runner.pid points at a live process (AC-6)", async () => {
+    const { dataDir, jobDir } = await setup({ runnerPid: process.pid });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: isProcessAlive,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "live-pid" });
+
+    const snapshot = await readSnapshot(jobDir);
+    expect(snapshot["state"]).toBe("running");
+  });
+
+  it("is a no-op (live-lease) when a fresh in-flight lease exists (pid null, acquiredAt within window) (AC-7)", async () => {
+    const { dataDir, jobDir } = await setup({
+      runnerPid: DEAD_PID,
+      lease: { pid: null, acquiredAt: new Date(NOW_MS).toISOString() },
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "live-lease" });
+  });
+
+  it("is a no-op (live-lease) when a lease pid is alive (AC-7)", async () => {
+    const { dataDir, jobDir } = await setup({
+      runnerPid: DEAD_PID,
+      lease: { pid: process.pid },
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: (pid) => pid === process.pid,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "live-lease" });
+  });
+
+  it("is a no-op (not-running) for a waiting (gated) job (AC-8)", async () => {
+    const { dataDir, jobDir } = await setup({
+      snapshot: {
+        id: "job-reconcile",
+        state: "waiting",
+        current: "research",
+        currentStage: null,
+        lastUpdated: "2026-06-19T11:00:00.000Z",
+        tasks: { research: { state: "done" }, analysis: { state: "pending" } },
+        gate: { afterTask: "research", message: "approve", requestedAt: "2026-06-19T11:30:00.000Z" },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "not-running" });
+  });
+
+  it("is a no-op (not-running) for a pending job (AC-8)", async () => {
+    const { dataDir, jobDir } = await setup({
+      snapshot: {
+        id: "job-reconcile",
+        state: "pending",
+        current: null,
+        currentStage: null,
+        lastUpdated: "2026-06-19T11:00:00.000Z",
+        tasks: { research: { state: "pending" } },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "not-running" });
+  });
+
+  it("is a no-op (not-running) for an already-failed job (AC-5)", async () => {
+    const { dataDir, jobDir } = await setup({
+      snapshot: {
+        id: "job-reconcile",
+        state: "failed",
+        current: "research",
+        currentStage: null,
+        lastUpdated: "2026-06-19T11:00:00.000Z",
+        tasks: { research: { state: "failed", error: "boom" } },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "not-running" });
+  });
+
+  it("is a no-op (not-running) for a done job (AC-5)", async () => {
+    const { dataDir, jobDir } = await setup({
+      snapshot: {
+        id: "job-reconcile",
+        state: "done",
+        current: null,
+        currentStage: null,
+        lastUpdated: "2026-06-19T11:00:00.000Z",
+        tasks: { research: { state: "done" } },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "not-running" });
+  });
+
+  it("is a no-op (fresh-status) on the boot-sweep path when status is within the grace window (AC-9)", async () => {
+    const { dataDir, jobDir } = await setup({
+      snapshot: {
+        id: "job-reconcile",
+        state: "running",
+        current: "research",
+        currentStage: null,
+        lastUpdated: new Date(NOW_MS).toISOString(),
+        tasks: { research: { state: "running" } },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+      runnerPid: DEAD_PID,
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "boot-sweep",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      requireStaleStatus: true,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "fresh-status" });
+  });
+
+  it("marks a stale job-level running state failed when no running task remains", async () => {
+    const { dataDir, jobDir } = await setup({
+      snapshot: {
+        id: "job-reconcile",
+        state: "running",
+        current: "research",
+        currentStage: null,
+        lastUpdated: "2026-06-19T11:00:00.000Z",
+        tasks: { research: { state: "done" } },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+      runnerPid: DEAD_PID,
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "boot-sweep",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      requireStaleStatus: true,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: true, reason: "marked-failed" });
+
+    const snapshot = await readSnapshot(jobDir);
+    expect(snapshot["state"]).toBe("failed");
+    expect(snapshot["current"]).toBeNull();
+    expect(snapshot["currentStage"]).toBeNull();
+    expect(snapshot["error"]).toEqual({
+      name: "RunnerInterrupted",
+      message: "runner exited while the job was still marked running",
+    });
+    expect(snapshot["errorContext"]).toEqual({
+      kind: "runner-interrupted",
+      code: undefined,
+      signal: undefined,
+      source: "boot-sweep",
+    });
+    const tasks = snapshot["tasks"] as Record<string, Record<string, unknown>>;
+    expect(tasks["research"]?.["state"]).toBe("done");
+  });
+
+  it("leaves a fresh job-level running state alone when no running task remains", async () => {
+    const { dataDir, jobDir } = await setup({
+      snapshot: {
+        id: "job-reconcile",
+        state: "running",
+        current: "research",
+        currentStage: null,
+        lastUpdated: new Date(NOW_MS).toISOString(),
+        tasks: { research: { state: "done" } },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+      runnerPid: DEAD_PID,
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "boot-sweep",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      requireStaleStatus: true,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "fresh-status" });
+
+    const snapshot = await readSnapshot(jobDir);
+    expect(snapshot["state"]).toBe("running");
+  });
+
+  it("is a no-op (unreadable) and writes nothing when status is missing (AC-12)", async () => {
+    const { dataDir, jobDir } = await setup({ snapshot: null, runnerPid: DEAD_PID });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "unreadable" });
+
+    const after = await readJobStatusResult(jobDir);
+    expect(after).toEqual({ ok: false, reason: "missing" });
+  });
+
+  it("is a no-op (unreadable) and leaves a corrupt status file untouched (AC-12)", async () => {
+    const { dataDir, jobDir } = await setup({ snapshot: null, runnerPid: DEAD_PID });
+    const corruptPath = join(jobDir, STATUS_FILENAME);
+    const corruptContent = "{";
+    await writeFile(corruptPath, corruptContent);
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "unreadable" });
+
+    const after = await Bun.file(corruptPath).text();
+    expect(after).toBe(corruptContent);
+  });
+
+  it("is idempotent: a second call after a successful reconcile is a no-op and does not change the file (AC-13)", async () => {
+    const { dataDir, jobDir } = await setup({ runnerPid: DEAD_PID });
+
+    const first = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      code: 1,
+      signal: null,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+    expect(first).toEqual({ reconciled: true, taskId: "research", reason: "marked-failed" });
+
+    const fileAfterFirst = await Bun.file(join(jobDir, STATUS_FILENAME)).text();
+
+    const second = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+    expect(second).toEqual({ reconciled: false, reason: "not-running" });
+
+    const fileAfterSecond = await Bun.file(join(jobDir, STATUS_FILENAME)).text();
+    expect(fileAfterSecond).toBe(fileAfterFirst);
+  });
+
+  it("does not clobber a fresh competing lease (forced interleave) (AC-14)", async () => {
+    const { dataDir, jobDir } = await setup({
+      runnerPid: DEAD_PID,
+      lease: { pid: null, acquiredAt: new Date(NOW_MS).toISOString() },
+    });
+
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId: "job-reconcile",
+      jobDir,
+      source: "child-exit",
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ reconciled: false, reason: "live-lease" });
+
+    const snapshot = await readSnapshot(jobDir);
+    expect(snapshot["state"]).toBe("running");
+  });
+
+  it("emits a structured log event with the required fields on success (AC-15)", async () => {
+    const { dataDir, jobDir } = await setup({ runnerPid: DEAD_PID });
+
+    const spy = spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const result = await reconcileInterruptedJob({
+        dataDir,
+        jobId: "job-reconcile",
+        jobDir,
+        source: "child-exit",
+        lockTimeoutMs: LOCK_TIMEOUT_MS,
+        code: 137,
+        signal: "SIGKILL",
+        now: () => NOW_MS,
+        isAlive: () => false,
+      });
+      expect(result).toEqual({ reconciled: true, taskId: "research", reason: "marked-failed" });
+
+      const calls = spy.mock.calls as unknown[][];
+      const eventCall = calls.find(
+        (call) => typeof call[1] === "string" && call[1] === "reconciled interrupted job",
+      );
+      expect(eventCall).toBeDefined();
+      const prefix = String(eventCall![0]);
+      expect(prefix).toContain("runner-liveness");
+      const payload = JSON.parse(String(eventCall![2])) as Record<string, unknown>;
+      expect(payload).toEqual({
+        jobId: "job-reconcile",
+        taskId: "research",
+        pid: DEAD_PID,
+        code: 137,
+        signal: "SIGKILL",
+        path: "child-exit",
+      });
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});
+
+describe("reconcileOrphanedCurrentJobs", () => {
+  let dataDirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      dataDirs.map((dir) => rm(dir, { recursive: true, force: true }).catch(() => {})),
+    );
+    dataDirs = [];
+  });
+
+  async function makeDataDir(): Promise<string> {
+    const dataDir = await mkdtemp(join(tmpdir(), "pop-sweep-"));
+    dataDirs.push(dataDir);
+    return dataDir;
+  }
+
+  async function writeJob(
+    dataDir: string,
+    jobId: string,
+    snapshot: Record<string, unknown>,
+    runnerPid?: number,
+  ): Promise<void> {
+    const jobDir = join(dataDir, "current", jobId);
+    await mkdir(jobDir, { recursive: true });
+    await writeFile(join(jobDir, STATUS_FILENAME), JSON.stringify(snapshot, null, 2));
+    if (runnerPid !== undefined) {
+      await writeFile(join(jobDir, "runner.pid"), String(runnerPid));
+    }
+  }
+
+  function runningSnapshot(jobId: string, lastUpdated: string): Record<string, unknown> {
+    return {
+      id: jobId,
+      state: "running",
+      current: "research",
+      currentStage: null,
+      lastUpdated,
+      tasks: { research: { state: "running" } },
+      files: { artifacts: [], logs: [], tmp: [] },
+    };
+  }
+
+  it("reconciles a stale current/ job with a dead pid and returns its jobId (AC-4)", async () => {
+    const dataDir = await makeDataDir();
+    const jobId = "job-stale";
+    await writeJob(
+      dataDir,
+      jobId,
+      runningSnapshot(jobId, "2026-06-19T11:00:00.000Z"),
+      DEAD_PID,
+    );
+
+    const result = await reconcileOrphanedCurrentJobs({
+      dataDir,
+      currentDir: join(dataDir, "current"),
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ scanned: 1, reconciled: [jobId] });
+
+    const snapshot = await readSnapshot(join(dataDir, "current", jobId));
+    expect(snapshot["state"]).toBe("failed");
+    const tasks = snapshot["tasks"] as Record<string, Record<string, unknown>>;
+    expect(tasks["research"]?.["state"]).toBe("failed");
+    expect(tasks["research"]?.["errorContext"]).toEqual({
+      kind: "runner-interrupted",
+      code: undefined,
+      signal: undefined,
+      source: "boot-sweep",
+    });
+  });
+
+  it("leaves alone a job whose runner.pid points at a live process (AC-11)", async () => {
+    const dataDir = await makeDataDir();
+    const jobId = "job-live";
+    await writeJob(
+      dataDir,
+      jobId,
+      runningSnapshot(jobId, "2026-06-19T11:00:00.000Z"),
+      process.pid,
+    );
+
+    const result = await reconcileOrphanedCurrentJobs({
+      dataDir,
+      currentDir: join(dataDir, "current"),
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: isProcessAlive,
+    });
+
+    expect(result).toEqual({ scanned: 1, reconciled: [] });
+
+    const snapshot = await readSnapshot(join(dataDir, "current", jobId));
+    expect(snapshot["state"]).toBe("running");
+  });
+
+  it("leaves alone a job whose status is fresh within the grace window (AC-11)", async () => {
+    const dataDir = await makeDataDir();
+    const jobId = "job-fresh";
+    await writeJob(
+      dataDir,
+      jobId,
+      runningSnapshot(jobId, new Date(NOW_MS).toISOString()),
+      DEAD_PID,
+    );
+
+    const result = await reconcileOrphanedCurrentJobs({
+      dataDir,
+      currentDir: join(dataDir, "current"),
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ scanned: 1, reconciled: [] });
+
+    const snapshot = await readSnapshot(join(dataDir, "current", jobId));
+    expect(snapshot["state"]).toBe("running");
+  });
+
+  it("leaves alone a job in a terminal state (AC-11)", async () => {
+    const dataDir = await makeDataDir();
+    const jobId = "job-done";
+    await writeJob(
+      dataDir,
+      jobId,
+      {
+        id: jobId,
+        state: "done",
+        current: null,
+        currentStage: null,
+        lastUpdated: "2026-06-19T11:00:00.000Z",
+        tasks: { research: { state: "done" } },
+        files: { artifacts: [], logs: [], tmp: [] },
+      },
+      DEAD_PID,
+    );
+
+    const result = await reconcileOrphanedCurrentJobs({
+      dataDir,
+      currentDir: join(dataDir, "current"),
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ scanned: 1, reconciled: [] });
+
+    const snapshot = await readSnapshot(join(dataDir, "current", jobId));
+    expect(snapshot["state"]).toBe("done");
+  });
+
+  it("returns scanned: 0 when current/ does not exist (AC-16)", async () => {
+    const dataDir = await makeDataDir();
+
+    const result = await reconcileOrphanedCurrentJobs({
+      dataDir,
+      currentDir: join(dataDir, "current"),
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ scanned: 0, reconciled: [] });
+  });
+
+  it("returns scanned: 0 for an empty current/ directory", async () => {
+    const dataDir = await makeDataDir();
+    await mkdir(join(dataDir, "current"), { recursive: true });
+    const log = spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const result = await reconcileOrphanedCurrentJobs({
+        dataDir,
+        currentDir: join(dataDir, "current"),
+        lockTimeoutMs: LOCK_TIMEOUT_MS,
+        staleAfterMs: 30_000,
+        now: () => NOW_MS,
+        isAlive: () => false,
+      });
+
+      expect(result).toEqual({ scanned: 0, reconciled: [] });
+      expect(log).not.toHaveBeenCalled();
+    } finally {
+      log.mockRestore();
+    }
+  });
+
+  it("ignores non-directory entries in current/ when reporting scanned jobs", async () => {
+    const dataDir = await makeDataDir();
+    const currentDir = join(dataDir, "current");
+    await mkdir(currentDir, { recursive: true });
+    await writeFile(join(currentDir, ".DS_Store"), "not a job");
+
+    const result = await reconcileOrphanedCurrentJobs({
+      dataDir,
+      currentDir,
+      lockTimeoutMs: LOCK_TIMEOUT_MS,
+      staleAfterMs: 30_000,
+      now: () => NOW_MS,
+      isAlive: () => false,
+    });
+
+    expect(result).toEqual({ scanned: 0, reconciled: [] });
+  });
+});