gsd-pi 2.28.0-dev.e19bf89 → 2.29.0-dev.49d972f

package/dist/cli.js

@@ -71,6 +71,21 @@ function parseCliArgs(argv) {
 }
 const cliFlags = parseCliArgs(process.argv);
 const isPrintMode = cliFlags.print || cliFlags.mode !== undefined;
+// Early resource-skew check — must run before TTY gate so version mismatch
+// errors surface even in non-TTY environments.
+exitIfManagedResourcesAreNewer(agentDir);
+// Early TTY check — must come before heavy initialization to avoid dangling
+// handles that prevent process.exit() from completing promptly.
+const hasSubcommand = cliFlags.messages.length > 0;
+if (!process.stdin.isTTY && !isPrintMode && !hasSubcommand && !cliFlags.listModels) {
+    process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n');
+    process.stderr.write('[gsd] Non-interactive alternatives:\n');
+    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
+    process.stderr.write('[gsd]   gsd --mode rpc                 JSON-RPC over stdin/stdout\n');
+    process.stderr.write('[gsd]   gsd --mode mcp                 MCP server over stdin/stdout\n');
+    process.stderr.write('[gsd]   gsd --mode text "message"      Text output mode\n');
+    process.exit(1);
+}
 // `gsd <subcommand> --help` — show subcommand-specific help
 const subcommand = cliFlags.messages[0];
 if (subcommand && process.argv.includes('--help')) {
@@ -420,14 +435,5 @@ if (enabledModelPatterns && enabledModelPatterns.length > 0) {
         session.setScopedModels(scopedModels);
     }
 }
-if (!process.stdin.isTTY) {
-    process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n');
-    process.stderr.write('[gsd] Non-interactive alternatives:\n');
-    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
-    process.stderr.write('[gsd]   gsd --mode rpc                 JSON-RPC over stdin/stdout\n');
-    process.stderr.write('[gsd]   gsd --mode mcp                 MCP server over stdin/stdout\n');
-    process.stderr.write('[gsd]   gsd --mode text "message"      Text output mode\n');
-    process.exit(1);
-}
 const interactiveMode = new InteractiveMode(session);
 await interactiveMode.run();

package/dist/resource-loader.js

@@ -1,6 +1,7 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
+import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
@@ -41,7 +42,11 @@ function getBundledGsdVersion() {
     }
 }
 function writeManagedResourceManifest(agentDir) {
-    const manifest = { gsdVersion: getBundledGsdVersion(), syncedAt: Date.now() };
+    const manifest = {
+        gsdVersion: getBundledGsdVersion(),
+        syncedAt: Date.now(),
+        contentHash: computeResourceFingerprint(),
+    };
     writeFileSync(getManagedResourceManifestPath(agentDir), JSON.stringify(manifest));
 }
 export function readManagedResourceVersion(agentDir) {
@@ -53,6 +58,44 @@ export function readManagedResourceVersion(agentDir) {
         return null;
     }
 }
