gsd-pi 2.28.0-dev.e19bf89 → 2.29.0-dev.23d50d0

package/src/resources/extensions/gsd/tests/mechanical-completion.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Mechanical Completion — unit tests (ADR-003).
+ *
+ * Tests deterministic slice/milestone completion using fixture data.
+ * Uses node:test + node:assert for consistency with token-profile.test.ts.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+
+// ─── Fixture Helpers ──────────────────────────────────────────────────────────
+
+function createTmpBase(): string {
+  const base = join(tmpdir(), `gsd-mech-test-${randomBytes(4).toString("hex")}`);
+  mkdirSync(base, { recursive: true });
+  return base;
+}
+
+function scaffold(base: string, mid: string, sid: string, taskSummaries: Array<{ tid: string; content: string }>) {
+  const gsdRoot = join(base, ".gsd");
+  const mDir = join(gsdRoot, "milestones", mid);
+  const sDir = join(mDir, "slices", sid);
+  const tDir = join(sDir, "tasks");
+  mkdirSync(tDir, { recursive: true });
+
+  for (const { tid, content } of taskSummaries) {
+    writeFileSync(join(tDir, `${tid}-SUMMARY.md`), content, "utf-8");
+  }
+
+  return { gsdRoot, mDir, sDir, tDir };
+}
+
+function makeTaskSummary(tid: string, opts: {
+  oneLiner?: string;
+  provides?: string[];
+  key_files?: string[];
+  key_decisions?: string[];
+  verification_result?: string;
+}): string {
+  const lines: string[] = [
+    "---",
+    `id: ${tid}`,
+    `parent: S01`,
+    `milestone: M001`,
+  ];
+  if (opts.provides?.length) lines.push(`provides:\n${opts.provides.map(p => `  - ${p}`).join("\n")}`);
+  if (opts.key_files?.length) lines.push(`key_files:\n${opts.key_files.map(f => `  - ${f}`).join("\n")}`);
+  if (opts.key_decisions?.length) lines.push(`key_decisions:\n${opts.key_decisions.map(d => `  - ${d}`).join("\n")}`);
+  lines.push(`verification_result: ${opts.verification_result ?? "passed"}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${tid}: Test Task`);
+  lines.push("");
+  if (opts.oneLiner) lines.push(`**${opts.oneLiner}**`);
+  lines.push("");
+  lines.push("## What Happened");
+  lines.push("");
+  lines.push(`Implemented the feature described in ${tid}. This was a significant change that modified multiple files across the codebase to support the new functionality.`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+// ─── Source-level structural tests ────────────────────────────────────────────
+
+const mechanicalSrc = readFileSync(
+  join(import.meta.dirname!, "..", "mechanical-completion.ts"),
+  "utf-8",
+);
+
+test("mechanical-completion: exports mechanicalSliceCompletion", () => {
+  assert.ok(
+    mechanicalSrc.includes("export async function mechanicalSliceCompletion"),
+    "should export mechanicalSliceCompletion",
+  );
+});
+
+test("mechanical-completion: exports aggregateMilestoneVerification", () => {
+  assert.ok(
+    mechanicalSrc.includes("export async function aggregateMilestoneVerification"),
+    "should export aggregateMilestoneVerification",
+  );
+});
+
+test("mechanical-completion: exports generateMilestoneSummary", () => {
+  assert.ok(
+    mechanicalSrc.includes("export async function generateMilestoneSummary"),
+    "should export generateMilestoneSummary",
+  );
+});
+
+test("mechanical-completion: exports appendNewDecisions", () => {
+  assert.ok(
+    mechanicalSrc.includes("export async function appendNewDecisions"),
+    "should export appendNewDecisions",
+  );
+});
+
+test("mechanical-completion: uses atomicWriteSync for file writes", () => {
+  assert.ok(
+    mechanicalSrc.includes("atomicWriteSync"),
+    "should use atomicWriteSync for safe file writes",
+  );
+});
+
+test("mechanical-completion: quality gate checks summary length for multi-task slices", () => {
+  assert.ok(
+    mechanicalSrc.includes("totalContent.length < 200"),
+    "should have quality gate for summary content length",
+  );
+});
+
+test("mechanical-completion: marks slice [x] in roadmap", () => {
+  assert.ok(
+    mechanicalSrc.includes("markSliceInRoadmap"),
+    "should mark slice done in roadmap",
+  );
+});
+
+test("mechanical-completion: aggregates VERIFY.json files for milestone validation", () => {
+  assert.ok(
+    mechanicalSrc.includes("resolveTaskJsonFiles") && mechanicalSrc.includes("VERIFY"),
+    "should read VERIFY.json files for milestone validation",
+  );
+});
+
+test("mechanical-completion: deduplicates decisions against existing DECISIONS.md", () => {
+  assert.ok(
+    mechanicalSrc.includes("existing.includes(d.trim())"),
+    "should deduplicate decisions against existing content",
+  );
+});
+
+test("mechanical-completion: produces VALIDATION.md with verdict frontmatter", () => {
+  assert.ok(
+    mechanicalSrc.includes("verdict:") && mechanicalSrc.includes("remediation_round: 0"),
+    "VALIDATION.md should have verdict and remediation_round frontmatter",
+  );
+});
+
+// ─── Integration tests with fixture data ──────────────────────────────────────
+
+test("mechanical: slice completion with 2 task summaries produces SUMMARY.md", async () => {
+  const base = createTmpBase();
+  try {
+    const mid = "M001";
+    const sid = "S01";
+
+    // Scaffold task summaries
+    scaffold(base, mid, sid, [
+      {
+        tid: "T01",
+        content: makeTaskSummary("T01", {
+          oneLiner: "Set up project structure",
+          provides: ["project-scaffold"],
+          key_files: ["src/index.ts", "package.json"],
+          verification_result: "passed",
+        }),
+      },
+      {
+        tid: "T02",
+        content: makeTaskSummary("T02", {
+          oneLiner: "Add core API endpoints",
+          provides: ["api-endpoints"],
+          key_files: ["src/api.ts"],
+          key_decisions: ["Used Express over Fastify"],
+          verification_result: "passed",
+        }),
+      },
+    ]);
+
+    // Write a roadmap with the slice unchecked
+    const roadmapPath = join(base, ".gsd", "milestones", mid, `${mid}-ROADMAP.md`);
+    writeFileSync(roadmapPath, `# Roadmap\n\n- [ ] **${sid}: First Slice**\n`, "utf-8");
+
+    // Write a slice plan with Verification section
+    const planPath = join(base, ".gsd", "milestones", mid, "slices", sid, `${sid}-PLAN.md`);
+    writeFileSync(planPath, `# Plan\n\n## Verification\n\n- Run \`npm test\`\n- Check output\n`, "utf-8");
+
+    // Dynamic import to get the actual module
+    const { mechanicalSliceCompletion } = await import("../mechanical-completion.js");
+    const ok = await mechanicalSliceCompletion(base, mid, sid);
+
+    assert.ok(ok, "should return true for valid slice completion");
+
+    // Check SUMMARY.md was written
+    const summaryPath = join(base, ".gsd", "milestones", mid, "slices", sid, `${sid}-SUMMARY.md`);
+    assert.ok(existsSync(summaryPath), "SUMMARY.md should exist");
+
+    const summaryContent = readFileSync(summaryPath, "utf-8");
+    assert.ok(summaryContent.includes("T01"), "summary should reference T01");
+    assert.ok(summaryContent.includes("T02"), "summary should reference T02");
+    assert.ok(summaryContent.includes("verification_result: passed"), "should have passed verification");
+
+    // Check roadmap was updated
+    const updatedRoadmap = readFileSync(roadmapPath, "utf-8");
+    assert.ok(updatedRoadmap.includes("[x]"), "roadmap should have [x] checkbox");
+
+    // Check UAT was written
+    const uatPath = join(base, ".gsd", "milestones", mid, "slices", sid, `${sid}-UAT.md`);
+    assert.ok(existsSync(uatPath), "UAT.md should exist");
+    const uatContent = readFileSync(uatPath, "utf-8");
+    assert.ok(uatContent.includes("npm test"), "UAT should contain verification content");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("mechanical: returns false for empty task summaries", async () => {
+  const base = createTmpBase();
+  try {
+    const mid = "M001";
+    const sid = "S01";
+    scaffold(base, mid, sid, []);
+
+    const { mechanicalSliceCompletion } = await import("../mechanical-completion.js");
+    const ok = await mechanicalSliceCompletion(base, mid, sid);
+    assert.ok(!ok, "should return false when no summaries exist");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("mechanical: returns false for insufficient summary content in multi-task slice", async () => {
+  const base = createTmpBase();
+  try {
+    const mid = "M001";
+    const sid = "S01";
+
+    // Two tasks but with very short content (under 200 chars)
+    scaffold(base, mid, sid, [
+      { tid: "T01", content: "---\nid: T01\nparent: S01\nmilestone: M001\n---\n\n# T01: A\n\n**Short**\n" },
+      { tid: "T02", content: "---\nid: T02\nparent: S01\nmilestone: M001\n---\n\n# T02: B\n\n**Brief**\n" },
+    ]);
+
+    const { mechanicalSliceCompletion } = await import("../mechanical-completion.js");
+    const ok = await mechanicalSliceCompletion(base, mid, sid);
+    assert.ok(!ok, "should return false when summaries are too short");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("mechanical: milestone verification aggregates VERIFY.json files", async () => {
+  const base = createTmpBase();
+  try {
+    const mid = "M001";
+    const sid = "S01";
+    const { tDir } = scaffold(base, mid, sid, []);
+
+    // Write VERIFY.json files
+    const evidence = {
+      schemaVersion: 1,
+      taskId: "T01",
+      unitId: "M001/S01/T01",
+      timestamp: Date.now(),
+      passed: true,
+      discoverySource: "plan",
+      checks: [
+        { command: "npm test", exitCode: 0, durationMs: 1500, verdict: "pass", blocking: true },
+      ],
+    };
+    writeFileSync(join(tDir, "T01-VERIFY.json"), JSON.stringify(evidence), "utf-8");
+
+    const evidence2 = { ...evidence, taskId: "T02", passed: false, checks: [
+      { command: "npm test", exitCode: 1, durationMs: 500, verdict: "fail", blocking: true },
+    ]};
+    writeFileSync(join(tDir, "T02-VERIFY.json"), JSON.stringify(evidence2), "utf-8");
+
+    const { aggregateMilestoneVerification } = await import("../mechanical-completion.js");
+    const result = await aggregateMilestoneVerification(base, mid);
+
+    assert.equal(result.verdict, "mixed", "should be mixed when some pass and some fail");
+    assert.equal(result.checks.length, 2, "should have 2 checks");
+
+    // Check VALIDATION.md was written
+    const validationPath = join(base, ".gsd", "milestones", mid, `${mid}-VALIDATION.md`);
+    assert.ok(existsSync(validationPath), "VALIDATION.md should exist");
+    const validationContent = readFileSync(validationPath, "utf-8");
+    assert.ok(validationContent.includes("verdict: mixed"), "should have mixed verdict in frontmatter");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("mechanical: milestone summary aggregates slice summaries", async () => {
+  const base = createTmpBase();
+  try {
+    const mid = "M001";
+
+    // Create two slices with summaries
+    for (const sid of ["S01", "S02"]) {
+      const sDir = join(base, ".gsd", "milestones", mid, "slices", sid);
+      mkdirSync(sDir, { recursive: true });
+      writeFileSync(
+        join(sDir, `${sid}-SUMMARY.md`),
+        `---\nid: ${sid}\nprovides:\n  - feature-${sid.toLowerCase()}\nkey_files:\n  - src/${sid.toLowerCase()}.ts\n---\n\n# ${sid}: Slice\n\n**${sid} implemented**\n`,
+        "utf-8",
+      );
+    }
+
+    const { generateMilestoneSummary } = await import("../mechanical-completion.js");
+    const content = await generateMilestoneSummary(base, mid);
+
+    assert.ok(content.includes("S01"), "should reference S01");
+    assert.ok(content.includes("S02"), "should reference S02");
+    assert.ok(content.includes("feature-s01"), "should aggregate provides");
+    assert.ok(content.includes("feature-s02"), "should aggregate provides");
+
+    const summaryPath = join(base, ".gsd", "milestones", mid, `${mid}-SUMMARY.md`);
+    assert.ok(existsSync(summaryPath), "M##-SUMMARY.md should exist");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("mechanical: decision deduplication skips existing decisions", async () => {
+  const base = createTmpBase();
+  try {
+    const gsdRoot = join(base, ".gsd");
+    mkdirSync(gsdRoot, { recursive: true });
+
+    // Write existing decisions
+    const decisionsPath = join(gsdRoot, "DECISIONS.md");
+    writeFileSync(decisionsPath, "# Decisions\n\n- Used TypeScript for type safety\n", "utf-8");
+
+    const { appendNewDecisions } = await import("../mechanical-completion.js");
+
+    // Call with one existing and one new decision
+    const mockSummaries = [
+      {
+        frontmatter: {
+          id: "T01", parent: "S01", milestone: "M001",
+          provides: [], requires: [], affects: [],
+          key_files: [], key_decisions: ["Used TypeScript for type safety", "Chose Express over Koa"],
+          patterns_established: [], drill_down_paths: [], observability_surfaces: [],
+          duration: "", verification_result: "passed", completed_at: "", blocker_discovered: false,
+        },
+        title: "T01", oneLiner: "", whatHappened: "", deviations: "", filesModified: [],
+      },
+    ];
+
+    await appendNewDecisions(base, mockSummaries as any);
+
+    const updated = readFileSync(decisionsPath, "utf-8");
+    assert.ok(updated.includes("Chose Express over Koa"), "should append new decision");
+    // The existing decision should not be duplicated
+    const matches = updated.match(/Used TypeScript for type safety/g);
+    assert.equal(matches?.length, 1, "should not duplicate existing decision");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/parallel-workers-multi-milestone-e2e.test.ts

@@ -30,7 +30,7 @@ import {
   getBudgetAlertLevel,
   getNewBudgetAlertLevel,
   getBudgetEnforcementAction,
-} from '../auto.ts';
+} from '../auto-budget.ts';
 import {
   type UnitMetrics,
   type MetricsLedger,

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -25,6 +25,7 @@ const BASE_VARS = {
   outputPath: "/tmp/test-project/.gsd/milestones/M001/slices/S01/S01-PLAN.md",
   inlinedContext: "--- test inlined context ---",
   dependencySummaries: "", executorContextConstraints: "",
+  sourceFilePaths: "- **Requirements**: `.gsd/REQUIREMENTS.md`",
 };
 
 test("plan-slice prompt: commit step present when commit_docs=true", () => {

package/src/resources/extensions/gsd/tests/session-lock.test.ts

@@ -0,0 +1,315 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, writeFileSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  acquireSessionLock,
+  releaseSessionLock,
+  updateSessionLock,
+  validateSessionLock,
+  readSessionLockData,
+  isSessionLockHeld,
+  isSessionLockProcessAlive,
+} from "../session-lock.ts";
+
+// ─── acquireSessionLock ──────────────────────────────────────────────────
+
+test("acquireSessionLock succeeds on empty directory", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const result = acquireSessionLock(dir);
+  assert.equal(result.acquired, true, "should acquire lock on empty dir");
+
+  // Verify lock file was created with correct data
+  const lockPath = join(dir, ".gsd", "auto.lock");
+  assert.ok(existsSync(lockPath), "auto.lock should exist after acquire");
+
+  const data = JSON.parse(readFileSync(lockPath, "utf-8"));
+  assert.equal(data.pid, process.pid, "lock should contain current PID");
+  assert.equal(data.unitType, "starting", "initial unit type should be 'starting'");
+
+  releaseSessionLock(dir);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("acquireSessionLock rejects when another live process holds lock", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // Simulate another process holding the lock by writing a lock with parent PID
+  const fakeLockData = {
+    pid: process.ppid,
+    startedAt: new Date().toISOString(),
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 2,
+  };
+  writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(fakeLockData, null, 2));
+
+  // First acquire to set up proper-lockfile state
+  const result1 = acquireSessionLock(dir);
+
+  // If proper-lockfile is available, it should manage the OS lock.
+  // If not (fallback mode), the PID check should detect the live process.
+  // Either way, we can't fully simulate another process holding an OS lock
+  // from within the same process, so we test the fallback path.
+  if (result1.acquired) {
+    // We got the lock (proper-lockfile saw no OS lock from another process)
+    // This is expected since we're in the same process
+    releaseSessionLock(dir);
+  }
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("acquireSessionLock takes over stale lock from dead process", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // Write a lock from a dead process
+  const staleLockData = {
+    pid: 9999999,
+    startedAt: "2026-03-01T00:00:00Z",
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    unitStartedAt: "2026-03-01T00:00:00Z",
+    completedUnits: 0,
+  };
+  writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(staleLockData, null, 2));
+
+  const result = acquireSessionLock(dir);
+  assert.equal(result.acquired, true, "should take over lock from dead process");
+
+  // Verify our PID is now in the lock
+  const data = readSessionLockData(dir);
+  assert.ok(data, "lock data should exist after acquire");
+  assert.equal(data!.pid, process.pid, "lock should contain our PID now");
+
+  releaseSessionLock(dir);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── releaseSessionLock ─────────────────────────────────────────────────
+
+test("releaseSessionLock removes the lock file", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const result = acquireSessionLock(dir);
+  assert.equal(result.acquired, true);
+
+  releaseSessionLock(dir);
+
+  const lockPath = join(dir, ".gsd", "auto.lock");
+  assert.ok(!existsSync(lockPath), "auto.lock should be removed after release");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("releaseSessionLock is safe when no lock exists", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // Should not throw
+  releaseSessionLock(dir);
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── updateSessionLock ──────────────────────────────────────────────────
+
+test("updateSessionLock updates the lock data without re-acquiring", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const result = acquireSessionLock(dir);
+  assert.equal(result.acquired, true);
+
+  updateSessionLock(dir, "execute-task", "M001/S01/T02", 3, "/tmp/session.jsonl");
+
+  const data = readSessionLockData(dir);
+  assert.ok(data, "lock data should exist after update");
+  assert.equal(data!.pid, process.pid, "PID should still be ours");
+  assert.equal(data!.unitType, "execute-task", "unit type should be updated");
+  assert.equal(data!.unitId, "M001/S01/T02", "unit ID should be updated");
+  assert.equal(data!.completedUnits, 3, "completed count should be updated");
+  assert.equal(data!.sessionFile, "/tmp/session.jsonl", "session file should be recorded");
+
+  releaseSessionLock(dir);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── validateSessionLock ────────────────────────────────────────────────
+
+test("validateSessionLock returns true when we hold the lock", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const result = acquireSessionLock(dir);
+  assert.equal(result.acquired, true);
+
+  assert.equal(validateSessionLock(dir), true, "should validate when we hold the lock");
+
+  releaseSessionLock(dir);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("validateSessionLock returns false after release", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const result = acquireSessionLock(dir);
+  assert.equal(result.acquired, true);
+  assert.equal(validateSessionLock(dir), true, "should be valid while held");
+
+  // Release the lock — both OS lock and lock file are removed
+  releaseSessionLock(dir);
+
+  // After release, _lockedPath is cleared and lock file is gone
+  assert.equal(isSessionLockHeld(dir), false, "should not be held after release");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("validateSessionLock returns false when another PID owns the lock", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // Write lock data with a different PID (parent process)
+  const foreignLockData = {
+    pid: process.ppid,
+    startedAt: new Date().toISOString(),
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 0,
+  };
+  writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(foreignLockData, null, 2));
+
+  // Without holding the OS lock, validate should check PID
+  assert.equal(validateSessionLock(dir), false, "should fail when another PID owns lock");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── isSessionLockHeld ──────────────────────────────────────────────────
+
+test("isSessionLockHeld returns true after acquire", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  acquireSessionLock(dir);
+  assert.equal(isSessionLockHeld(dir), true);
+
+  releaseSessionLock(dir);
+  assert.equal(isSessionLockHeld(dir), false, "should return false after release");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── isSessionLockProcessAlive ──────────────────────────────────────────
+
+test("isSessionLockProcessAlive returns false for dead PID", () => {
+  const data = {
+    pid: 9999999,
+    startedAt: new Date().toISOString(),
+    unitType: "starting",
+    unitId: "bootstrap",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 0,
+  };
+  assert.equal(isSessionLockProcessAlive(data), false);
+});
+
+test("isSessionLockProcessAlive returns false for own PID (recycled)", () => {
+  const data = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    unitType: "starting",
+    unitId: "bootstrap",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 0,
+  };
+  // Own PID returns false because it means the lock is from a recycled PID
+  assert.equal(isSessionLockProcessAlive(data), false);
+});
+
+// ─── readSessionLockData ────────────────────────────────────────────────
+
+test("readSessionLockData returns null when no lock exists", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const data = readSessionLockData(dir);
+  assert.equal(data, null);
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("readSessionLockData reads existing lock data", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const lockData = {
+    pid: 12345,
+    startedAt: "2026-03-18T00:00:00Z",
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    unitStartedAt: "2026-03-18T00:01:00Z",
+    completedUnits: 2,
+    sessionFile: "/tmp/session.jsonl",
+  };
+  writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(lockData, null, 2));
+
+  const data = readSessionLockData(dir);
+  assert.ok(data, "should read lock data");
+  assert.equal(data!.pid, 12345);
+  assert.equal(data!.unitType, "execute-task");
+  assert.equal(data!.unitId, "M001/S01/T01");
+  assert.equal(data!.completedUnits, 2);
+  assert.equal(data!.sessionFile, "/tmp/session.jsonl");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── Acquire → Release → Re-Acquire lifecycle ──────────────────────────
+
+test("session lock supports acquire → release → re-acquire cycle", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // First acquire
+  const r1 = acquireSessionLock(dir);
+  assert.equal(r1.acquired, true, "first acquire should succeed");
+  assert.equal(isSessionLockHeld(dir), true);
+
+  // Release
+  releaseSessionLock(dir);
+  assert.equal(isSessionLockHeld(dir), false);
+
+  // Re-acquire
+  const r2 = acquireSessionLock(dir);
+  assert.equal(r2.acquired, true, "re-acquire after release should succeed");
+  assert.equal(isSessionLockHeld(dir), true);
+
+  releaseSessionLock(dir);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── Lock creates .gsd/ directory if needed ─────────────────────────────
+
+test("acquireSessionLock creates .gsd/ if it does not exist", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-lock-"));
+  // Do NOT create .gsd/ — let the lock function do it
+
+  const result = acquireSessionLock(dir);
+  assert.equal(result.acquired, true, "should succeed even without .gsd/");
+  assert.ok(existsSync(join(dir, ".gsd")), ".gsd/ should be created");
+
+  releaseSessionLock(dir);
+  rmSync(dir, { recursive: true, force: true });
+});