gsd-pi 2.78.0 → 2.78.1-dev.9d08d820b

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -7,14 +7,13 @@
  * Templates live at prompts/ relative to this module's directory.
  * They use {{variableName}} syntax for substitution.
  *
- * All templates are eagerly loaded into cache at module init via warmCache().
- * This prevents a running session from being invalidated when another `gsd`
- * launch overwrites ~/.gsd/agent/ with newer templates via initResources().
- * Without eager caching, the in-memory extension code (which knows variable
- * set A) can read a newer template from disk (which expects variable set B),
- * causing a "template declares {{X}} but no value was provided" crash
- * mid-session — especially for late-loading templates like complete-milestone
- * that aren't read until the end of a long auto-mode run.
+ * Templates are snapshotted shortly after module init via warmCache().
+ * This keeps import/extension-registration fast while still preventing a
+ * running session from being invalidated when another `gsd` launch overwrites
+ * ~/.gsd/agent/ with newer templates via initResources(). Without caching, the
+ * in-memory extension code (which knows variable set A) can read a newer
+ * template from disk (which expects variable set B), causing a
+ * "template declares {{X}} but no value was provided" crash mid-session.
  */
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
@@ -82,8 +81,8 @@ export function getTemplatesDir(): string {
   return templatesDir;
 }
 