+function readManagedResourceManifest(agentDir) {
+    try {
+        return JSON.parse(readFileSync(getManagedResourceManifestPath(agentDir), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Computes a lightweight content fingerprint of the bundled resources directory.
+ *
+ * Walks all files under resourcesDir and hashes their relative paths + sizes.
+ * This catches same-version content changes (npm link dev workflow, hotfixes
+ * within a release) without the cost of reading every file's contents.
+ *
+ * ~1ms for a typical resources tree (~100 files) — just stat calls, no reads.
+ */
+function computeResourceFingerprint() {
+    const entries = [];
+    collectFileEntries(resourcesDir, resourcesDir, entries);
+    entries.sort();
+    return createHash('sha256').update(entries.join('\n')).digest('hex').slice(0, 16);
+}
+function collectFileEntries(dir, root, out) {
+    if (!existsSync(dir))
+        return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectFileEntries(fullPath, root, out);
+        }
+        else {
+            const rel = relative(root, fullPath);
+            const size = statSync(fullPath).size;
+            out.push(`${rel}:${size}`);
+        }
+    }
+}
 export function getNewerManagedResourceVersion(agentDir, currentVersion) {
     const managedVersion = readManagedResourceVersion(agentDir);
     if (!managedVersion) {
@@ -111,10 +154,34 @@ function syncResourceDir(srcDir, destDir) {
                     rmSync(target, { recursive: true, force: true });
             }
         }
-        cpSync(srcDir, destDir, { recursive: true, force: true });
+        try {
+            cpSync(srcDir, destDir, { recursive: true, force: true });
+        }
+        catch {
+            // Fallback for Windows paths with non-ASCII characters where cpSync
+            // fails with the \\?\ extended-length prefix (#1178).
+            copyDirRecursive(srcDir, destDir);
+        }
         makeTreeWritable(destDir);
     }
 }
+/**
+ * Recursive directory copy using copyFileSync — workaround for cpSync failures
+ * on Windows paths containing non-ASCII characters (#1178).
+ */
+function copyDirRecursive(src, dest) {
+    mkdirSync(dest, { recursive: true });
+    for (const entry of readdirSync(src, { withFileTypes: true })) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *
@@ -132,12 +199,17 @@ function syncResourceDir(srcDir, destDir) {
  */
 export function initResources(agentDir) {
     mkdirSync(agentDir, { recursive: true });
-    // Skip the full copy when the synced version already matches the running version.
-    // This avoids ~800ms of synchronous rmSync + cpSync on every startup.
+    // Skip the full copy when both version AND content fingerprint match.
+    // Version-only checks miss same-version content changes (npm link dev workflow,
+    // hotfixes within a release). The content hash catches those at ~1ms cost.
     const currentVersion = getBundledGsdVersion();
-    const managedVersion = readManagedResourceVersion(agentDir);
-    if (managedVersion && managedVersion === currentVersion) {
-        return;
+    const manifest = readManagedResourceManifest(agentDir);
+    if (manifest && manifest.gsdVersion === currentVersion) {
+        // Version matches — check content fingerprint for same-version staleness.
+        const currentHash = computeResourceFingerprint();
+        if (manifest.contentHash && manifest.contentHash === currentHash) {
+            return;
+        }
     }
     syncResourceDir(bundledExtensionsDir, join(agentDir, 'extensions'));
     syncResourceDir(join(resourcesDir, 'agents'), join(agentDir, 'agents'));

package/dist/resources/extensions/gsd/auto-post-unit.ts

@@ -35,6 +35,7 @@ import {
 import { writeUnitRuntimeRecord, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences } from "./preferences.js";
 import { runGSDDoctor, rebuildState, summarizeDoctorIssues } from "./doctor.js";
+import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
 import { recordHealthSnapshot, checkHealEscalation } from "./doctor-proactive.js";
 import { syncStateToProjectRoot } from "./auto-worktree-sync.js";
 import { resetRewriteCircuitBreaker } from "./auto-dispatch.js";
@@ -154,13 +155,17 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
         ctx.ui.notify(`Post-hook: applied ${report.fixesApplied.length} fix(es).`, "info");
       }
 
-      // Proactive health tracking
-      const summary = summarizeDoctorIssues(report.issues);
+      // Proactive health tracking — exclude completion-transition codes at task level
+      // since they are expected after the last task and resolved by complete-slice
+      const issuesForHealth = effectiveFixLevel === "task"
+        ? report.issues.filter(i => !COMPLETION_TRANSITION_CODES.has(i.code))
+        : report.issues;
+      const summary = summarizeDoctorIssues(issuesForHealth);
       recordHealthSnapshot(summary.errors, summary.warnings, report.fixesApplied.length);
 
       // Check if we should escalate to LLM-assisted heal
       if (summary.errors > 0) {
-        const unresolvedErrors = report.issues
+        const unresolvedErrors = issuesForHealth
           .filter(i => i.severity === "error" && !i.fixable)
           .map(i => ({ code: i.code, message: i.message, unitId: i.unitId }));
         const escalation = checkHealEscalation(summary.errors, unresolvedErrors);
@@ -171,7 +176,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
           );
           try {
             const { formatDoctorIssuesForPrompt, formatDoctorReport } = await import("./doctor.js");
-            const { dispatchDoctorHeal } = await import("./commands.js");
+            const { dispatchDoctorHeal } = await import("./commands-handlers.js");
             const actionable = report.issues.filter(i => i.severity === "error");
             const reportText = formatDoctorReport(report, { scope: doctorScope, includeWarnings: true });
             const structuredIssues = formatDoctorIssuesForPrompt(actionable);

package/dist/resources/extensions/gsd/auto-recovery.ts

@@ -36,8 +36,10 @@ import {
   clearPathCache,
   resolveGsdRootFile,
 } from "./paths.js";
+import { isValidationTerminal } from "./state.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
+import { loadJsonFileOrNull } from "./json-persistence.js";
 import { dirname, join } from "node:path";
 
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
@@ -137,6 +139,21 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   if (!absPath) return false;
   if (!existsSync(absPath)) return false;
 
+  // validate-milestone must have a VALIDATION file with a terminal verdict
+  // (pass, needs-attention, or needs-remediation). Without this check, a
+  // VALIDATION file with missing/malformed frontmatter or an unrecognized
+  // verdict is treated as "complete" by the artifact check but deriveState
+  // still returns phase:"validating-milestone" (because isValidationTerminal
+  // returns false), creating an infinite skip loop that hits the lifetime cap.
+  if (unitType === "validate-milestone") {
+    try {
+      const validationContent = readFileSync(absPath, "utf-8");
+      if (!isValidationTerminal(validationContent)) return false;
+    } catch {
+      return false;
+    }
+  }
+
   // plan-slice must produce a plan with actual task entries, not just a scaffold.
   // The plan file may exist from a prior discussion/context step with only headings
   // but no tasks. Without this check the artifact is considered "complete" and the
@@ -211,7 +228,7 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
         try {
           const roadmapContent = readFileSync(roadmapFile, "utf-8");
           const roadmap = parseRoadmap(roadmapContent);
-          const slice = roadmap.slices.find(s => s.id === sid);
+          const slice = (roadmap.slices ?? []).find(s => s.id === sid);
           if (slice && !slice.done) return false;
         } catch {
           // Corrupt/unparseable roadmap — fail verification so the unit
@@ -338,6 +355,10 @@ export function skipExecuteTask(
 
 // ─── Disk-backed completed-unit helpers ───────────────────────────────────────
 
+function isStringArray(data: unknown): data is string[] {
+  return Array.isArray(data) && data.every(item => typeof item === "string");
+}
+
 /** Path to the persisted completed-unit keys file. */
 export function completedKeysPath(base: string): string {
   return join(base, ".gsd", "completed-units.json");
@@ -346,12 +367,7 @@ export function completedKeysPath(base: string): string {
 /** Write a completed unit key to disk (read-modify-write append to set). */
 export function persistCompletedKey(base: string, key: string): void {
   const file = completedKeysPath(base);
-  let keys: string[] = [];
-  try {
-    if (existsSync(file)) {
-      keys = JSON.parse(readFileSync(file, "utf-8"));
-    }
-  } catch (e) { /* corrupt file — start fresh */ void e; }
+  const keys = loadJsonFileOrNull(file, isStringArray) ?? [];
   const keySet = new Set(keys);
   if (!keySet.has(key)) {
     keys.push(key);
@@ -362,27 +378,21 @@ export function persistCompletedKey(base: string, key: string): void {
 /** Remove a stale completed unit key from disk. */
 export function removePersistedKey(base: string, key: string): void {
   const file = completedKeysPath(base);
-  try {
-    if (existsSync(file)) {
-      const keys: string[] = JSON.parse(readFileSync(file, "utf-8"));
-      const filtered = keys.filter(k => k !== key);
-      // Only write if the key was actually present
-      if (filtered.length !== keys.length) {
-        atomicWriteSync(file, JSON.stringify(filtered));
-      }
-    }
-  } catch (e) { /* non-fatal: removePersistedKey failure */ void e; }
+  const keys = loadJsonFileOrNull(file, isStringArray);
+  if (!keys) return;
+  const filtered = keys.filter(k => k !== key);
+  if (filtered.length !== keys.length) {
+    atomicWriteSync(file, JSON.stringify(filtered));
+  }
 }
 
 /** Load all completed unit keys from disk into the in-memory set. */
 export function loadPersistedKeys(base: string, target: Set<string>): void {
   const file = completedKeysPath(base);
-  try {
-    if (existsSync(file)) {
-      const keys: string[] = JSON.parse(readFileSync(file, "utf-8"));
-      for (const k of keys) target.add(k);
-    }
-  } catch (e) { /* non-fatal: loadPersistedKeys failure */ void e; }
+  const keys = loadJsonFileOrNull(file, isStringArray);
+  if (keys) {
+    for (const k of keys) target.add(k);
+  }
 }
 
 // ─── Merge State Reconciliation ───────────────────────────────────────────────

package/dist/resources/extensions/gsd/auto-start.ts

@@ -26,6 +26,13 @@ import {
 import { invalidateAllCaches } from "./cache.js";
 import { synthesizeCrashRecovery } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, formatCrashInfo, isLockProcessAlive } from "./crash-recovery.js";
+import {
+  acquireSessionLock,
+  updateSessionLock,
+  releaseSessionLock,
+  readSessionLockData,
+  isSessionLockProcessAlive,
+} from "./session-lock.js";
 import { selfHealRuntimeRecords } from "./auto-recovery.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
@@ -81,6 +88,18 @@ export async function bootstrapAutoSession(
 ): Promise<boolean> {
   const { shouldUseWorktreeIsolation, registerSigtermHandler, lockBase } = deps;
 
+  // ── Session lock: acquire FIRST, before any state mutation ──────────────
+  // This is the primary guard against concurrent sessions on the same project.
+  // Uses OS-level file locking (proper-lockfile) to prevent TOCTOU races.
+  const lockResult = acquireSessionLock(base);
+  if (!lockResult.acquired) {
+    ctx.ui.notify(
+      `${lockResult.reason}\nStop it with \`kill ${lockResult.existingPid ?? "the other process"}\` before starting a new session.`,
+      "error",
+    );
+    return false;
+  }
+
   // Ensure git repo exists
   if (!nativeIsRepo(base)) {
     const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
@@ -109,16 +128,11 @@ export async function bootstrapAutoSession(
   // Initialize GitServiceImpl
   s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
 
-  // Check for crash from previous session
+  // Check for crash from previous session (use both old and new lock data)
   const crashLock = readCrashLock(base);
   if (crashLock) {
-    if (isLockProcessAlive(crashLock)) {
-      ctx.ui.notify(
-        `Another auto-mode session (PID ${crashLock.pid}) appears to be running.\nStop it with \`kill ${crashLock.pid}\` before starting a new session.`,
-        "error",
-      );
-      return false;
-    }
+    // We already hold the session lock, so no concurrent session is running.
+    // The crash lock is from a dead process — recover context from it.
     const recoveredMid = crashLock.unitId.split("/")[0];
     const milestoneAlreadyComplete = recoveredMid
       ? !!resolveMilestoneFile(base, recoveredMid, "SUMMARY")
@@ -401,13 +415,14 @@ export async function bootstrapAutoSession(
   ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
   ctx.ui.setFooter(hideFooter);
   const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
-  const pendingCount = state.registry.filter(m => m.status !== 'complete' && m.status !== 'parked').length;
+  const pendingCount = (state.registry ?? []).filter(m => m.status !== 'complete' && m.status !== 'parked').length;
   const scopeMsg = pendingCount > 1
     ? `Will loop through ${pendingCount} milestones.`
     : "Will loop until milestone complete.";
   ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
 
-  // Write initial lock file
+  // Update lock file with milestone info (OS lock already acquired at bootstrap start)
+  updateSessionLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown", 0);
   writeLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown", 0);
 
   // Secrets collection gate — pause instead of blocking (#1146)

package/dist/resources/extensions/gsd/auto-verification.ts

@@ -105,19 +105,39 @@ export async function runPostUnitVerification(
     const completionKey = `${s.currentUnit.type}/${s.currentUnit.id}`;
 
     if (result.checks.length > 0) {
-      const passCount = result.checks.filter(c => c.exitCode === 0).length;
-      const total = result.checks.length;
+      const blockingChecks = result.checks.filter(c => c.blocking);
+      const advisoryChecks = result.checks.filter(c => !c.blocking);
+      const blockingPassCount = blockingChecks.filter(c => c.exitCode === 0).length;
+      const advisoryFailCount = advisoryChecks.filter(c => c.exitCode !== 0).length;
+
       if (result.passed) {
-        ctx.ui.notify(`Verification gate: ${passCount}/${total} checks passed`);
+        let msg = blockingChecks.length > 0
+          ? `Verification gate: ${blockingPassCount}/${blockingChecks.length} blocking checks passed`
+          : `Verification gate: passed (no blocking checks)`;
+        if (advisoryFailCount > 0) {
+          msg += ` (${advisoryFailCount} advisory warning${advisoryFailCount > 1 ? "s" : ""})`;
+        }
+        ctx.ui.notify(msg);
+        // Log advisory warnings to stderr for visibility
+        if (advisoryFailCount > 0) {
+          const advisoryFailures = advisoryChecks.filter(c => c.exitCode !== 0);
+          process.stderr.write(`verification-gate: ${advisoryFailCount} advisory (non-blocking) failure(s)\n`);
+          for (const f of advisoryFailures) {
+            process.stderr.write(`  [advisory] ${f.command} exited ${f.exitCode}\n`);
+          }
+        }
       } else {
-        const failures = result.checks.filter(c => c.exitCode !== 0);
-        const failNames = failures.map(f => f.command).join(", ");
+        const blockingFailures = blockingChecks.filter(c => c.exitCode !== 0);
+        const failNames = blockingFailures.map(f => f.command).join(", ");
         ctx.ui.notify(`Verification gate: FAILED — ${failNames}`);
-        process.stderr.write(`verification-gate: ${total - passCount}/${total} checks failed\n`);
-        for (const f of failures) {
+        process.stderr.write(`verification-gate: ${blockingFailures.length}/${blockingChecks.length} blocking checks failed\n`);
+        for (const f of blockingFailures) {
           process.stderr.write(`  ${f.command} exited ${f.exitCode}\n`);
           if (f.stderr) process.stderr.write(`  stderr: ${f.stderr.slice(0, 500)}\n`);
         }
+        if (advisoryFailCount > 0) {
+          process.stderr.write(`verification-gate: ${advisoryFailCount} additional advisory (non-blocking) failure(s)\n`);
+        }
       }
     }
 
@@ -155,6 +175,20 @@ export async function runPostUnitVerification(
       s.verificationRetryCount.delete(s.currentUnit.id);
       s.pendingVerificationRetry = null;
       return "continue";
+    } else if (result.discoverySource === "package-json") {
+      // Auto-discovered checks from package.json may fail on pre-existing errors
+      // that the current task didn't introduce. Don't trigger the retry loop —
+      // log a warning and let the task proceed (#1186).
+      process.stderr.write(
+        `verification-gate: auto-discovered checks failed (source: package-json) — treating as advisory, not blocking\n`,
+      );
+      ctx.ui.notify(
+        `Verification: auto-discovered checks failed (pre-existing errors likely). Continuing without retry.`,
+        "warning",
+      );
+      s.verificationRetryCount.delete(s.currentUnit.id);
+      s.pendingVerificationRetry = null;
+      return "continue";
     } else if (autoFixEnabled && attempt + 1 <= maxRetries) {
       const nextAttempt = attempt + 1;
       s.verificationRetryCount.set(s.currentUnit.id, nextAttempt);

package/dist/resources/extensions/gsd/auto-worktree-sync.ts

@@ -11,6 +11,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, cpSync, unlinkSync, readdirSync } from "node:fs";
+import { loadJsonFileOrNull } from "./json-persistence.js";
 import { join, sep as pathSep } from "node:path";
 import { homedir } from "node:os";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
@@ -36,6 +37,12 @@ export function syncProjectRootToWorktree(projectRoot: string, worktreePath: str
   // has newer artifacts (e.g. slices that don't exist in the worktree yet)
   safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId))
 
+  // Copy living documents from project root to worktree so agents have the
+  // latest decisions, requirements, project state, and knowledge.
+  for (const doc of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md"]) {
+    safeCopy(join(prGsd, doc), join(wtGsd, doc), { force: true });
+  }
+
   // Delete worktree gsd.db so it rebuilds from the freshly synced files.
   // Stale DB rows are the root cause of the infinite skip loop (#853).
   try {
@@ -89,6 +96,14 @@ export function syncStateToProjectRoot(worktreePath: string, projectRoot: string
   // worktree. If the next session resolves basePath before worktree re-entry,
   // selfHeal can't find or clear the stale record (#769).
   safeCopyRecursive(join(wtGsd, "runtime", "units"), join(prGsd, "runtime", "units"), { force: true })
+
+  // 5. Living documents — decisions, requirements, project description, knowledge.
+  // Agents update these during slice execution. Without syncing, a new session
+  // reads stale copies from the project root, losing architectural decisions,
+  // requirement status updates, and accumulated knowledge (#1168).
+  for (const doc of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md"]) {
+    safeCopy(join(wtGsd, doc), join(prGsd, doc), { force: true });
+  }
 }
 
 // ─── Resource Staleness ───────────────────────────────────────────────────
@@ -98,15 +113,15 @@ export function syncStateToProjectRoot(worktreePath: string, projectRoot: string
  * 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");
-  try {
-    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-    return typeof manifest?.gsdVersion === "string" ? manifest.gsdVersion : null;
-  } catch {
-    return null;
-  }
+  const manifest = loadJsonFileOrNull(manifestPath, isManifestWithVersion);
+  return manifest?.gsdVersion ?? null;
 }
 
 /**