gsd-pi 2.77.0-dev.1d17f366c → 2.77.0-dev.58d3d4d6c

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -987,6 +987,27 @@ export function validatePreferences(preferences: GSDPreferences): {
     if (g.merge_to_main !== undefined) {
       warnings.push("git.merge_to_main is deprecated — milestone-level merge is now always used. Remove this setting.");
     }
+    // #4765 — collapse cadence + milestone resquash
+    if (g.collapse_cadence !== undefined) {
+      const validCadence = new Set(["milestone", "slice"]);
+      if (typeof g.collapse_cadence === "string" && validCadence.has(g.collapse_cadence)) {
+        git.collapse_cadence = g.collapse_cadence as "milestone" | "slice";
+      } else {
+        errors.push("git.collapse_cadence must be one of: milestone, slice");
+      }
+    }
+    if (g.milestone_resquash !== undefined) {
+      if (typeof g.milestone_resquash === "boolean") {
+        git.milestone_resquash = g.milestone_resquash;
+        const cadence = (git.collapse_cadence as string | undefined)
+          ?? (typeof g.collapse_cadence === "string" ? g.collapse_cadence : undefined);
+        if (cadence !== "slice") {
+          warnings.push('git.milestone_resquash is ignored unless git.collapse_cadence is "slice"');
+        }
+      } else {
+        errors.push("git.milestone_resquash must be a boolean");
+      }
+    }
 
     if (Object.keys(git).length > 0) {
       validated.git = git as GitPreferences;

package/src/resources/extensions/gsd/prompt-cache-optimizer.ts

@@ -55,6 +55,10 @@ const SEMI_STATIC_LABELS = new Set([
   "prior-summaries",
   "project-context",
   "overrides",
+  // KNOWLEDGE is milestone-scoped (stable within a session), so it belongs
+  // in the cacheable prefix. See issue #4719.
+  "knowledge",
+  "project-knowledge",
 ]);
 
 /** Labels that change per-task */

package/src/resources/extensions/gsd/slice-cadence.ts

@@ -0,0 +1,299 @@
+/**
+ * Slice-cadence collapse — #4765.
+ *
+ * When `git.collapse_cadence: "slice"` is set, each slice's commits are
+ * squash-merged from the milestone branch to main as soon as the slice
+ * passes validation. Shrinks the orphan window (#4761) from milestone-size
+ * to slice-size and surfaces merge conflicts per-slice rather than all at
+ * once at milestone end.
+ *
+ * This module is deliberately focused and narrower than mergeMilestoneToMain:
+ *   - No worktree teardown (worktree is reused for the next slice)
+ *   - No DB reconciliation (modern worktrees share the main DB via path resolver)
+ *   - No roadmap/summary/gate handling (that's still the milestone's job)
+ *   - Fails loudly on dirty main — caller is responsible for cleanliness
+ *
+ * Kernighan: the v1 surface handles the happy path + conflict. Edge cases
+ * that mergeMilestoneToMain covers (concurrent merges, shared DB paths,
+ * submodules) are explicit non-goals; users opt in via preference and early-
+ * adopter scenarios are scoped narrow.
+ */
+
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { MergeConflictError } from "./git-service.js";
+import {
+  nativeBranchForceReset,
+  nativeCheckoutBranch,
+  nativeCommit,
+  nativeCommitCountBetween,
+  nativeConflictFiles,
+  nativeDetectMainBranch,
+  nativeMergeSquash,
+} from "./native-git-bridge.js";
+import { resolveGitDir } from "./worktree-manager.js";
+import { logWarning } from "./workflow-logger.js";
+import { emitSliceMerged, emitMilestoneResquash } from "./worktree-telemetry.js";
+
+/**
+ * Auto-worktree milestone branch name. Must match autoWorktreeBranch() in
+ * auto-worktree.ts; duplicated here to avoid a cyclic import.
+ */
+function milestoneBranchName(milestoneId: string): string {
+  return `milestone/${milestoneId}`;
+}
+
+function cleanupMergeArtifacts(projectRoot: string): void {
+  try {
+    const gitDir = resolveGitDir(projectRoot);
+    for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+      const p = join(gitDir, f);
+      if (existsSync(p)) unlinkSync(p);
+    }
+  } catch (err) {
+    logWarning("worktree", `merge artifact cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export interface SliceMergeResult {
+  commitSha: string | null;
+  mainBranch: string;
+  milestoneBranch: string;
+  durationMs: number;
+  skipped: boolean;
+  skippedReason?: string;
+}
+
+/**
+ * Squash-merge one slice's commits from the milestone branch to main.
+ *
+ * Preconditions:
+ *   - Caller is on the milestone branch inside the worktree
+ *   - `projectRoot` points at the real project root (not the worktree)
+ *
+ * Post-conditions on success:
+ *   - Slice's commits are a single squash commit on main
+ *   - `milestone/<MID>` is fast-forwarded to main (so next slice's work
+ *     starts from a clean base)
+ *   - caller's process.cwd is restored
+ *
+ * Throws MergeConflictError on conflicts; caller should surface and stop.
+ * Throws GSDError on dirty main / detection failures.
+ */
+export function mergeSliceToMain(
+  projectRoot: string,
+  milestoneId: string,
+  sliceId: string,
+): SliceMergeResult {
+  const started = Date.now();
+  const worktreeCwd = process.cwd();
+  const milestoneBranch = milestoneBranchName(milestoneId);
+  const mainBranch = nativeDetectMainBranch(projectRoot);
+
+  // Fast path: if the milestone branch has no commits ahead of main, there
+  // is nothing to merge. Return a skip result instead of no-op'ing silently
+  // so the caller's telemetry shows the decision.
+  let commitsAhead = 0;
+  try {
+    commitsAhead = nativeCommitCountBetween(projectRoot, mainBranch, milestoneBranch);
+  } catch {
+    // If we can't count, assume there's work and let the merge proceed —
+    // a failing merge is more informative than a silent skip.
+    commitsAhead = 1;
+  }
+  if (commitsAhead === 0) {
+    // Do NOT emit slice-merged here — this is a no-op, not a merge. Emitting
+    // would inflate slicesMerged in telemetry/forensics and distort the
+    // conflict rate denominator.
+    return {
+      commitSha: null,
+      mainBranch,
+      milestoneBranch,
+      durationMs: Date.now() - started,
+      skipped: true,
+      skippedReason: "no-commits-ahead",
+    };
+  }
+
+  process.chdir(projectRoot);
+  try {
+    // Dirty-main check — v1 fails loudly rather than auto-stashing. Users
+    // running slice-cadence opt in knowing main stays clean between merges.
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+    if (status) {
+      throw new GSDError(
+        GSD_GIT_ERROR,
+        `slice-cadence merge requires a clean project root; uncommitted changes detected. ` +
+        `Commit or stash at ${projectRoot} before retrying. Status:\n${status}`,
+      );
+    }
+
+    nativeCheckoutBranch(projectRoot, mainBranch);
+
+    // Clean any stale merge artifacts before attempting the squash (#2912 pattern)
+    cleanupMergeArtifacts(projectRoot);
+
+    const mergeResult = nativeMergeSquash(projectRoot, milestoneBranch);
+    if (!mergeResult.success) {
+      const conflictedFiles = mergeResult.conflicts.length > 0
+        ? mergeResult.conflicts
+        : nativeConflictFiles(projectRoot);
+      cleanupMergeArtifacts(projectRoot);
+      try {
+        emitSliceMerged(projectRoot, milestoneId, sliceId, {
+          durationMs: Date.now() - started,
+          conflict: true,
+        });
+      } catch { /* silent */ }
+      throw new MergeConflictError(
+        conflictedFiles,
+        "squash",
+        milestoneBranch,
+        mainBranch,
+      );
+    }
+
+    // Commit the squash with a slice-scoped message
+    const commitSha = nativeCommit(
+      projectRoot,
+      `gsd: merge ${sliceId} of ${milestoneId} (slice-cadence)`,
+    );
+
+    // Advance the milestone branch to main so the next slice's commits start
+    // from a clean base. Force-reset is safe because we just merged this
+    // branch's entire delta.
+    nativeBranchForceReset(projectRoot, milestoneBranch, mainBranch);
+
+    const durationMs = Date.now() - started;
+    try {
+      emitSliceMerged(projectRoot, milestoneId, sliceId, {
+        durationMs,
+        conflict: false,
+        commitSha: commitSha ?? undefined,
+      });
+    } catch { /* silent */ }
+
+    return {
+      commitSha,
+      mainBranch,
+      milestoneBranch,
+      durationMs,
+      skipped: false,
+    };
+  } finally {
+    // Always restore cwd even if anything above threw.
+    try { process.chdir(worktreeCwd); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Re-squash per-slice commits on main into a single milestone commit.
+ *
+ * Runs at milestone completion when `collapse_cadence: "slice"` AND
+ * `milestone_resquash: true`. The `startSha` is the SHA of main immediately
+ * before the milestone's first slice merge — the caller is responsible for
+ * recording this (AutoSession field, git ref, or DB row).
+ *
+ * Strategy: soft-reset main to startSha, then commit the net diff. The
+ * N slice commits between startSha and HEAD are collapsed into one.
+ *
+ * No-op (returns false) if startSha equals HEAD (nothing to re-squash).
+ */
+export function resquashMilestoneOnMain(
+  projectRoot: string,
+  milestoneId: string,
+  startSha: string,
+): { resquashed: boolean; newSha: string | null } {
+  const mainBranch = nativeDetectMainBranch(projectRoot);
+  const worktreeCwd = process.cwd();
+
+  process.chdir(projectRoot);
+  try {
+    nativeCheckoutBranch(projectRoot, mainBranch);
+
+    // Verify the startSha..HEAD range contains ONLY this milestone's slice-
+    // cadence commits. If any unrelated commits landed on main since the
+    // milestone started (e.g. concurrent work, cherry-picks, hotfixes), a
+    // blind `git reset --soft` would fold them into the re-squash and rewrite
+    // their attribution. Fail closed — the user can resolve manually.
+    const expectedSuffix = `(slice-cadence)`;
+    const expectedMilestoneToken = ` of ${milestoneId} `;
+    let subjectsRaw = "";
+    try {
+      subjectsRaw = execFileSync(
+        "git",
+        ["log", "--format=%s", `${startSha}..HEAD`],
+        { cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      );
+    } catch {
+      return { resquashed: false, newSha: null };
+    }
+    const subjects = subjectsRaw.split("\n").filter((s) => s.length > 0);
+    const sliceCount = subjects.length;
+    if (sliceCount === 0) {
+      return { resquashed: false, newSha: null };
+    }
+    const foreign = subjects.filter(
+      (s) => !(s.endsWith(expectedSuffix) && s.includes(expectedMilestoneToken)),
+    );
+    if (foreign.length > 0) {
+      logWarning(
+        "worktree",
+        `slice-cadence: skipping milestone resquash for ${milestoneId} — ` +
+        `${foreign.length} non-slice-cadence commit(s) in ${startSha}..HEAD ` +
+        `would be folded in. First: "${foreign[0]}". Resolve history manually.`,
+      );
+      return { resquashed: false, newSha: null };
+    }
+
+    // Safe to collapse: all commits in the range are this milestone's slices.
+    execFileSync("git", ["reset", "--soft", startSha], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+
+    const newSha = nativeCommit(
+      projectRoot,
+      `gsd: complete milestone ${milestoneId} (${sliceCount} slices re-squashed)`,
+      { allowEmpty: true },
+    );
+
+    try {
+      emitMilestoneResquash(projectRoot, milestoneId, {
+        sliceCount,
+        startSha,
+        endSha: newSha ?? undefined,
+      });
+    } catch { /* silent */ }
+
+    return { resquashed: true, newSha };
+  } finally {
+    try { process.chdir(worktreeCwd); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Read the effective collapse cadence from validated preferences. Accepts
+ * a raw preferences object (the shape loadEffectiveGSDPreferences returns).
+ */
+export function getCollapseCadence(
+  prefs: { git?: { collapse_cadence?: "milestone" | "slice" } } | undefined | null,
+): "milestone" | "slice" {
+  return prefs?.git?.collapse_cadence ?? "milestone";
+}
+
+export function getMilestoneResquash(
+  prefs: { git?: { milestone_resquash?: boolean } } | undefined | null,
+): boolean {
+  // Default true when cadence is slice — resquash preserves the milestone-
+  // level history shape users expect.
+  return prefs?.git?.milestone_resquash !== false;
+}

package/src/resources/extensions/gsd/tests/artifacts-table-preserved-on-cache-invalidate.test.ts

@@ -22,6 +22,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { invalidateAllCaches } from "../cache.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
 import {
   openDatabase,
   closeDatabase,
@@ -160,7 +161,7 @@ describe("cache.ts must not re-import clearArtifacts into invalidateAllCaches",
   test("invalidateAllCaches does not call clearArtifacts", () => {
     const fnIdx = src.indexOf("function invalidateAllCaches");
     assert.ok(fnIdx !== -1);
-    const body = src.slice(fnIdx, fnIdx + 1000);
+    const body = extractSourceRegion(src, "function invalidateAllCaches", { fromIdx: fnIdx });
     assert.ok(
       !/\bclearArtifacts\s*\(/.test(body),
       "invalidateAllCaches must not call clearArtifacts() — it wipes the write-through store",

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

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { extractSourceRegion } from "./test-helpers.ts";
 import {
   resolveAgentEnd,
   resolveAgentEndCancelled,
@@ -595,7 +596,7 @@ test("auto/phases.ts: selectAndApplyModel called exactly once and before updateP
   // Extract the runUnitPhase function body
   const fnStart = src.indexOf("export async function runUnitPhase");
   assert.ok(fnStart > 0, "runUnitPhase should exist in phases.ts");
-  const fnBody = src.slice(fnStart, fnStart + 16000);
+  const fnBody = extractSourceRegion(src, "export async function runUnitPhase");
 
   // selectAndApplyModel must appear exactly once
   const allOccurrences = [...fnBody.matchAll(/selectAndApplyModel\(/g)];
@@ -1538,9 +1539,7 @@ test("auto.ts startAuto dispatches through the UOK kernel wrapper with explicit
   // Find the startAuto function body
   const fnIdx = src.indexOf("export async function startAuto");
   assert.ok(fnIdx > -1, "startAuto must exist in auto.ts");
-  const fnEnd = src.indexOf("\n// ─── ", fnIdx + 100);
-  const fnBlock =
-    fnEnd > -1 ? src.slice(fnIdx, fnEnd) : src.slice(fnIdx, fnIdx + 5000);
+  const fnBlock = extractSourceRegion(src, "export async function startAuto", "\n// ─── ");
   assert.ok(
     fnBlock.includes("runAutoLoopWithUok("),
     "startAuto must dispatch through runAutoLoopWithUok()",
@@ -1562,9 +1561,7 @@ test("startAuto calls selfHealRuntimeRecords before autoLoop (#1727)", { skip: "
   );
   const fnIdx = src.indexOf("export async function startAuto");
   assert.ok(fnIdx > -1, "startAuto must exist in auto.ts");
-  const fnEnd = src.indexOf("\n// ─── ", fnIdx + 100);
-  const fnBlock =
-    fnEnd > -1 ? src.slice(fnIdx, fnEnd) : src.slice(fnIdx, fnIdx + 5000);
+  const fnBlock = extractSourceRegion(src, "export async function startAuto", "\n// ─── ");
 
   // Both autoLoop call sites must be preceded by selfHealRuntimeRecords
   const healIdx = fnBlock.indexOf("selfHealRuntimeRecords");
@@ -1589,7 +1586,7 @@ test("startAuto guards against concurrent invocation (#2923)", () => {
   const fnIdx = src.indexOf("export async function startAuto");
   assert.ok(fnIdx > -1, "startAuto must exist in auto.ts");
   // The guard must appear before any other logic in the function body
-  const fnBody = src.slice(fnIdx, fnIdx + 500);
+  const fnBody = extractSourceRegion(src, "export async function startAuto");
   const activeGuard = fnBody.indexOf("if (s.active)");
   assert.ok(activeGuard > -1, "startAuto must check s.active to prevent concurrent auto-loops");
   const returnIdx = fnBody.indexOf("return;", activeGuard);

package/src/resources/extensions/gsd/tests/auto-remediate-slice-status.test.ts

@@ -15,6 +15,7 @@ import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -43,7 +44,9 @@ describe('auto-remediate stale slice status (#3673)', () => {
     assert.match(before, /try\s*\{/,
       'updateSliceStatus should be inside a try block');
 
-    const after = source.slice(updateIdx, updateIdx + 300);
+    // Bound the region to stop before the rogue fallback so /catch/ only
+    // matches this try block's catch, not an unrelated later one.
+    const after = extractSourceRegion(source, 'updateSliceStatus(mid, sid', 'rogues.push({');
     assert.match(after, /catch/,
       'try block should have a catch for fallback');
   });

package/src/resources/extensions/gsd/tests/auto-retry-mcp-churn-fixes.test.ts

@@ -16,6 +16,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { extractSourceRegion } from "./test-helpers.ts";
 import {
   resetEvidence,
   getEvidence,
@@ -107,7 +108,9 @@ describe("register-hooks: skip prepareWorkflowMcpForProject inside auto-worktree
   it("session_start hook is gated on isInAutoWorktree", () => {
     const idx = src.indexOf('pi.on("session_start"');
     assert.ok(idx !== -1, "session_start handler must exist");
-    const block = src.slice(idx, idx + 2500);
+    // Bound the extraction at the next pi.on(...) so adjacent handlers
+    // can't bleed into this handler's assertions.
+    const block = extractSourceRegion(src, 'pi.on("session_start"', 'pi.on("session_switch"');
     assert.ok(
       block.includes("isInAutoWorktree"),
       "session_start must consult isInAutoWorktree before preparing MCP",
@@ -121,7 +124,7 @@ describe("register-hooks: skip prepareWorkflowMcpForProject inside auto-worktree
   it("session_switch hook is gated on isInAutoWorktree", () => {
     const idx = src.indexOf('pi.on("session_switch"');
     assert.ok(idx !== -1, "session_switch handler must exist");
-    const block = src.slice(idx, idx + 2500);
+    const block = extractSourceRegion(src, 'pi.on("session_switch"', 'pi.on("tool_call"');
     assert.ok(
       block.includes("isInAutoWorktree"),
       "session_switch must consult isInAutoWorktree before preparing MCP",
@@ -192,7 +195,7 @@ describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", (
   it("projectDirParam is optional and documents the default", () => {
     const idx = src.indexOf("const projectDirParam");
     assert.ok(idx !== -1, "projectDirParam definition must exist");
-    const block = src.slice(idx, idx + 600);
+    const block = extractSourceRegion(src, "const projectDirParam");
     assert.ok(
       block.includes(".optional()"),
       "projectDirParam must be optional so the agent stops deliberating",
@@ -206,7 +209,7 @@ describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", (
   it("parseWorkflowArgs defaults projectDir to process.cwd() when omitted", () => {
     const idx = src.indexOf("function parseWorkflowArgs");
     assert.ok(idx !== -1, "parseWorkflowArgs must exist");
-    const block = src.slice(idx, idx + 1500);
+    const block = extractSourceRegion(src, "function parseWorkflowArgs");
     assert.ok(
       block.includes("parsed.projectDir ?? process.cwd()"),
       "parseWorkflowArgs must fall back to process.cwd() when projectDir is omitted",
@@ -216,7 +219,7 @@ describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", (
   it("validateProjectDir accepts external-state worktree paths via .gsd symlink target", () => {
     const idx = src.indexOf("function validateProjectDir");
     assert.ok(idx !== -1, "validateProjectDir must exist");
-    const block = src.slice(idx, idx + 2500);
+    const block = extractSourceRegion(src, "function validateProjectDir");
     assert.ok(
       block.includes("resolveExternalStateRoot"),
       "validateProjectDir must consult resolveExternalStateRoot for external-state layouts",
@@ -224,7 +227,7 @@ describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", (
 
     const helperIdx = src.indexOf("function resolveExternalStateRoot");
     assert.ok(helperIdx !== -1, "resolveExternalStateRoot helper must exist");
-    const helperBlock = src.slice(helperIdx, helperIdx + 600);
+    const helperBlock = extractSourceRegion(src, "function resolveExternalStateRoot");
     assert.ok(
       helperBlock.includes("realpathSync"),
       "resolveExternalStateRoot must use realpathSync to follow the symlink",
@@ -240,7 +243,7 @@ describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", (
     // milestone that has an auto-worktree at <projectRoot>/.gsd/worktrees/<MID>/,
     // tool writes must go to the worktree .gsd rather than the shared project .gsd.
     const parseIdx = src.indexOf("function parseWorkflowArgs");
-    const parseBlock = src.slice(parseIdx, parseIdx + 2500);
+    const parseBlock = extractSourceRegion(src, "function parseWorkflowArgs");
     assert.ok(
       parseBlock.includes("resolveActiveWorktreeBasePath"),
       "parseWorkflowArgs must consult resolveActiveWorktreeBasePath",
@@ -254,7 +257,7 @@ describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", (
   it("resolveActiveWorktreeBasePath checks .git presence to avoid hijacking stray directories", () => {
     const idx = src.indexOf("function resolveActiveWorktreeBasePath");
     assert.ok(idx !== -1, "resolveActiveWorktreeBasePath helper must exist");
-    const block = src.slice(idx, idx + 1200);
+    const block = extractSourceRegion(src, "function resolveActiveWorktreeBasePath");
     assert.ok(
       block.includes('existsSync(join(wtPath, ".git"))'),
       "resolveActiveWorktreeBasePath must verify a .git file exists in the worktree",
@@ -264,7 +267,7 @@ describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", (
   it("extractMilestoneId handles camelCase, snake_case, and short aliases", () => {
     const idx = src.indexOf("function extractMilestoneId");
     assert.ok(idx !== -1, "extractMilestoneId helper must exist");
-    const block = src.slice(idx, idx + 600);
+    const block = extractSourceRegion(src, "function extractMilestoneId");
     assert.ok(block.includes("milestoneId"), "must check milestoneId");
     assert.ok(block.includes("milestone_id"), "must check milestone_id");
     assert.ok(block.includes("mid"), "must check mid");

package/src/resources/extensions/gsd/tests/auto-start-clean-runtime-db-gated.test.ts

@@ -10,6 +10,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const sourceFile = join(__dirname, "..", "auto-start.ts");
@@ -37,7 +38,7 @@ describe("auto-start cleanStaleRuntimeUnits DB gating (#4663)", () => {
   test("cleanStaleRuntimeUnits predicate consults DB status when available", () => {
     const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
     assert.ok(cleanIdx > -1);
-    const snippet = source.slice(cleanIdx, cleanIdx + 600);
+    const snippet = extractSourceRegion(source, "cleanStaleRuntimeUnits(");
     assert.match(
       snippet,
       /isDbAvailable\(\)/,
@@ -53,7 +54,7 @@ describe("auto-start cleanStaleRuntimeUnits DB gating (#4663)", () => {
   test("cleanStaleRuntimeUnits predicate still falls back to SUMMARY-file when DB unavailable", () => {
     const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
     assert.ok(cleanIdx > -1);
-    const snippet = source.slice(cleanIdx, cleanIdx + 600);
+    const snippet = extractSourceRegion(source, "cleanStaleRuntimeUnits(");
     assert.match(
       snippet,
       /resolveMilestoneFile\(base,\s*mid,\s*["']SUMMARY["']\)/,

package/src/resources/extensions/gsd/tests/auto-start-cold-db-bootstrap.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -13,7 +13,7 @@ console.log("\n=== #2841: cold DB opened before initial deriveState ===");
 const helperIdx = src.indexOf("async function openProjectDbIfPresent");
 assertTrue(helperIdx >= 0, "auto-start.ts defines a helper for pre-derive DB open (#2841)");
 
-const helperRegion = helperIdx >= 0 ? src.slice(helperIdx, helperIdx + 500) : "";
+const helperRegion = helperIdx >= 0 ? extractSourceRegion(src, "async function openProjectDbIfPresent") : "";
 assertTrue(
   helperRegion.includes("resolveProjectRootDbPath(basePath)"),
   "pre-derive DB helper resolves the project-root DB path (#2841)",

package/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts

@@ -2,6 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const sourcePath = join(import.meta.dirname, "..", "auto-start.ts");
 const source = readFileSync(sourcePath, "utf-8");
@@ -53,7 +54,7 @@ test("bootstrapAutoSession checks manual session override before preferences", (
   );
 
   // Preferred model should still be part of fallback resolution.
-  const snapshotBlock = source.slice(snapshotIdx, snapshotIdx + 400);
+  const snapshotBlock = extractSourceRegion(source, "const startModelSnapshot = manualSessionOverride");
   assert.ok(
     snapshotBlock.includes("validatedPreferredModel") || snapshotBlock.includes("preferredModel"),
     "startModelSnapshot must still consider preferredModel for built-in providers",
@@ -64,7 +65,7 @@ test("bootstrapAutoSession prioritizes current session model over PREFERENCES.md
   const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
   assert.ok(snapshotIdx > -1, "auto-start.ts should build startModelSnapshot");
 
-  const snapshotBlock = source.slice(snapshotIdx, snapshotIdx + 500);
+  const snapshotBlock = extractSourceRegion(source, "const startModelSnapshot = manualSessionOverride");
   const currentIdx = snapshotBlock.indexOf("currentSessionModel");
   const preferredIdx = snapshotBlock.indexOf("validatedPreferredModel");
 
@@ -97,7 +98,7 @@ test("bootstrapAutoSession prefers session model over PREFERENCES.md when provid
   const preferredIdx = source.indexOf("const preferredModel = ");
   assert.ok(preferredIdx > -1, "auto-start.ts should build preferredModel");
 
-  const preferredBlock = source.slice(preferredIdx, preferredIdx + 200);
+  const preferredBlock = extractSourceRegion(source, "const preferredModel = ");
   assert.ok(
     preferredBlock.includes("sessionProviderIsCustom"),
     "preferredModel must be gated on sessionProviderIsCustom so PREFERENCES.md is skipped for custom providers",

package/src/resources/extensions/gsd/tests/auto-start-worktree-db-path.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -13,7 +13,7 @@ console.log("\n=== #3822: worktree bootstrap uses project DB path ===");
 const dbLifecycleIdx = src.indexOf("// ── DB lifecycle ──");
 assertTrue(dbLifecycleIdx > 0, "auto-start.ts has a DB lifecycle section");
 
-const dbLifecycleRegion = dbLifecycleIdx > 0 ? src.slice(dbLifecycleIdx, dbLifecycleIdx + 600) : "";
+const dbLifecycleRegion = dbLifecycleIdx > 0 ? extractSourceRegion(src, "// ── DB lifecycle ──") : "";
 
 assertTrue(
   dbLifecycleRegion.includes("const gsdDbPath = resolveProjectRootDbPath(s.basePath);"),

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

@@ -2,6 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const autoSrc = readFileSync(join(import.meta.dirname, "..", "auto.ts"), "utf-8");
 const phasesSrc = readFileSync(join(import.meta.dirname, "..", "auto", "phases.ts"), "utf-8");
@@ -20,7 +21,7 @@ test("stopAuto restores original thinking level", () => {
 test("runUnitPhase threads captured thinking level into selectAndApplyModel", () => {
   const callIdx = phasesSrc.indexOf("deps.selectAndApplyModel(");
   assert.ok(callIdx > -1, "phases.ts should call selectAndApplyModel");
-  const callBlock = phasesSrc.slice(callIdx, callIdx + 600);
+  const callBlock = extractSourceRegion(phasesSrc, "deps.selectAndApplyModel(");
   assert.ok(
     callBlock.includes("s.autoModeStartThinkingLevel"),
     "runUnitPhase should pass autoModeStartThinkingLevel to selectAndApplyModel",
@@ -30,7 +31,7 @@ test("runUnitPhase threads captured thinking level into selectAndApplyModel", ()
 test("hook model override preserves captured thinking level", () => {
   const hookIdx = phasesSrc.indexOf("const hookModelOverride = sidecarItem?.model ?? iterData.hookModelOverride;");
   assert.ok(hookIdx > -1, "phases.ts should include hook model override handling");
-  const hookBlock = phasesSrc.slice(hookIdx, hookIdx + 600);
+  const hookBlock = extractSourceRegion(phasesSrc, "const hookModelOverride = sidecarItem?.model ?? iterData.hookModelOverride;");
   assert.ok(
     hookBlock.includes("pi.setThinkingLevel(s.autoModeStartThinkingLevel)"),
     "hook model override should re-apply captured thinking level after setModel",