@opengsd/gsd-pi 1.3.0 → 1.4.0

package/dist/resources/extensions/gsd/db-workspace.js

@@ -1,10 +1,24 @@
 // Project/App: gsd-pi
 // File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
 import { existsSync } from "node:fs";
-import { dirname } from "node:path";
-import { backupDatabaseSnapshot, checkpointDatabase, closeAllDatabases, closeDatabase, closeDatabaseByWorkspace, getDbPath, getDbStatus, getDbProvider, isDbAvailable, openDatabase, openDatabaseByScope, openDatabaseByWorkspace, refreshOpenDatabaseFromDisk, vacuumDatabase, wasDbOpenAttempted, } from "./gsd-db.js";
-import { resolveGsdPathContract } from "./paths.js";
-import { setLogBasePath } from "./workflow-logger.js";
+import { dirname, join } from "node:path";
+import { backupDatabaseSnapshot, checkpointDatabase, closeAllDatabases, closeDatabase, closeDatabaseByWorkspace, getDbPath, getDbStatus, getDbProvider, isDbAvailable, openDatabase, openDatabaseByScope, openDatabaseByWorkspace, openIsolatedDatabase, refreshOpenDatabaseFromDisk, vacuumDatabase, wasDbOpenAttempted, } from "./gsd-db.js";
+import { resolveGsdPathContract, gsdRoot } from "./paths.js";
+import { logWarning, setLogBasePath } from "./workflow-logger.js";
+/**
+ * Global SQLite handle invariants:
+ *
+ * - `openWorkflowDatabase` / `openDatabase` switch the process-global handle consumed by
+ *   deriveState, dispatch, reconciliation repairs, and domain writers. Only one active
+ *   project database should own the global handle at a time.
+ * - `openWorkflowDatabaseIsolated` opens a caller-owned connection that does not clobber
+ *   the global handle. Use for read-only observers (parallel monitor) and other background
+ *   probes that must not disturb the active workflow session.
+ * - Reconciliation repairs that write markdown/DB state must use `ensureWorkflowDbForBase`
+ *   so repairs target the correct project; those paths intentionally re-open the global handle.
+ * - Pair ad-hoc project switches with `closeWorkflowDatabase()` or restore via
+ *   `ensureWorkflowDbForBase(..., { refresh: true })` before returning to derive/dispatch.
+ */
 export function resolveWorkflowDatabaseLocation(basePath) {
     const contract = resolveGsdPathContract(basePath);
     return {
@@ -59,6 +73,18 @@ export function openExistingWorkflowDatabase(basePath) {
 export function openWorkflowDatabasePath(path) {
     return openDatabase(path);
 }
+/**
+ * Open an isolated database connection for read-only observation without
+ * displacing the active workflow session's global DB handle. The caller is
+ * responsible for calling `adapter.close()` when done.
+ *
+ * Use this for background observers (e.g. the parallel monitor overlay) that
+ * need to query a database on a 5s tick without interfering with the primary
+ * connection. Returns null if the connection cannot be opened.
+ */
+export function openWorkflowDatabaseIsolated(path) {
+    return openIsolatedDatabase(path);
+}
 export function openWorkflowDatabaseByWorkspace(workspace) {
     return openDatabaseByWorkspace(workspace);
 }
@@ -92,6 +118,44 @@ export function getWorkflowDatabasePath() {
 export function refreshWorkflowDatabaseFromDisk() {
     return refreshOpenDatabaseFromDisk();
 }
+export function expectedWorkflowDbPathForBase(basePath) {
+    return join(gsdRoot(basePath), "gsd.db");
+}
+export function ensureWorkflowDbAtPath(dbPath) {
+    if (!dbPath || dbPath === ":memory:")
+        return isDbAvailable();
+    if (isDbAvailable() && getWorkflowDatabasePath() === dbPath)
+        return true;
+    if (!existsSync(dbPath))
+        return false;
+    try {
+        return openWorkflowDatabasePath(dbPath);
+    }
+    catch (err) {
+        logWarning("reconcile", `ensureWorkflowDbAtPath could not reopen DB: ${err.message}`);
+        return false;
+    }
+}
+export function ensureWorkflowDbForBase(basePath, options = {}) {
+    const dbPath = expectedWorkflowDbPathForBase(basePath);
+    if (!existsSync(dbPath))
+        return false;
+    try {
+        if (options.refresh) {
+            if (isDbAvailable() && getWorkflowDatabasePath() === dbPath && refreshWorkflowDatabaseFromDisk()) {
+                return true;
+            }
+            return openWorkflowDatabasePath(dbPath);
+        }
+        if (isDbAvailable() && getWorkflowDatabasePath() === dbPath)
+            return true;
+        return openWorkflowDatabasePath(dbPath);
+    }
+    catch (err) {
+        logWarning("reconcile", `ensureWorkflowDbForBase could not reopen DB: ${err.message}`);
+        return false;
+    }
+}
 export function checkpointWorkflowDatabase() {
     checkpointDatabase();
 }

package/dist/resources/extensions/gsd/delegation-policy.js

@@ -94,7 +94,7 @@ const POLICY = {
     gsd_plan_task: {
         toolName: "gsd_plan_task",
         verdict: "no",
-        rationale: "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+        rationale: "Incremental task planning mutates the active slice plan and re-renders projections; keep it ordered in the foreground plan-slice unit.",
     },
 };
 function resolveCanonical(name) {

package/dist/resources/extensions/gsd/discussion-handoff.js

@@ -6,7 +6,7 @@ import { startAutoDetached } from "./auto.js";
 import { extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { getMilestone, insertMilestone, isDbAvailable } from "./gsd-db.js";
 import { assessMilestoneHandoffReadiness, formatAcceptedDiscussHandoffMessage, } from "./milestone-readiness.js";
-import { gsdRoot, resolveGsdRootFile, resolveMilestoneFile } from "./paths.js";
+import { clearPathCache, gsdRoot, resolveGsdRootFile, resolveMilestoneFile } from "./paths.js";
 import { _getPendingAutoStart, deletePendingAutoStart } from "./pending-auto-start.js";
 import { logWarning } from "./workflow-logger.js";
 import { readManifest } from "./workflow-manifest.js";
@@ -186,14 +186,18 @@ function cleanupAcceptedHandoffArtifacts(entry) {
 }
 /** Called from agent_end to check if auto-mode should start after discuss. */
 export function checkAutoStartAfterDiscuss(lookupBasePath) {
+    // Clear the path cache so layout-aware resolution sees fresh directory
+    // listings — the cache may have been primed before discuss wrote its
+    // artifacts (e.g. CONTEXT.md), causing resolveMilestoneFile to miss them.
+    clearPathCache();
     const entry = _getPendingAutoStart(lookupBasePath);
     if (!entry)
         return false;
     const { ctx, pi, basePath, milestoneId, step } = entry;
-    const contextFilePath = entry.scope.contextFile();
-    const roadmapFilePath = entry.scope.roadmapFile();
-    const contextFile = existsSync(contextFilePath) ? contextFilePath : null;
-    const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
+    // Use layout-aware resolution so flat-phase projects (phases/NN-slug/)
+    // are found as well as legacy projects (milestones/MID/).
+    const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+    const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     if (!contextFile && !roadmapFile)
         return false;
     if (hasBlockingDepthGate(entry))

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -273,10 +273,10 @@ This config sets a parent workspace with two child repositories. The implicit `p
   - `audit_unified.enabled`: boolean — dual-write unified audit envelope events. Default: `true`.
   - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow. Default: `true`.
 
-- `context_management`: configures context hygiene for auto-mode sessions. Keys:
+- `context_management`: configures context hygiene for auto-mode sessions. In step mode, the configurable threshold is a soft warning; automatic session re-rooting happens only at the fixed 90% hard context boundary. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.
-  - `compaction_threshold_percent`: number — trigger compaction at this % of context window (0.5-0.95). Lower values fire compaction earlier, reducing drift. Default: `0.60`.
+  - `compaction_threshold_percent`: number — show a soft context warning at this fraction of the context window (0.5-0.95). Lower values warn earlier so operators can compact manually before drift accumulates. Default: `0.60`.
   - `tool_result_max_chars`: number — max chars per tool result in GSD sessions (200-10000). Default: `800`.
 
 - `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`.

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -1,11 +1,115 @@
-import { existsSync, statSync } from "node:fs";
-import { isDbAvailable, _getAdapter } from "./gsd-db.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, isMemoriesFtsAvailable, _getAdapter, } from "./gsd-db.js";
+import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { deriveState } from "./state.js";
+import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 import { flushWorkflowProjections } from "./projection-flush.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { parsePlan } from "./parsers-legacy.js";
+function relativeFile(basePath, filePath) {
+    return relative(basePath, filePath).split("\\").join("/");
+}
+function reportCheckboxDbStatusDivergence(issues, basePath, filePath, scope, unitId, status, checkboxDone) {
+    const dbDone = isClosedStatus(status);
+    if (checkboxDone === dbDone)
+        return;
+    issues.push({
+        severity: "error",
+        code: "checkbox_db_status_divergence",
+        scope,
+        unitId,
+        message: `${scope === "slice" ? "Slice" : "Task"} ${unitId} is ${dbDone ? "closed" : "open"} in the database (status: ${status}) but the markdown checkbox is ${checkboxDone ? "checked" : "unchecked"}.`,
+        file: relativeFile(basePath, filePath),
+        fixable: false,
+    });
+}
+function checkProjectionCheckboxDbStatus(basePath, milestoneIds, issues) {
+    for (const milestoneId of milestoneIds) {
+        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+        const slices = getMilestoneSlices(milestoneId);
+        if (roadmapPath && existsSync(roadmapPath)) {
+            try {
+                const roadmap = readFileSync(roadmapPath, "utf-8");
+                const sliceDoneById = new Map(parseRoadmapSlices(roadmap).map((entry) => [entry.id, entry.done]));
+                for (const slice of slices) {
+                    const checkboxDone = sliceDoneById.get(slice.id);
+                    if (checkboxDone === undefined)
+                        continue;
+                    reportCheckboxDbStatusDivergence(issues, basePath, roadmapPath, "slice", `${milestoneId}/${slice.id}`, slice.status, checkboxDone);
+                }
+            }
+            catch {
+                // Non-fatal — checkbox drift diagnostics must never block doctor.
+            }
+        }
+        for (const slice of slices) {
+            const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+            if (!planPath || !existsSync(planPath))
+                continue;
+            try {
+                const plan = readFileSync(planPath, "utf-8");
+                // parsePlan reads the authoritative task checkboxes (the flat-phase
+                // <tasks> block / ## Tasks section), so a stray task-style checkbox
+                // line elsewhere in PLAN.md (e.g. a Must-Haves or Verification bullet
+                // above <tasks>) can no longer hide real drift or fake a divergence.
+                const taskDoneById = new Map(parsePlan(plan).tasks.map((entry) => [entry.id, entry.done]));
+                for (const task of getSliceTasks(milestoneId, slice.id)) {
+                    const checkboxDone = taskDoneById.get(task.id);
+                    if (checkboxDone === undefined)
+                        continue;
+                    reportCheckboxDbStatusDivergence(issues, basePath, planPath, "task", `${milestoneId}/${slice.id}/${task.id}`, task.status, checkboxDone);
+                }
+            }
+            catch {
+                // Non-fatal — checkbox drift diagnostics must never block doctor.
+            }
+        }
+    }
+}
+function isClearedByMilestoneShellProjectionFlush(basePath, issue, reRenderedMilestoneIds) {
+    if (issue.code !== "checkbox_db_status_divergence")
+        return false;
+    if (issue.scope !== "slice")
+        return false;
+    const milestoneId = issue.unitId.split("/")[0] ?? "";
+    if (!reRenderedMilestoneIds.has(milestoneId))
+        return false;
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (!roadmapPath || !issue.file)
+        return false;
+    return issue.file === relativeFile(basePath, roadmapPath);
+}
+function artifactExistsOnDisk(basePath, artifactPath) {
+    if (isAbsolute(artifactPath))
+        return existsSync(artifactPath);
+    return [
+        join(gsdProjectionRoot(basePath), artifactPath),
+        join(gsdRoot(basePath), artifactPath),
+    ].some((candidate) => existsSync(candidate));
+}
+function artifactUnitId(row) {
+    if (!row.milestone_id)
+        return "project";
+    if (row.slice_id && row.task_id)
+        return `${row.milestone_id}/${row.slice_id}/${row.task_id}`;
+    if (row.slice_id)
+        return `${row.milestone_id}/${row.slice_id}`;
+    return row.milestone_id;
+}
+function artifactScope(row) {
+    if (row.task_id)
+        return "task";
+    if (row.slice_id)
+        return "slice";
+    if (row.milestone_id)
+        return "milestone";
+    return "project";
+}
 export async function checkEngineHealth(basePath, issues, fixesApplied) {
     const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
@@ -23,6 +127,30 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     try {
         if (isDbAvailable()) {
             const adapter = _getAdapter();
+            try {
+                if (isMemoriesFtsAvailable(adapter)) {
+                    const runtimeKv = adapter
+                        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='runtime_kv'")
+                        .get();
+                    const marker = runtimeKv
+                        ? adapter.prepare("SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key").get({ ":key": MEMORIES_FTS_REBUILT_KEY })
+                        : undefined;
+                    if (!marker) {
+                        issues.push({
+                            severity: "warning",
+                            code: "memories_fts_rebuild_missing",
+                            scope: "project",
+                            unitId: "project",
+                            message: `Memory full-text index exists but runtime_kv has no ${MEMORIES_FTS_REBUILT_KEY} marker. The index may be stale or incomplete, so memory search can silently degrade to the LIKE fallback.`,
+                            file: ".gsd/gsd.db",
+                            fixable: false,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Non-fatal — memory FTS health check failed
+            }
             // a. Orphaned tasks (task.slice_id points to non-existent slice)
             try {
                 const orphanedTasks = adapter
@@ -172,7 +300,33 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
             catch {
                 // Non-fatal — completed-milestone reopen check failed
             }
-            // f. Completion artifacts disagree with open DB hierarchy rows.
+            // f. Artifact rows reference files that no longer exist on disk.
+            try {
+                const artifactRows = adapter
+                    .prepare(`SELECT path, artifact_type, milestone_id, slice_id, task_id
+             FROM artifacts
+             WHERE path != ''
+             ORDER BY path`)
+                    .all();
+                for (const row of artifactRows) {
+                    if (artifactExistsOnDisk(basePath, row.path))
+                        continue;
+                    const unitId = artifactUnitId(row);
+                    issues.push({
+                        severity: "error",
+                        code: "artifact_file_missing",
+                        scope: artifactScope(row),
+                        unitId,
+                        message: `Artifact ${row.path} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
+                        file: row.path,
+                        fixable: false,
+                    });
+                }
+            }
+            catch {
+                // Non-fatal — artifact file existence check failed
+            }
+            // g. Completion artifacts disagree with open DB hierarchy rows.
             try {
                 const rows = adapter
                     .prepare(`SELECT a.path, a.artifact_type, a.milestone_id, a.slice_id, a.task_id, a.imported_at,
@@ -189,6 +343,8 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     .all();
                 const seen = new Set();
                 for (const row of rows) {
+                    if (!artifactExistsOnDisk(basePath, row.path))
+                        continue;
                     const reopenAt = latestExplicitReopenAt(basePath, row.milestone_id);
                     if (!isAfter(row.imported_at, reopenAt))
                         continue;
@@ -223,9 +379,24 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     catch {
         // Non-fatal — DB constraint checks failed entirely
     }
+    // Checkbox-vs-DB divergence detection runs before projection drift auto-fix
+    // so stale re-renders cannot overwrite manually edited markdown first. Runs
+    // inside its own try/catch: getAllMilestones / getMilestoneSlices /
+    // getSliceTasks issue prepared queries that can throw on a corrupt or locked
+    // DB, and like every other DB-touching check here this diagnostic must never
+    // block doctor.
+    try {
+        if (isDbAvailable()) {
+            checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+        }
+    }
+    catch {
+        // Non-fatal: checkbox-vs-DB divergence check must never block doctor
+    }
     // ── Projection drift detection ──────────────────────────────────────────
     // If the DB is available, check whether markdown projections are stale
     // relative to the event log and re-render them.
+    const reRenderedMilestoneIds = [];
     try {
         if (isDbAvailable()) {
             const eventLogPath = workflowEventLogPath(basePath);
@@ -241,6 +412,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                         try {
                             await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
+                            reRenderedMilestoneIds.push(milestone.id);
                         }
                         catch {
                             // Non-fatal — projection re-render failed
@@ -252,6 +424,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                         try {
                             await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
+                            reRenderedMilestoneIds.push(milestone.id);
                         }
                         catch {
                             // Non-fatal — projection re-render failed
@@ -264,4 +437,19 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     catch {
         // Non-fatal — projection drift check must never block doctor
     }
+    if (reRenderedMilestoneIds.length > 0) {
+        const reRendered = new Set(reRenderedMilestoneIds);
+        for (let i = issues.length - 1; i >= 0; i--) {
+            const issue = issues[i];
+            // flushWorkflowProjections re-renders milestone shell projections (not
+            // slice PLAN.md files), so only clear stale ROADMAP checkbox diagnostics.
+            if (isClearedByMilestoneShellProjectionFlush(basePath, issue, reRendered)) {
+                issues.splice(i, 1);
+                continue;
+            }
+            if (issue.code === "artifact_file_missing" && issue.file && artifactExistsOnDisk(basePath, issue.file)) {
+                issues.splice(i, 1);
+            }
+        }
+    }
 }

package/dist/resources/extensions/gsd/doctor-git-checks.js

@@ -13,7 +13,7 @@ import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegr
 import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { getAllWorktreeHealth } from "./worktree-health.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { listUnmergedGitPaths } from "./git-conflict-state.js";
+import { listUnmergedGitPaths, probeGitConflictState, reconcileGitConflictsOnSignal } from "./git-conflict-state.js";
 import { resolveWorktreeProjectRoot } from "./worktree-root.js";
 /**
  * Returns true if the directory contains only doctor artifacts
@@ -141,13 +141,13 @@ function getSnapshotDiffCheckFailure(basePath) {
     }
     return failures.length > 0 ? failures.join("\n") : null;
 }
-export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "none") {
+export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "none", dryRun = false) {
     // Degrade gracefully if not a git repo
     if (!nativeIsRepo(basePath)) {
         return; // Not a git repo — skip all git health checks
     }
     const gitDir = resolveGitDir(basePath);
-    const unmergedPaths = listUnmergedGitPaths(basePath);
+    let unmergedPaths = listUnmergedGitPaths(basePath);
     if (unmergedPaths === null) {
         issues.push({
             severity: "error",
@@ -159,6 +159,28 @@ export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix,
         });
         return;
     }
+    // ── Auto-resolve safe conflicts before reporting ──────────────────────
+    // A failed worktree merge (e.g. during complete-slice) can leave conflict
+    // markers for paths that are always safe to accept from the milestone side
+    // (.gsd/ state and build artifacts). Run the same reconciliation the
+    // preflight/auto-worktree paths use before the doctor hard-blocks auto-mode,
+    // so only genuinely-manual conflicts remain. This also clears stale
+    // merge-state markers (e.g. MERGE_HEAD) in the same pass when auto-resolve
+    // empties the unmerged set (#849).
+    if (unmergedPaths.length > 0 && !dryRun) {
+        try {
+            const reconcileFixes = reconcileGitConflictsOnSignal(basePath, probeGitConflictState(basePath));
+            if (reconcileFixes.length > 0) {
+                fixesApplied.push(...reconcileFixes);
+                const refreshed = listUnmergedGitPaths(basePath);
+                if (refreshed !== null)
+                    unmergedPaths = refreshed;
+            }
+        }
+        catch {
+            // Non-fatal — fall through to report the unmerged paths as-is
+        }
+    }
     // ── Orphaned auto-worktrees & Stale milestone branches ────────────────
     // These checks only apply in worktree/branch modes — skip in none mode
     // where no milestone worktrees or branches are created.

package/dist/resources/extensions/gsd/doctor-providers.js

@@ -11,6 +11,7 @@
  *   - Optional search/tool integrations (Brave, Tavily, Jina, Context7)
  */
 import { existsSync, readFileSync } from "node:fs";
+import { access, readFile } from "node:fs/promises";
 import { delimiter, join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
@@ -133,15 +134,11 @@ const CLI_AUTH_PATH_CHECK_PROVIDERS = new Set([
     "google-gemini-cli",
     "google-antigravity",
 ]);
-/**
- * Check if a CLI provider's binary exists anywhere in PATH.
- * Fast filesystem scan — no subprocess, no network, sub-1ms.
- */
-function isCliBinaryInPath(providerId) {
+let asyncCliBinaryPathCache = null;
+function cliExecutableNames(providerId) {
     const binaries = CLI_BINARY_MAP[providerId];
     if (!binaries)
-        return false;
-    const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+        return [];
     // On Windows, command shims are commonly installed as .cmd/.exe/.bat/.com.
     // Scan PATHEXT candidates in addition to the bare binary name.
     const executableNames = [...binaries];
@@ -160,8 +157,45 @@ function isCliBinaryInPath(providerId) {
             }
         }
     }
+    return executableNames;
+}
+/**
+ * Check if a CLI provider's binary exists anywhere in PATH.
+ * Fast filesystem scan — no subprocess, no network, sub-1ms.
+ */
+function isCliBinaryInPath(providerId) {
+    const cached = asyncCliBinaryPathCache?.get(providerId);
+    if (cached !== undefined)
+        return cached;
+    const executableNames = cliExecutableNames(providerId);
+    if (executableNames.length === 0)
+        return false;
+    const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
     return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
+async function isCliBinaryInPathAsync(providerId) {
+    const executableNames = cliExecutableNames(providerId);
+    if (executableNames.length === 0)
+        return false;
+    const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+    const candidates = pathDirs.flatMap(dir => executableNames.map(name => join(dir, name)));
+    if (candidates.length === 0)
+        return false;
+    try {
+        await Promise.any(candidates.map(candidate => access(candidate)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadCliBinaryPathCache() {
+    const entries = await Promise.all(Object.keys(CLI_BINARY_MAP).map(async (providerId) => [
+        providerId,
+        await isCliBinaryInPathAsync(providerId),
+    ]));
+    return new Map(entries);
+}
 function modelsJsonPaths() {
     const home = homedir();
     return [
@@ -170,7 +204,11 @@ function modelsJsonPaths() {
         join(home, ".pi", "agent", "models.json"),
     ];
 }
+let asyncModelsJsonApiKeyCache = null;
 function hasModelsJsonApiKey(providerId) {
+    if (asyncModelsJsonApiKeyCache) {
+        return asyncModelsJsonApiKeyCache.has(providerId);
+    }
     for (const path of modelsJsonPaths()) {
         if (!existsSync(path))
             continue;
@@ -187,7 +225,25 @@ function hasModelsJsonApiKey(providerId) {
     }
     return false;
 }
-function resolveKey(providerId) {
+async function loadModelsJsonApiKeyCache() {
+    const providersWithKeys = new Set();
+    for (const path of modelsJsonPaths()) {
+        try {
+            const parsed = JSON.parse(await readFile(path, "utf-8"));
+            for (const [providerId, provider] of Object.entries(parsed.providers ?? {})) {
+                const apiKey = provider.apiKey;
+                if (typeof apiKey === "string" && apiKey.trim().length > 0) {
+                    providersWithKeys.add(providerId);
+                }
+            }
+        }
+        catch {
+            // Missing or malformed models.json should not break dashboard health checks.
+        }
+    }
+    return providersWithKeys;
+}
+function resolveKeyFromAuthOrEnv(providerId) {
     const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
     if (providerId === "anthropic-vertex" && process.env.ANTHROPIC_VERTEX_PROJECT_ID) {
         return { found: true, source: "env", backedOff: false };
@@ -234,6 +290,12 @@ function resolveKey(providerId) {
     if (info?.envVar && process.env[info.envVar]) {
         return { found: true, source: "env", backedOff: false };
     }
+    return null;
+}
+function resolveKey(providerId) {
+    const direct = resolveKeyFromAuthOrEnv(providerId);
+    if (direct)
+        return direct;
     if (hasModelsJsonApiKey(providerId)) {
         return { found: true, source: "models.json", backedOff: false };
     }
@@ -432,6 +494,28 @@ export function runProviderChecks() {
     results.push(...checkOptionalProviders());
     return results;
 }
+/**
+ * Non-blocking equivalent of `runProviderChecks` for the health-widget
+ * background refresh. PATH checks and custom models.json discovery use async
+ * filesystem APIs so periodic widget refreshes do not stall the input loop.
+ */
+export async function runProviderChecksAsync() {
+    const [cliCache, modelsJsonCache] = await Promise.all([
+        loadCliBinaryPathCache(),
+        loadModelsJsonApiKeyCache(),
+    ]);
+    const previousCliCache = asyncCliBinaryPathCache;
+    const previousModelsJsonCache = asyncModelsJsonApiKeyCache;
+    asyncCliBinaryPathCache = cliCache;
+    asyncModelsJsonApiKeyCache = modelsJsonCache;
+    try {
+        return runProviderChecks();
+    }
+    finally {
+        asyncCliBinaryPathCache = previousCliCache;
+        asyncModelsJsonApiKeyCache = previousModelsJsonCache;
+    }
+}
 /**
  * Format provider check results as a human-readable report string.
  */

package/dist/resources/extensions/gsd/doctor-runtime-checks.js

@@ -10,25 +10,12 @@ import { getActiveAutoWorkers } from "./db/auto-workers.js";
 import { normalizeRealPath } from "./paths.js";
 import { ensureGitignore, isGsdGitignored } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
-import { recoverFailedMigration } from "./migrate-external.js";
+import { isCurrentGsdStateIntactForMigratingCleanup, recoverFailedMigration } from "./migrate-external.js";
 import { splitCompletedKey } from "./forensics.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { getAllMilestones, isDbAvailable } from "./gsd-db.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 const MAX_UAT_ATTEMPTS = 3;
-function isCurrentGsdStateIntactForMigratingCleanup(basePath) {
-    try {
-        const stateFile = resolveGsdRootFile(basePath, "STATE");
-        const milestonesPath = milestonesDir(basePath);
-        const dbPath = join(gsdRoot(basePath), "gsd.db");
-        const hasDbFile = existsSync(dbPath);
-        const hasNonEmptyDb = hasDbFile && statSync(dbPath).size > 0;
-        return existsSync(stateFile) && existsSync(milestonesPath) && hasNonEmptyDb;
-    }
-    catch {
-        return false;
-    }
-}
 function hasAssessmentVerdict(basePath, mid, sid) {
     const assessmentPath = join(gsdRoot(basePath), "milestones", mid, "slices", sid, `${sid}-ASSESSMENT.md`);
     if (!existsSync(assessmentPath))
@@ -400,6 +387,9 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
             if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
                 missing.push(".gsd-worktrees/");
             }
+            if (!existingLines.has(".gsd-backups/") && !existingLines.has(".gsd-backups")) {
+                missing.push(".gsd-backups/");
+            }
             if (!hasBlanketIgnore) {
                 missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
             }
@@ -442,7 +432,7 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
                 });
                 if (shouldFix("failed_migration")) {
                     if (recoverFailedMigration(basePath)) {
-                        fixesApplied.push("recovered failed migration (.gsd.migrating → .gsd)");
+                        fixesApplied.push("recovered failed external state migration");
                     }
                     else if (isCurrentGsdStateIntactForMigratingCleanup(basePath)) {
                         try {