gsd-pi 2.29.0-dev.953d788 → 2.29.0-dev.f08b4fe

package/dist/resources/extensions/gsd/preferences-models.ts

@@ -254,13 +254,19 @@ export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPrefer
           subagent: "claude-sonnet-4-5-20250514",
         },
         phases: {
+          skip_research: true,
+          skip_reassess: true,
           skip_slice_research: true,
         },
       };
     case "quality":
       return {
         models: {},
-        phases: {},
+        phases: {
+          skip_research: true,
+          skip_slice_research: true,
+          skip_reassess: true,
+        },
       };
   }
 }

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

@@ -172,9 +172,10 @@ export function validatePreferences(preferences: GSDPreferences): {
       if (p.skip_reassess !== undefined) validatedPhases.skip_reassess = !!p.skip_reassess;
       if (p.skip_slice_research !== undefined) validatedPhases.skip_slice_research = !!p.skip_slice_research;
       if (p.skip_milestone_validation !== undefined) validatedPhases.skip_milestone_validation = !!p.skip_milestone_validation;
+      if (p.reassess_after_slice !== undefined) validatedPhases.reassess_after_slice = !!p.reassess_after_slice;
       if ((p as any).require_slice_discussion !== undefined) (validatedPhases as any).require_slice_discussion = !!(p as any).require_slice_discussion;
       // Warn on unknown phase keys
-      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research", "skip_milestone_validation", "require_slice_discussion"]);
+      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research", "skip_milestone_validation", "reassess_after_slice", "require_slice_discussion"]);
       for (const key of Object.keys(p)) {
         if (!knownPhaseKeys.has(key)) {
           warnings.push(`unknown phases key "${key}" — ignored`);

package/dist/resources/extensions/gsd/preferences.ts

@@ -13,6 +13,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import type { PostUnitHookConfig, PreDispatchHookConfig } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
@@ -81,11 +82,15 @@ export {
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
 const LEGACY_GLOBAL_PREFERENCES_PATH = join(homedir(), ".pi", "agent", "gsd-preferences.md");
-const PROJECT_PREFERENCES_PATH = join(process.cwd(), ".gsd", "preferences.md");
+function projectPreferencesPath(): string {
+  return join(gsdRoot(process.cwd()), "preferences.md");
+}
 // Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
 // Check uppercase as a fallback so those files aren't silently ignored.
 const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(homedir(), ".gsd", "PREFERENCES.md");
-const PROJECT_PREFERENCES_PATH_UPPERCASE = join(process.cwd(), ".gsd", "PREFERENCES.md");
+function projectPreferencesPathUppercase(): string {
+  return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+}
 
 export function getGlobalGSDPreferencesPath(): string {
   return GLOBAL_PREFERENCES_PATH;
@@ -96,7 +101,7 @@ export function getLegacyGlobalGSDPreferencesPath(): string {
 }
 
 export function getProjectGSDPreferencesPath(): string {
-  return PROJECT_PREFERENCES_PATH;
+  return projectPreferencesPath();
 }
 
 // ─── Loading ────────────────────────────────────────────────────────────────
@@ -108,8 +113,8 @@ export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
 }
 
 export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {
-  return loadPreferencesFile(PROJECT_PREFERENCES_PATH, "project")
-    ?? loadPreferencesFile(PROJECT_PREFERENCES_PATH_UPPERCASE, "project");
+  return loadPreferencesFile(projectPreferencesPath(), "project")
+    ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project");
 }
 
 export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -16,13 +16,15 @@ Summarize your understanding of the specification concretely:
 - Scope estimate (how many milestones × slices)
 - Any ambiguities or gaps you notice
 
-### Step 2: Investigate
+### Step 2: Investigate (brief)
 
-Scout the codebase to understand what already exists:
+Quickly scout the codebase to understand what already exists — spend no more than 5-6 tool calls here:
 - `ls` the project root and key directories
 - Search for relevant existing code, patterns, dependencies
 - Check library docs if needed (`resolve_library` / `get_library_docs`)
 
+Then move on to writing artifacts. Do not explore exhaustively — the research phase will do deeper investigation later.
+
 ### Step 3: Make Decisions
 
 For any ambiguities or gaps in the specification:

package/dist/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -91,7 +91,7 @@ Before moving to the wrap-up gate, verify you have covered:
 - options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
 - **The question ID must contain `depth_verification`** (e.g. `depth_verification_confirm`) — this enables the write-gate downstream.
 
-**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? Anything I missed?" Wait for confirmation before proceeding.
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for confirmation before proceeding.
 
 If they clarify, absorb the correction and re-verify.
 

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -12,9 +12,33 @@ All relevant context has been preloaded below — start working immediately with
 
 ## Your Role in the Pipeline
 
-A **researcher agent** already explored the codebase and documented findings in the milestone research doc (inlined above, if present). It identified key files, technology choices, constraints, and risks. **Trust the research.** Your job is strategic decomposition — turning findings into an ordered set of demoable slices — not re-exploration. Don't read code files the research already summarized unless something is ambiguous or missing.
+You are the first deep look at this milestone. You have full tool access — explore the codebase, look up docs, investigate technology choices. Your job is to understand the landscape and then strategically decompose the work into demoable slices.
 
-After you finish, each slice goes through its own research → plan → execute cycle. Slice researchers dive deeper into the specific area. Slice planners decompose into tasks. Executors build each task. Your roadmap sets the strategic frame for all of them.
+After you finish, each slice goes through its own plan → execute cycle. Slice planners decompose into tasks. Executors build each task. Your roadmap sets the strategic frame for all of them.
+
+### Explore First, Then Decompose
+
+Before decomposing, build your understanding:
+
+1. **Codebase exploration.** For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
+2. **Library docs.** Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase.
+3. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
+4. **Requirements analysis.** If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors.
+
+### Strategic Questions to Answer
+
+- What should be proven first?
+- What existing patterns should be reused?
+- What boundary contracts matter?
+- What constraints does the existing codebase impose?
+- Are there known failure modes that should shape slice ordering?
+- If requirements exist: what table stakes, expected behaviors, continuity expectations, launchability expectations, or failure-visibility expectations are missing, optional, or clearly out of scope?
+
+### Source Files
+
+{{sourceFilePaths}}
+
+If milestone research exists (inlined above), trust those findings and skip redundant exploration. If findings are significant and no research file exists yet, write `{{researchOutputPath}}`.
 
 Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why. Use complete sentences rather than planner shorthand or fragmentary notes.
 

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

@@ -18,7 +18,21 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
-A **researcher agent** already explored the codebase and documented findings in the slice research doc (inlined above, if present). It identified key files, build order, constraints, and verification approach. **Trust the research.** Your job is decomposition — turning findings into executable tasks — not re-exploration. Don't read code files the research already summarized unless something is ambiguous or missing from its findings.
+You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
+
+### Verify Roadmap Assumptions
+
+Check prior slice summaries (inlined above as dependency summaries, if present). If prior slices discovered constraints, changed approaches, or flagged fragility, adjust your plan accordingly. The roadmap description may be stale — verify it against the current codebase state.
+
+### Explore Slice Scope
+
+Read the code files relevant to this slice. Confirm the roadmap's description of what exists, what needs to change, and what boundaries apply. Use `rg`, `find`, and targeted reads.
+
+### Source Files
+
+{{sourceFilePaths}}
+
+If slice research exists (inlined above), trust those findings and skip redundant exploration.
 
 After you finish, **executor agents** implement each task in isolated fresh context windows. They see only their task plan, the slice plan excerpt (goal/demo/verification), and compressed summaries of prior tasks. They do not see the research doc, the roadmap, or REQUIREMENTS.md. Everything an executor needs must be in the task plan itself — file paths, specific steps, expected inputs and outputs.
 

package/dist/resources/extensions/gsd/prompts/workflow-start.md

@@ -0,0 +1,28 @@
+# Workflow Template: {{templateName}}
+
+You are executing a **{{templateName}}** workflow (template: `{{templateId}}`).
+
+## Context
+
+- **Description:** {{description}}
+- **Issue reference:** {{issueRef}}
+- **Date:** {{date}}
+- **Branch:** {{branch}}
+- **Artifact directory:** {{artifactDir}}
+- **Phases:** {{phases}}
+- **Complexity:** {{complexity}}
+
+## Workflow Definition
+
+Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. At each phase gate, confirm with the user before proceeding.
+
+{{workflowContent}}
+
+## Execution Rules
+
+1. **Follow the phases in order.** Do not skip phases unless the workflow explicitly allows it.
+2. **Artifact discipline.** If an artifact directory is specified, write all planning/summary documents there.
+3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
+4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
+5. **Gate between phases.** After each phase, summarize what was done and ask the user to confirm before moving to the next phase.
+6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/dist/resources/extensions/gsd/queue-order.ts

@@ -9,10 +9,10 @@
  * survives branch switches and is shared across sessions.
  */
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { milestoneIdSort } from "./milestone-ids.js";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -45,6 +45,12 @@ function queueOrderPath(basePath: string): string {
   return join(gsdRoot(basePath), "QUEUE-ORDER.json");
 }
 
+// ─── Type Guards ─────────────────────────────────────────────────────────────
+
+function isQueueOrderFile(data: unknown): data is QueueOrderFile {
+  return data !== null && typeof data === "object" && "order" in data! && Array.isArray((data as QueueOrderFile).order);
+}
+
 // ─── Read / Write ────────────────────────────────────────────────────────────
 
 /**
@@ -52,15 +58,8 @@ function queueOrderPath(basePath: string): string {
  * the file is corrupt/unreadable.
  */
 export function loadQueueOrder(basePath: string): string[] | null {
-  const p = queueOrderPath(basePath);
-  if (!existsSync(p)) return null;
-  try {
-    const data: QueueOrderFile = JSON.parse(readFileSync(p, "utf-8"));
-    if (!Array.isArray(data.order)) return null;
-    return data.order;
-  } catch {
-    return null;
-  }
+  const data = loadJsonFileOrNull(queueOrderPath(basePath), isQueueOrderFile);
+  return data?.order ?? null;
 }
 
 /**
@@ -71,7 +70,7 @@ export function saveQueueOrder(basePath: string, order: string[]): void {
     order,
     updatedAt: new Date().toISOString(),
   };
-  writeFileSync(queueOrderPath(basePath), JSON.stringify(data, null, 2) + "\n", "utf-8");
+  saveJsonFile(queueOrderPath(basePath), data);
 }
 
 // ─── Sorting ─────────────────────────────────────────────────────────────────

package/dist/resources/extensions/gsd/repo-identity.ts

@@ -0,0 +1,148 @@
+/**
+ * GSD Repo Identity — external state directory primitives.
+ *
+ * Computes a stable per-repo identity hash, resolves the external
+ * `~/.gsd/projects/<hash>/` state directory, and manages the
+ * `<project>/.gsd → external` symlink.
+ */
+
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+// ─── Repo Identity ──────────────────────────────────────────────────────────
+
+/**
+ * Get the git remote URL for "origin", or "" if no remote is configured.
+ * Uses `git config` rather than `git remote get-url` for broader compat.
+ */
+function getRemoteUrl(basePath: string): string {
+  try {
+    return execFileSync("git", ["config", "--get", "remote.origin.url"], {
+      cwd: basePath,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Resolve the git toplevel (real root) for the given path.
+ * For worktrees this returns the main repo root, not the worktree path.
+ */
+function resolveGitRoot(basePath: string): string {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: basePath,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    }).trim();
+  } catch {
+    return resolve(basePath);
+  }
+}
+
+/**
+ * Compute a stable identity for a repository.
+ *
+ * SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated to 12 hex chars.
+ * Deterministic: same repo always produces the same hash regardless of
+ * which worktree the caller is inside.
+ */
+export function repoIdentity(basePath: string): string {
+  const remoteUrl = getRemoteUrl(basePath);
+  const root = resolveGitRoot(basePath);
+  const input = `${remoteUrl}\n${root}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 12);
+}
+
+// ─── External State Directory ───────────────────────────────────────────────
+
+/**
+ * Compute the external GSD state directory for a repository.
+ *
+ * Returns `$GSD_STATE_DIR/projects/<hash>` if `GSD_STATE_DIR` is set,
+ * otherwise `~/.gsd/projects/<hash>`.
+ */
+export function externalGsdRoot(basePath: string): string {
+  const base = process.env.GSD_STATE_DIR || join(homedir(), ".gsd");
+  return join(base, "projects", repoIdentity(basePath));
+}
+
+// ─── Symlink Management ─────────────────────────────────────────────────────
+
+/**
+ * Ensure the `<project>/.gsd` symlink points to the external state directory.
+ *
+ * 1. mkdir -p the external dir
+ * 2. If `<project>/.gsd` doesn't exist → create symlink
+ * 3. If `<project>/.gsd` is already the correct symlink → no-op
+ * 4. If `<project>/.gsd` is a real directory → return as-is (migration handles later)
+ *
+ * Returns the resolved external path.
+ */
+export function ensureGsdSymlink(projectPath: string): string {
+  const externalPath = externalGsdRoot(projectPath);
+  const localGsd = join(projectPath, ".gsd");
+
+  // Ensure external directory exists
+  mkdirSync(externalPath, { recursive: true });
+
+  if (!existsSync(localGsd)) {
+    // Nothing exists yet — create symlink
+    symlinkSync(externalPath, localGsd, "junction");
+    return externalPath;
+  }
+
+  try {
+    const stat = lstatSync(localGsd);
+
+    if (stat.isSymbolicLink()) {
+      // Already a symlink — verify it points to the right place
+      const target = realpathSync(localGsd);
+      if (target === externalPath) {
+        return externalPath; // correct symlink, no-op
+      }
+      // Symlink exists but points elsewhere — leave it for now
+      // (could be a custom override or stale symlink)
+      return target;
+    }
+
+    if (stat.isDirectory()) {
+      // Real directory — migration will handle this later.
+      // Return the local path so existing code still works.
+      return localGsd;
+    }
+  } catch {
+    // lstat failed — path exists but we can't stat it
+  }
+
+  return localGsd;
+}
+
+// ─── Worktree Detection ─────────────────────────────────────────────────────
+
+/**
+ * Check if the given directory is a git worktree (not the main repo).
+ *
+ * Git worktrees have a `.git` *file* (not directory) containing a
+ * `gitdir:` pointer. This is git's native worktree indicator — no
+ * string marker parsing needed.
+ */
+export function isInsideWorktree(cwd: string): boolean {
+  const gitPath = join(cwd, ".git");
+  try {
+    const stat = lstatSync(gitPath);
+    if (!stat.isFile()) return false;
+    const content = readFileSync(gitPath, "utf-8").trim();
+    return content.startsWith("gitdir:");
+  } catch {
+    return false;
+  }
+}

package/dist/resources/extensions/gsd/resource-version.ts

@@ -0,0 +1,99 @@
+/**
+ * Resource version tracking and stale worktree detection.
+ *
+ * Staleness detection for managed GSD resources and utilities
+ * for escaping stale worktree cwd after milestone teardown.
+ */
+
+import { existsSync, readdirSync, unlinkSync } from "node:fs";
+import { loadJsonFileOrNull } from "./json-persistence.js";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveProjectRoot } from "./worktree.js";
+
+// ─── Resource Staleness ───────────────────────────────────────────────────
+
+/**
+ * Read the resource version (semver) from the managed-resources manifest.
+ * Uses gsdVersion instead of syncedAt so that launching a second session
+ * doesn't falsely trigger staleness (#804).
+ */
+function isManifestWithVersion(data: unknown): data is { gsdVersion: string } {
+  return data !== null && typeof data === "object" && "gsdVersion" in data! && typeof (data as Record<string, unknown>).gsdVersion === "string";
+}
+
+export function readResourceVersion(): string | null {
+  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+  const manifestPath = join(agentDir, "managed-resources.json");
+  const manifest = loadJsonFileOrNull(manifestPath, isManifestWithVersion);
+  return manifest?.gsdVersion ?? null;
+}
+
+/**
+ * Check if managed resources have been updated since session start.
+ * Returns a warning message if stale, null otherwise.
+ */
+export function checkResourcesStale(versionOnStart: string | null): string | null {
+  if (versionOnStart === null) return null;
+  const current = readResourceVersion();
+  if (current === null) return null;
+  if (current !== versionOnStart) {
+    return "GSD resources were updated since this session started. Restart gsd to load the new code.";
+  }
+  return null;
+}
+
+// ─── Stale Worktree Escape ────────────────────────────────────────────────
+
+/**
+ * Detect and escape a stale worktree cwd (#608).
+ *
+ * After milestone completion + merge, the worktree directory is removed but
+ * the process cwd may still point inside `.gsd/worktrees/<MID>/`.
+ * When a new session starts, `process.cwd()` is passed as `base` to startAuto
+ * and all subsequent writes land in the wrong directory. This function detects
+ * that scenario and chdir back to the project root.
+ *
+ * Returns the corrected base path.
+ */
+export function escapeStaleWorktree(base: string): string {
+  const projectRoot = resolveProjectRoot(base);
+  if (projectRoot === base) return base;
+  try {
+    process.chdir(projectRoot);
+  } catch {
+    return base;
+  }
+  return projectRoot;
+}
+
+/**
+ * Clean stale runtime unit files for completed milestones.
+ *
+ * After restart, stale runtime/units/*.json from prior milestones can
+ * cause deriveState to resume the wrong milestone (#887). Removes files
+ * for milestones that have a SUMMARY (fully complete).
+ */
+export function cleanStaleRuntimeUnits(
+  gsdRootPath: string,
+  hasMilestoneSummary: (mid: string) => boolean,
+): number {
+  const runtimeUnitsDir = join(gsdRootPath, "runtime", "units");
+  if (!existsSync(runtimeUnitsDir)) return 0;
+
+  let cleaned = 0;
+  try {
+    for (const file of readdirSync(runtimeUnitsDir)) {
+      if (!file.endsWith(".json")) continue;
+      const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
+      if (!midMatch) continue;
+      if (hasMilestoneSummary(midMatch[1])) {
+        try {
+          unlinkSync(join(runtimeUnitsDir, file));
+          cleaned++;
+        } catch { /* non-fatal */ }
+      }
+    }
+  } catch { /* non-fatal */ }
+  return cleaned;
+}

package/dist/resources/extensions/gsd/session-forensics.ts

@@ -20,6 +20,7 @@
 
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { truncateWithEllipsis } from "../shared/format-utils.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
 import { MAX_JSONL_BYTES, parseJSONL } from "./jsonl-utils.js";
@@ -292,7 +293,7 @@ export function getDeepDiagnostic(basePath: string): string | null {
     if (mid) {
       const wtPath = getAutoWorktreePath(basePath, mid);
       if (wtPath) {
-        const wtActivityDir = join(wtPath, ".gsd", "activity");
+        const wtActivityDir = join(gsdRoot(wtPath), "activity");
         trace = readLastActivityLog(wtActivityDir);
       }
     }
@@ -300,7 +301,7 @@ export function getDeepDiagnostic(basePath: string): string | null {
 
   // Fall back to root activity logs
   if (!trace || trace.toolCallCount === 0) {
-    const activityDir = join(basePath, ".gsd", "activity");
+    const activityDir = join(gsdRoot(basePath), "activity");
     trace = readLastActivityLog(activityDir);
   }
 
@@ -314,7 +315,7 @@ export function getDeepDiagnostic(basePath: string): string | null {
  */
 function readActiveMilestoneId(basePath: string): string | null {
   try {
-    const statePath = join(basePath, ".gsd", "STATE.md");
+    const statePath = join(gsdRoot(basePath), "STATE.md");
     if (!existsSync(statePath)) return null;
     const content = readFileSync(statePath, "utf-8");
     const match = /\*\*Active Milestone:\*\*\s*(\S+)/i.exec(content);

package/dist/resources/extensions/gsd/session-status-io.ts

@@ -11,9 +11,6 @@
  */
 
 import {
-  writeFileSync,
-  readFileSync,
-  renameSync,
   unlinkSync,
   readdirSync,
   mkdirSync,
@@ -21,6 +18,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { loadJsonFileOrNull, writeJsonFileAtomic } from "./json-persistence.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -49,9 +47,16 @@ export interface SignalMessage {
 const PARALLEL_DIR = "parallel";
 const STATUS_SUFFIX = ".status.json";
 const SIGNAL_SUFFIX = ".signal.json";
-const TMP_SUFFIX = ".tmp";
 const DEFAULT_STALE_TIMEOUT_MS = 30_000;
 
+function isSessionStatus(data: unknown): data is SessionStatus {
+  return data !== null && typeof data === "object" && "milestoneId" in data && "pid" in data;
+}
+
+function isSignalMessage(data: unknown): data is SignalMessage {
+  return data !== null && typeof data === "object" && "signal" in data && "sentAt" in data;
+}
+
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 function parallelDir(basePath: string): string {
@@ -86,25 +91,13 @@ function isPidAlive(pid: number): boolean {
 
 /** Write session status atomically (write to .tmp, then rename). */
 export function writeSessionStatus(basePath: string, status: SessionStatus): void {
-  try {
-    ensureParallelDir(basePath);
-    const dest = statusPath(basePath, status.milestoneId);
-    const tmp = dest + TMP_SUFFIX;
-    writeFileSync(tmp, JSON.stringify(status, null, 2), "utf-8");
-    renameSync(tmp, dest);
-  } catch { /* non-fatal */ }
+  ensureParallelDir(basePath);
+  writeJsonFileAtomic(statusPath(basePath, status.milestoneId), status);
 }
 
 /** Read a specific milestone's session status. */
 export function readSessionStatus(basePath: string, milestoneId: string): SessionStatus | null {
-  try {
-    const p = statusPath(basePath, milestoneId);
-    if (!existsSync(p)) return null;
-    const raw = readFileSync(p, "utf-8");
-    return JSON.parse(raw) as SessionStatus;
-  } catch {
-    return null;
-  }
+  return loadJsonFileOrNull(statusPath(basePath, milestoneId), isSessionStatus);
 }
 
 /** Read all session status files from .gsd/parallel/. */
@@ -114,13 +107,10 @@ export function readAllSessionStatuses(basePath: string): SessionStatus[] {
 
   const results: SessionStatus[] = [];
   try {
-    const entries = readdirSync(dir);
-    for (const entry of entries) {
+    for (const entry of readdirSync(dir)) {
       if (!entry.endsWith(STATUS_SUFFIX)) continue;
-      try {
-        const raw = readFileSync(join(dir, entry), "utf-8");
-        results.push(JSON.parse(raw) as SessionStatus);
-      } catch { /* skip corrupt files */ }
+      const status = loadJsonFileOrNull(join(dir, entry), isSessionStatus);
+      if (status) results.push(status);
     }
   } catch { /* non-fatal */ }
   return results;
@@ -138,27 +128,19 @@ export function removeSessionStatus(basePath: string, milestoneId: string): void
 
 /** Write a signal file for a worker to consume. */
 export function sendSignal(basePath: string, milestoneId: string, signal: SessionSignal): void {
-  try {
-    ensureParallelDir(basePath);
-    const dest = signalPath(basePath, milestoneId);
-    const tmp = dest + TMP_SUFFIX;
-    const msg: SignalMessage = { signal, sentAt: Date.now(), from: "coordinator" };
-    writeFileSync(tmp, JSON.stringify(msg, null, 2), "utf-8");
-    renameSync(tmp, dest);
-  } catch { /* non-fatal */ }
+  ensureParallelDir(basePath);
+  const msg: SignalMessage = { signal, sentAt: Date.now(), from: "coordinator" };
+  writeJsonFileAtomic(signalPath(basePath, milestoneId), msg);
 }
 
 /** Read and delete a signal file (atomic consume). Returns null if no signal pending. */
 export function consumeSignal(basePath: string, milestoneId: string): SignalMessage | null {
-  try {
-    const p = signalPath(basePath, milestoneId);
-    if (!existsSync(p)) return null;
-    const raw = readFileSync(p, "utf-8");
-    unlinkSync(p);
-    return JSON.parse(raw) as SignalMessage;
-  } catch {
-    return null;
+  const p = signalPath(basePath, milestoneId);
+  const msg = loadJsonFileOrNull(p, isSignalMessage);
+  if (msg) {
+    try { unlinkSync(p); } catch { /* non-fatal */ }
   }
+  return msg;
 }
 
 // ─── Stale Detection ───────────────────────────────────────────────────────