@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -11,12 +11,14 @@
  *   - Optional search/tool integrations (Brave, Tavily, Jina, Context7)
  */
 import { existsSync, readFileSync } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
+import { isCursorAgentReadyUncached } from "../cursor-cli/readiness.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, supportsBrowserOAuth } from "./key-manager.js";
-import { homedir } from "node:os";
 // ── Provider routing constants ────────────────────────────────────────────────
 /**
  * Providers that use external CLI authentication (not API keys).
@@ -26,6 +28,7 @@ const CLI_AUTH_PROVIDERS = new Set([
     "claude-code",
     "google-gemini-cli",
     "google-antigravity",
+    "cursor-agent",
 ]);
 /**
  * Providers that can serve models normally associated with another provider.
@@ -33,9 +36,9 @@ const CLI_AUTH_PROVIDERS = new Set([
  * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
  */
 const PROVIDER_ROUTES = {
-    anthropic: ["github-copilot", "claude-code"],
-    openai: ["github-copilot", "openai-codex"],
-    google: ["google-antigravity", "google-gemini-cli"],
+    anthropic: ["github-copilot", "claude-code", "cursor-agent"],
+    openai: ["github-copilot", "openai-codex", "cursor-agent"],
+    google: ["google-antigravity", "google-gemini-cli", "cursor-agent"],
 };
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
 /**
@@ -60,6 +63,7 @@ function modelToProviderId(model) {
             anthropic: "anthropic",
             openai: "openai",
             "github-copilot": "github-copilot",
+            "cursor-agent": "cursor-agent",
         };
         if (prefixMap[prefix])
             return prefixMap[prefix];
@@ -72,6 +76,8 @@ function modelToProviderId(model) {
         return "openai";
     if (lower.startsWith("gemini"))
         return "google";
+    if (lower.startsWith("composer"))
+        return "cursor-agent";
     if (lower.startsWith("llama") || lower.startsWith("mixtral"))
         return "groq";
     if (lower.startsWith("grok"))
@@ -128,20 +134,18 @@ const CLI_BINARY_MAP = {
     "claude-code": ["claude", "claude-code"],
     "google-gemini-cli": ["gemini"],
     "google-antigravity": ["agy"],
+    "cursor-agent": ["cursor-agent"],
 };
 const CLI_AUTH_PATH_CHECK_PROVIDERS = new Set([
     "google-gemini-cli",
     "google-antigravity",
+    "cursor-agent",
 ]);
-/**
- * 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 +164,56 @@ 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))));
 }
+function isExternalCliProviderReady(providerId) {
+    if (providerId === "cursor-agent")
+        return isCursorAgentReadyUncached();
+    return isCliBinaryInPath(providerId);
+}
+function cursorAgentFailureDetail() {
+    if (!isCliBinaryInPath("cursor-agent")) {
+        return "Install Cursor Agent and ensure `cursor-agent` is on PATH";
+    }
+    return "Run `cursor-agent login` or set CURSOR_API_KEY";
+}
+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 +222,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 +243,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,12 +308,23 @@ function resolveKey(providerId) {
     if (info?.envVar && process.env[info.envVar]) {
         return { found: true, source: "env", backedOff: false };
     }
+    return null;
+}
+function resolveKey(providerId) {
+    if (providerId === "cursor-agent") {
+        return isExternalCliProviderReady(providerId)
+            ? { found: true, source: "env", backedOff: false }
+            : { found: false, source: "none", backedOff: false };
+    }
+    const direct = resolveKeyFromAuthOrEnv(providerId);
+    if (direct)
+        return direct;
     if (hasModelsJsonApiKey(providerId)) {
         return { found: true, source: "models.json", backedOff: false };
     }
     // Cross-provider routes can use a local CLI when it is installed. Explicit
     // external CLI provider selections are handled in checkLlmProviders() below.
-    if (CLI_AUTH_PROVIDERS.has(providerId) && isCliBinaryInPath(providerId)) {
+    if (CLI_AUTH_PROVIDERS.has(providerId) && isExternalCliProviderReady(providerId)) {
         return { found: true, source: "env", backedOff: false };
     }
     return { found: false, source: "none", backedOff: false };
@@ -254,17 +339,22 @@ function checkLlmProviders() {
         if (CLI_AUTH_PROVIDERS.has(providerId)) {
             const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
             const label = info?.label ?? providerId;
-            if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isCliBinaryInPath(providerId)) {
+            if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isExternalCliProviderReady(providerId)) {
                 const binaries = CLI_BINARY_MAP[providerId]?.map(binary => `\`${binary}\``).join(" or ");
+                const detail = providerId === "cursor-agent"
+                    ? cursorAgentFailureDetail()
+                    : binaries
+                        ? `Install ${label} and ensure ${binaries} is on PATH`
+                        : `Install ${label} and ensure its CLI is on PATH`;
                 results.push({
                     name: providerId,
                     label,
                     category: "llm",
                     status: "error",
-                    message: `${label} — CLI not found`,
-                    detail: binaries
-                        ? `Install ${label} and ensure ${binaries} is on PATH`
-                        : `Install ${label} and ensure its CLI is on PATH`,
+                    message: providerId === "cursor-agent" && isCliBinaryInPath(providerId)
+                        ? `${label} — CLI not authenticated`
+                        : `${label} — CLI not found`,
+                    detail,
                     required: true,
                 });
                 continue;
@@ -432,6 +522,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 {

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

@@ -1,16 +1,20 @@
-import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { openExistingWorkflowDatabase } from "./db-workspace.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, legacyMilestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { collectPreferenceDiagnostics, formatPreferenceDiagnosticDetail } from "./preferences-diagnostics.js";
 import { isClosedStatus } from "./status-guards.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
 import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
@@ -171,7 +175,8 @@ export async function selectDoctorScope(basePath, requestedScope) {
         return state.activeMilestone.id;
     }
     const milestonesPath = milestonesDir(basePath);
-    if (!existsSync(milestonesPath))
+    const legacyMilestonesPath = legacyMilestonesDir(basePath);
+    if (!existsSync(milestonesPath) && !existsSync(legacyMilestonesPath))
         return undefined;
     for (const milestone of state.registry) {
         const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
@@ -279,6 +284,92 @@ export async function readDoctorHistory(basePath, lastN = 50) {
         return [];
     }
 }
+/**
+ * Resolve the git working-tree root for a path, or null if it is not a repo.
+ * Used by the workspace-repository probe to check that a declared child path is
+ * itself a git repository (not merely nested inside the parent's repo).
+ */
+function resolveGitToplevel(cwd) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+        }).trim();
+        return out ? resolve(out) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** realpath that falls back to the resolved path if the link cannot be read. */
+function realpathSafe(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/**
+ * Parent-workspace probe (#818): validate that every declared child repository
+ * exists on disk and is a git repository at its own root. The registry only
+ * checks paths stay inside the project root; it never checks existence or
+ * git-ness, so a typo'd path (e.g. `frontned`) would otherwise build cleanly
+ * and silently produce "no problems found." No-op for single-repo projects.
+ */
+function checkWorkspaceRepositoryHealth(basePath, prefs, issues) {
+    if (prefs?.workspace?.mode !== "parent")
+        return;
+    let registry;
+    try {
+        registry = createRepositoryRegistryFromPreferences(basePath, prefs);
+    }
+    catch (err) {
+        issues.push({
+            severity: "error",
+            code: "invalid_preferences",
+            scope: "project",
+            unitId: "workspace",
+            message: `workspace registry failed to build: ${err instanceof Error ? err.message : String(err)}`,
+            fixable: false,
+        });
+        return;
+    }
+    for (const repo of registry.repositories) {
+        if (repo.id === "project")
+            continue;
+        if (!existsSync(repo.root)) {
+            issues.push({
+                severity: "error",
+                code: "workspace_repo_path_missing",
+                scope: "project",
+                unitId: `workspace.repositories.${repo.id}`,
+                message: `declared repository "${repo.id}" path does not exist on disk: ${repo.root}`,
+                fixable: false,
+            });
+            continue;
+        }
+        // Must be a repo at its OWN root — a plain dir nested in the parent repo
+        // would otherwise pass a bare `nativeIsRepo` check via the enclosing
+        // parent's .git. Compare on realpath so symlinked temp roots (macOS
+        // /var vs /private/var) don't cause a false mismatch.
+        const toplevel = resolveGitToplevel(repo.root);
+        const declaredReal = realpathSafe(repo.root);
+        const toplevelReal = toplevel ? realpathSafe(toplevel) : null;
+        if (toplevelReal !== declaredReal) {
+            issues.push({
+                severity: "warning",
+                code: "workspace_repo_not_a_repo",
+                scope: "project",
+                unitId: `workspace.repositories.${repo.id}`,
+                message: `declared repository "${repo.id}" path is not a git repository at its own root: ${repo.root}`,
+                fixable: false,
+            });
+        }
+    }
+}
 export async function runGSDDoctor(basePath, options) {
     const issues = [];
     const fixesApplied = [];
@@ -333,7 +424,8 @@ export async function runGSDDoctor(basePath, options) {
     const isolationMode = options?.isolationMode ??
         (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
             prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
-    await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
+    await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode, dryRun);
+    checkWorkspaceRepositoryHealth(basePath, prefs?.preferences, issues);
     const gitMs = Date.now() - t0git;
     // Runtime health checks — timed
     const t0runtime = Date.now();
@@ -350,9 +442,10 @@ export async function runGSDDoctor(basePath, options) {
     });
     const envMs = Date.now() - t0env;
     // Engine health checks — DB constraints and projection drift
-    await checkEngineHealth(basePath, issues, fixesApplied);
+    await checkEngineHealth(basePath, issues, fixesApplied, { repair: fix && !dryRun });
     const milestonesPath = milestonesDir(basePath);
-    if (!existsSync(milestonesPath)) {
+    const legacyMilestonesPath2 = legacyMilestonesDir(basePath);
+    if (!existsSync(milestonesPath) && !existsSync(legacyMilestonesPath2)) {
         const report = { ok: issues.every(i => i.severity !== "error"), basePath, issues, fixesApplied, timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: 0 } };
         await appendDoctorHistory(basePath, report);
         return report;
@@ -396,7 +489,13 @@ export async function runGSDDoctor(basePath, options) {
             // Non-fatal — provider check failure should not block other checks
         }
     }
-    for (const milestone of state.registry) {
+    // When DB is unavailable, state.registry is empty. Fall back to a direct
+    // filesystem scan so the doctor can still report issues (e.g. missing ROADMAP)
+    // for milestone dirs that exist on disk.
+    const milestoneEntries = state.registry.length > 0
+        ? state.registry
+        : findMilestoneIds(basePath).map(id => ({ id, title: id }));
+    for (const milestone of milestoneEntries) {
         const milestoneId = milestone.id;
         const milestonePath = resolveMilestonePath(basePath, milestoneId);
         if (!milestonePath)
@@ -433,8 +532,17 @@ export async function runGSDDoctor(basePath, options) {
         }
         const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
         const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-        if (!roadmapContent)
+        if (!roadmapContent) {
+            issues.push({
+                severity: "error",
+                code: "missing_roadmap",
+                scope: "milestone",
+                unitId: milestoneId,
+                message: `Milestone ${milestoneId} is missing its ROADMAP.md file.`,
+                fixable: false,
+            });
             continue;
+        }
         let slices;
         if (isDbAvailable()) {
             const dbSlices = getMilestoneSlices(milestoneId);
@@ -574,6 +682,9 @@ export async function runGSDDoctor(basePath, options) {
                 // Skipped slices may legitimately never create tasks/.
                 if (slice.pending || slice.skipped)
                     continue;
+                // Flat-phase: tasks are embedded in plan files; no tasks/ subdir expected.
+                if (!existsSync(legacyMilestonesDir(basePath)))
+                    continue;
                 issues.push({
                     severity: slice.done ? "warning" : "error",
                     code: "missing_tasks_dir",
@@ -739,7 +850,7 @@ export async function runGSDDoctor(basePath, options) {
                 code: "all_slices_done_missing_milestone_validation",
                 scope: "milestone",
                 unitId: milestoneId,
-                message: `All slices are done but ${milestoneId}-VALIDATION.md is missing \u2014 milestone is in validating-milestone phase`,
+                message: `All slices are done but the milestone VALIDATION.md is missing \u2014 milestone is in validating-milestone phase`,
                 file: relMilestoneFile(basePath, milestoneId, "VALIDATION"),
                 fixable: false,
             });

package/dist/resources/extensions/gsd/error-classifier.js

@@ -9,7 +9,7 @@
  *
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
-import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
+import { TOOL_SURFACE_NOT_READY, isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 export function createRetryState() {
     return { networkRetryCount: 0, consecutiveTransientCount: 0, currentRetryModelId: undefined };
 }
@@ -82,7 +82,19 @@ export function classifyError(errorMsg, retryAfterMs) {
     if (TOOL_SCHEMA_RE.test(errorMsg)) {
         return { kind: "tool-schema", retryAfterMs: 0 };
     }
+    // Terminal tool-surface failure: the workflow MCP server is in a
+    // non-self-healing status (failed / needs-auth / disabled). This is NOT
+    // transient — retrying the same model cannot repair a dead server, so it
+    // must escalate / pause rather than retrying every ~3s into the per-unit
+    // cost cap. Checked ahead of the transient readiness branch below, which
+    // shares the TOOL_SURFACE_NOT_READY prefix and would otherwise collapse the
+    // terminal case into a transient `network` retry. See #783.
+    if (isTerminalToolSurfaceError(errorMsg)) {
+        return { kind: "permanent" };
+    }
     // Tool-surface readiness abort — transient; retry the same model shortly.
+    // This covers the not-yet-connected variants (absent, pending, connected but
+    // not registered); terminal statuses were handled by the branch above.
     if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
         return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
     }

package/dist/resources/extensions/gsd/escalation.js

@@ -7,7 +7,7 @@
 // execute-task only (refine-slice escalation is deferred per ADR-011).
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { resolveSlicePath } from "./paths.js";
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { getTask, setTaskEscalationPending, setTaskEscalationAwaitingReview, clearTaskEscalationFlags, claimEscalationOverride, findUnappliedEscalationOverride, setTaskBlockerSource, listEscalationArtifacts, } from "./gsd-db.js";
 import { emitUokAuditEvent, buildAuditEnvelope } from "./uok/audit.js";
@@ -18,10 +18,17 @@ import { logWarning } from "./workflow-logger.js";
  *   .gsd/milestones/{M}/slices/{S}/tasks/{T}-ESCALATION.json
  */
 export function escalationArtifactPath(basePath, milestoneId, sliceId, taskId) {
-    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
-    if (!sDir)
+    const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    if (tDir)
+        return join(tDir, `${taskId}-ESCALATION.json`);
+    // Flat-phase: tasks live in plan files; escalation artifacts sit in the phase dir.
+    // Legacy without tasks/: return null so writeEscalationArtifact throws (run doctor).
+    if (existsSync(legacyMilestonesDir(basePath)))
         return null;
-    return join(sDir, "tasks", `${taskId}-ESCALATION.json`);
+    const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    if (!phaseDir)
+        return null;
+    return join(phaseDir, `${taskId}-ESCALATION.json`);
 }
 // ─── Artifact I/O ─────────────────────────────────────────────────────────
 /** Build an EscalationArtifact from a gsd_complete_task escalation payload. */