-// Cache all templates eagerly at module load — a running session uses the
-// template versions that were on disk at startup, immune to later overwrites.
+// Cache all templates from a startup snapshot — a running session uses the
+// template versions that were on disk near startup, immune to later overwrites.
 const templateCache = new Map<string, string>();
 
 /**
@@ -124,8 +123,23 @@ function warmCache(): void {
   }
 }
 
-// Snapshot all templates at module load time
-warmCache();
+let warmCacheScheduled = false;
+
+function scheduleWarmCache(): void {
+  if (warmCacheScheduled) return;
+  warmCacheScheduled = true;
+
+  const run = () => {
+    warmCache();
+  };
+
+  const timer = setTimeout(run, 1000);
+  timer.unref?.();
+}
+
+// Snapshot the full prompt/template tree after import so extension startup only
+// pays for prompts that are actually needed immediately.
+scheduleWarmCache();
 
 /**
  * Load a prompt template and substitute variables.

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -16,6 +16,16 @@ Start with what the excerpts give you. Read full files when the section heads si
 
 **On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+
+- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
+- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+
+Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+
 {{inlinedContext}}
 
 Then:

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -20,6 +20,16 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. Strongly consider delegating when the slice is non-trivial:
+
+- **Cross-cutting code or new abstractions** → dispatch the **reviewer** agent with the slice diff and plan; apply High/Critical findings before completing.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit.
+- **Added or modified tests** → dispatch the **tester** agent to assess coverage gaps relative to the slice plan.
+
+Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_complete_slice` with `milestoneId` and `sliceId`.
+
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
+### Delegate Recon and Sub-Decomposition When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate work that benefits from an isolated context window. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem → dispatch the **scout** agent for codebase recon and work from its compressed report.
+- The slice spans multiple subsystems and the decomposition isn't obvious → dispatch the **planner** agent or use the **decompose-into-slices** skill on a focused sub-area, then integrate.
+- You need current external information (library docs, API behavior, recent changes) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) from this unit — they would write user source and bypass this unit's write isolation. Implementation belongs in `execute-task`.
+
 ### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
 Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.

package/src/resources/extensions/gsd/prompts/refine-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
+### Delegate Recon When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate recon and sub-decomposition. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem touched by the sketch → dispatch the **scout** agent and work from its compressed report.
+- A specific area of the refinement needs deeper architectural analysis → dispatch the **planner** agent for a focused sub-plan, then integrate.
+- You need current external information (library docs, API behavior) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) — they would write user source and bypass write isolation. Implementation belongs in `execute-task`.
+
 ### Respect the Sketch Scope
 
 The sketch scope inlined above is a **hard constraint**. Plan within it. If, after exploring the codebase, the scope is too narrow to deliver the goal, surface this as a deviation in the plan's narrative and still produce the plan — do not silently expand the scope.

package/src/resources/extensions/gsd/slice-parallel-orchestrator.ts

@@ -82,6 +82,7 @@ let sliceState: SliceOrchestratorState | null = null;
 
 const SLICE_ORCHESTRATOR_STATE_FILE = "slice-orchestrator.json";
 const TMP_SUFFIX = ".tmp";
+export const SLICE_WORKER_AUTO_ARGS = ["headless", "--json", "auto"] as const;
 
 interface PersistedSliceWorker {
   milestoneId: string;
@@ -356,7 +357,7 @@ export function getSliceOrchestratorState(): SliceOrchestratorState | null {
 /**
  * Start parallel execution for eligible slices within a milestone.
  *
- * For each eligible slice: create a worktree, spawn `gsd --mode json --print "/gsd auto"`
+ * For each eligible slice: create a worktree, spawn `gsd headless --json auto`
  * with env GSD_SLICE_LOCK=<SID> + GSD_MILESTONE_LOCK=<MID> + GSD_PARALLEL_WORKER=1.
  */
 export async function startSliceParallel(
@@ -598,8 +599,13 @@ function resolveGsdBin(): string | null {
 
 /**
  * Spawn a worker process for a slice.
- * The worker runs `gsd --mode json --print "/gsd auto"` in the slice's worktree
+ * The worker runs `gsd headless --json auto` in the slice's worktree
  * with GSD_SLICE_LOCK, GSD_MILESTONE_LOCK, and GSD_PARALLEL_WORKER set.
+ *
+ * Print-mode slash commands return after the command handler schedules
+ * auto-mode, so the worker process can exit before doing any LLM work. The
+ * headless auto entrypoint keeps the process alive until auto-mode reaches a
+ * terminal notification, matching milestone-level parallel workers.
  */
 function spawnSliceWorker(
   basePath: string,
@@ -616,7 +622,7 @@ function spawnSliceWorker(
 
   let child: ChildProcess;
   try {
-    child = spawn(process.execPath, [binPath, "--mode", "json", "--print", "/gsd auto"], {
+    child = spawn(process.execPath, [binPath, ...SLICE_WORKER_AUTO_ARGS], {
       cwd: worker.worktreePath,
       env: {
         ...process.env,

package/src/resources/extensions/gsd/state.ts

@@ -114,6 +114,48 @@ export function isGhostMilestone(basePath: string, mid: string): boolean {
   return !context && !draft && !roadmap && !summary;
 }
 
+/**
+ * A "reusable ghost" milestone is an orphaned filesystem stub that is safe
+ * to reclaim as the next milestone ID.
+ *
+ * Stricter than `isGhostMilestone`: returns true ONLY when ALL of the
+ * following hold:
+ *   1. No DB row exists for `mid` (any status, including "queued") — a DB row
+ *      means the milestone was intentionally registered by
+ *      `gsd_milestone_generate_id` and may have an in-flight discuss flow.
+ *      Reusing it would collide with that flow. (#4996 race window)
+ *   2. No worktree directory exists at `gsdRoot/worktrees/{mid}` — a worktree
+ *      means the milestone is legitimately in-flight.
+ *   3. No content files exist (CONTEXT, CONTEXT-DRAFT, ROADMAP, SUMMARY) —
+ *      any content means the discuss flow already ran.
+ *
+ * The looser `isGhostMilestone` also classifies queued-row-without-content as
+ * a ghost to help state queries filter phantoms. `isReusableGhostMilestone`
+ * intentionally does NOT reclaim those — a queued row is sufficient proof of
+ * a live in-flight ID reservation.
+ *
+ * Used by `nextMilestoneIdReserved` and both MCP ID-generator tools to fill
+ * gaps left by phantom directories before resorting to max+1.
+ */
+export function isReusableGhostMilestone(basePath: string, mid: string): boolean {
+  // Condition 1: no DB row (any status).
+  if (!isDbAvailable()) return false;
+  const dbRow = getMilestone(mid);
+  if (dbRow != null) return false;
+
+  // Condition 2: no worktree.
+  const root = gsdRoot(basePath);
+  const wtPath = join(root, 'worktrees', mid);
+  if (existsSync(wtPath)) return false;
+
+  // Condition 3: no content files.
+  const context = resolveMilestoneFile(basePath, mid, "CONTEXT");
+  const draft   = resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT");
+  const roadmap = resolveMilestoneFile(basePath, mid, "ROADMAP");
+  const summary = resolveMilestoneFile(basePath, mid, "SUMMARY");
+  return !context && !draft && !roadmap && !summary;
+}
+
 // ─── Query Functions ───────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/templates/PREFERENCES.md

@@ -39,6 +39,7 @@ dynamic_routing:
   budget_pressure:
   cross_provider:
   hooks:
+disabled_model_providers: []
 uok:
   enabled: true
   legacy_fallback:

package/src/resources/extensions/gsd/tests/auto-loop.test.ts

@@ -1,5 +1,8 @@
 import test, { mock } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import {
   resolveAgentEnd,
@@ -26,6 +29,24 @@ function makeEvent(
   return { messages };
 }
 
+async function drainMicrotasks(turns = 20): Promise<void> {
+  for (let i = 0; i < turns; i++) {
+    await Promise.resolve();
+  }
+}
+
+async function waitForMicrotasks(
+  condition: () => boolean,
+  label: string,
+  turns = 500,
+): Promise<void> {
+  for (let i = 0; i < turns; i++) {
+    if (condition()) return;
+    await Promise.resolve();
+  }
+  assert.fail(`Timed out waiting for ${label}`);
+}
+
 /**
  * Build a minimal mock AutoSession with controllable newSession behavior.
  */
@@ -716,7 +737,7 @@ function makeLoopSession(overrides?: Partial<Record<string, unknown>>) {
     verbose: false,
     stepMode: false,
     paused: false,
-    basePath: "/tmp/project",
+    basePath: mkdtempSync(join(tmpdir(), "gsd-auto-loop-")),
     originalBasePath: "",
     currentMilestoneId: "M001",
     currentUnit: null,
@@ -736,6 +757,7 @@ function makeLoopSession(overrides?: Partial<Record<string, unknown>>) {
     unitRecoveryCount: new Map<string, number>(),
     verificationRetryCount: new Map<string, number>(),
     gitService: null,
+    lastRequestTimestamp: 0,
     autoStartTime: Date.now(),
     cmdCtx: {
       newSession: () => Promise.resolve({ cancelled: false }),
@@ -2361,6 +2383,161 @@ test("autoLoop warns but proceeds for greenfield project (no project files) (#18
   );
 });
 
+// ── Proactive rate limiting (#2996) ──────────────────────────────────────────
+
+test("autoLoop enforces min_request_interval_ms delay between LLM dispatches (#2996)", async () => {
+  _resetPendingResolve();
+  mock.timers.enable({ apis: ["Date", "setTimeout"], now: 1_000 });
+
+  try {
+    const ctx = makeMockCtx();
+    ctx.ui.setStatus = () => {};
+    ctx.sessionManager = { getSessionFile: () => "/tmp/session.json" };
+    const pi = makeMockPi();
+    const originalSendMessage = pi.sendMessage;
+    const dispatchTimestamps: number[] = [];
+    pi.sendMessage = (...args: unknown[]) => {
+      dispatchTimestamps.push(Date.now());
+      return originalSendMessage(...args);
+    };
+
+    let iterCount = 0;
+
+    const s = makeLoopSession();
+
+    const deps = makeMockDeps({
+      loadEffectiveGSDPreferences: () => ({
+        preferences: { min_request_interval_ms: 300 },
+      }),
+      deriveState: async () => {
+        iterCount++;
+        deps.callLog.push("deriveState");
+        return {
+          phase: "executing",
+          activeMilestone: { id: "M001", title: "Test", status: "active" },
+          activeSlice: { id: "S01", title: "Slice" },
+          activeTask: { id: "T01" },
+          registry: [{ id: "M001", status: "active" }],
+          blockers: [],
+        } as any;
+      },
+      postUnitPostVerification: async () => {
+        deps.callLog.push("postUnitPostVerification");
+        if (iterCount >= 2) {
+          s.active = false;
+        }
+        return "continue" as const;
+      },
+    });
+
+    const loopPromise = autoLoop(ctx, pi, s, deps);
+
+    await waitForMicrotasks(() => dispatchTimestamps.length === 1, "first dispatch");
+    resolveAgentEnd(makeEvent());
+    await waitForMicrotasks(
+      () => deps.callLog.filter((entry) => entry === "resolveDispatch").length >= 2,
+      "second dispatch planning",
+    );
+
+    await drainMicrotasks(100);
+    mock.timers.tick(299);
+    await drainMicrotasks(100);
+    assert.equal(dispatchTimestamps.length, 1, "second dispatch should wait for the configured interval");
+
+    mock.timers.tick(1);
+    await waitForMicrotasks(() => dispatchTimestamps.length === 2, "second dispatch");
+    resolveAgentEnd(makeEvent());
+
+    await loopPromise;
+
+    assert.ok(iterCount >= 2, `expected at least 2 iterations, got ${iterCount}`);
+    assert.ok(dispatchTimestamps.length >= 2, `expected at least 2 dispatches, got ${dispatchTimestamps.length}`);
+
+    assert.equal(
+      (s as any).lastRequestTimestamp,
+      dispatchTimestamps[1],
+      "lastRequestTimestamp should record the actual dispatch time",
+    );
+
+    const gap = dispatchTimestamps[1]! - dispatchTimestamps[0]!;
+    assert.equal(
+      gap,
+      300,
+      `gap between dispatches should match min_request_interval_ms=300 (got ${gap}ms)`,
+    );
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+test("autoLoop skips rate-limit delay when min_request_interval_ms is 0 (default)", async () => {
+  _resetPendingResolve();
+  mock.timers.enable({ apis: ["Date", "setTimeout"], now: 2_000 });
+
+  try {
+    const ctx = makeMockCtx();
+    ctx.ui.setStatus = () => {};
+    ctx.sessionManager = { getSessionFile: () => "/tmp/session.json" };
+    const pi = makeMockPi();
+    const originalSendMessage = pi.sendMessage;
+    const dispatchTimestamps: number[] = [];
+    pi.sendMessage = (...args: unknown[]) => {
+      dispatchTimestamps.push(Date.now());
+      return originalSendMessage(...args);
+    };
+
+    let iterCount = 0;
+
+    const s = makeLoopSession();
+
+    const deps = makeMockDeps({
+      loadEffectiveGSDPreferences: () => ({
+        preferences: {},
+      }),
+      deriveState: async () => {
+        iterCount++;
+        deps.callLog.push("deriveState");
+        return {
+          phase: "executing",
+          activeMilestone: { id: "M001", title: "Test", status: "active" },
+          activeSlice: { id: "S01", title: "Slice" },
+          activeTask: { id: "T01" },
+          registry: [{ id: "M001", status: "active" }],
+          blockers: [],
+        } as any;
+      },
+      postUnitPostVerification: async () => {
+        deps.callLog.push("postUnitPostVerification");
+        if (iterCount >= 3) {
+          s.active = false;
+        }
+        return "continue" as const;
+      },
+    });
+
+    const loopPromise = autoLoop(ctx, pi, s, deps);
+
+    for (let i = 1; i <= 3; i++) {
+      await waitForMicrotasks(() => dispatchTimestamps.length === i, `dispatch ${i}`);
+      resolveAgentEnd(makeEvent());
+    }
+
+    await loopPromise;
+
+    assert.ok(iterCount >= 3, `expected at least 3 iterations, got ${iterCount}`);
+    assert.ok(dispatchTimestamps.length >= 3, `expected at least 3 dispatches, got ${dispatchTimestamps.length}`);
+
+    const gap = dispatchTimestamps[2]! - dispatchTimestamps[1]!;
+    assert.equal(
+      gap,
+      0,
+      `gap should be 0ms under mocked time without rate limiting (got ${gap}ms)`,
+    );
+  } finally {
+    mock.timers.reset();
+  }
+});
+
 // ─── #4850: pre-send model-policy block is non-retryable ────────────────────
 test("autoLoop classifies ModelPolicyDispatchBlockedError as blocked, not a retryable error", async () => {
   _resetPendingResolve();

package/src/resources/extensions/gsd/tests/auto-recovery.test.ts

@@ -731,6 +731,64 @@ test("hasImplementationArtifacts uses milestone path history instead of rolling
   }
 });
 
+test("hasImplementationArtifacts finds implementation commits when .gsd/ is gitignored (#5033)", () => {
+  const base = makeGitBase();
+  try {
+    // Simulate external/untracked .gsd/ via .git/info/exclude — milestone
+    // planning artifacts never enter git, but real implementation files do.
+    writeFileSync(join(base, ".git", "info", "exclude"), ".gsd/\n");
+    mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md"),
+      "# Summary",
+    );
+
+    mkdirSync(join(base, "benchmarks", "M001"), { recursive: true });
+    writeFileSync(join(base, "benchmarks", "M001", "manifest.yaml"), "cases: []\n");
+
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync(
+      "git",
+      ["commit", "-m", "feat: materialize M001 evidence\n\nGSD-Task: S01/T01"],
+      { cwd: base, stdio: "ignore" },
+    );
+
+    const result = hasImplementationArtifacts(base, "M001");
+    assert.equal(
+      result,
+      "present",
+      "milestone-tagged commit binding must work when .gsd/ is gitignored",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("hasImplementationArtifacts ignores malformed milestone IDs in commit-message fallback", () => {
+  const base = makeGitBase();
+  try {
+    writeFileSync(join(base, ".git", "info", "exclude"), ".gsd/\n");
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "feature.ts"), "export function feature() {}\n");
+
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync(
+      "git",
+      ["commit", "-m", "feat: materialize M001(foo evidence\n\nGSD-Task: S01/T01"],
+      { cwd: base, stdio: "ignore" },
+    );
+
+    const result = hasImplementationArtifacts(base, "M001(");
+    assert.equal(
+      result,
+      "absent",
+      "malformed milestone IDs must not bind implementation commits through message scanning",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("hasImplementationArtifacts returns true on non-git directory (fail-open)", () => {
   const base = join(tmpdir(), `gsd-test-nogit-${randomUUID()}`);
   mkdirSync(base, { recursive: true });

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

@@ -14,10 +14,12 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AutoSession } from "../auto/session.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AUTO_TS_PATH = join(__dirname, "..", "auto.ts");
 const SESSION_TS_PATH = join(__dirname, "..", "auto", "session.ts");
+const RUNTIME_STATE_TS_PATH = join(__dirname, "..", "auto-runtime-state.ts");
 
 function getAutoTsSource(): string {
   return readFileSync(AUTO_TS_PATH, "utf-8");
@@ -27,6 +29,24 @@ function getSessionTsSource(): string {
   return readFileSync(SESSION_TS_PATH, "utf-8");
 }
 
+function getRuntimeStateTsSource(): string {
+  return readFileSync(RUNTIME_STATE_TS_PATH, "utf-8");
+}
+
+test("AutoSession.lockBasePath uses GSD_PROJECT_ROOT for symlink-resolved worktrees", () => {
+  const savedProjectRoot = process.env.GSD_PROJECT_ROOT;
+  process.env.GSD_PROJECT_ROOT = "/real/project";
+  try {
+    const session = new AutoSession();
+    session.basePath = "/Users/dev/.gsd/projects/abc123/worktrees/M001/slices/S01";
+
+    assert.equal(session.lockBasePath, "/real/project");
+  } finally {
+    if (savedProjectRoot === undefined) delete process.env.GSD_PROJECT_ROOT;
+    else process.env.GSD_PROJECT_ROOT = savedProjectRoot;
+  }
+});
+
 // ── Invariant 1: No module-level mutable variables in auto.ts ────────────────
 
 test("auto.ts has no module-level let declarations", () => {
@@ -75,18 +95,18 @@ test("auto.ts has no module-level var declarations", () => {
 
 // ── Invariant 2: AutoSession singleton is the only mutable module-level binding ──
 
-test("auto.ts has exactly one module-level const for AutoSession", () => {
-  const source = getAutoTsSource();
+test("auto-runtime-state.ts has exactly one module-level const for AutoSession", () => {
+  const source = getRuntimeStateTsSource();
   const lines = source.split("\n");
 
   const sessionConsts = lines.filter(line =>
-    /^const\s+\w+\s*=\s*new\s+AutoSession/.test(line),
+    /^(export\s+)?const\s+\w+\s*=\s*new\s+AutoSession/.test(line),
   );
 
   assert.equal(
     sessionConsts.length,
     1,
-    `auto.ts should have exactly one \`const s = new AutoSession()\`. ` +
+    `auto-runtime-state.ts should have exactly one \`const autoSession = new AutoSession()\`. ` +
     `Found ${sessionConsts.length}: ${sessionConsts.join(", ")}`,
   );
 });
@@ -201,7 +221,6 @@ test("auto.ts module-level consts are only AutoSession instance, true constants,
 
   // Patterns that are acceptable at module level
   const allowedPatterns = [
-    /^const s = new AutoSession/,                 // The session singleton
     /^const [A-Z_]+\s*=/,                          // UPPER_CASE constants
     /^const \w+StateAccessors/,                    // Static accessor objects
     /^const \w+:\s*\w+\s*=/,                       // Typed constants

package/src/resources/extensions/gsd/tests/auto-supervisor.test.mjs

@@ -7,10 +7,27 @@ import { writeUnitRuntimeRecord, readUnitRuntimeRecord } from '../unit-runtime.t
 import { resolveAutoSupervisorConfig } from '../preferences.ts';
 
 test('resolveAutoSupervisorConfig provides safe timeout defaults', () => {
-  const supervisor = resolveAutoSupervisorConfig();
-  assert.equal(supervisor.soft_timeout_minutes, 20);
-  assert.equal(supervisor.idle_timeout_minutes, 10);
-  assert.equal(supervisor.hard_timeout_minutes, 30);
+  // Isolate from any developer ~/.gsd/PREFERENCES.md that overrides these
+  // defaults — the test pins what resolveAutoSupervisorConfig() returns when
+  // no preferences file exists, so it must not pick up the runner's home dir.
+  const previousGsdHome = process.env.GSD_HOME;
+  const previousCwd = process.cwd();
+  const isolated = mkdtempSync(join(tmpdir(), 'gsd-supervisor-defaults-'));
+  process.env.GSD_HOME = isolated;
+  process.chdir(isolated);
+  try {
+    const supervisor = resolveAutoSupervisorConfig();
+    assert.equal(supervisor.soft_timeout_minutes, 20);
+    assert.equal(supervisor.idle_timeout_minutes, 10);
+    assert.equal(supervisor.hard_timeout_minutes, 30);
+  } finally {
+    if (previousGsdHome === undefined) {
+      delete process.env.GSD_HOME;
+    } else {
+      process.env.GSD_HOME = previousGsdHome;
+    }
+    process.chdir(previousCwd);
+  }
 });
 
 test('writeUnitRuntimeRecord persists progress and recovery metadata defaults', () => {

package/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts

@@ -32,7 +32,7 @@ describe("bootstrap deriveState DB guards (#3844)", () => {
     assert.ok(compactIdx > -1, "register-hooks should define session_before_compact");
     const compactSection = extractSourceRegion(registerHooksSrc, 'pi.on("session_before_compact"');
     const ensureIdx = compactSection.indexOf("ensureDbOpen()");
-    const deriveIdx = compactSection.indexOf("deriveState(basePath)");
+    const deriveIdx = compactSection.indexOf("deriveGsdState(basePath)");
     assert.ok(ensureIdx > -1, "session_before_compact should call ensureDbOpen()");
     assert.ok(deriveIdx > -1, "session_before_compact should derive state");
     assert.ok(ensureIdx < deriveIdx, "session_before_compact should open DB before deriveState");