@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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";
@@ -35,7 +36,7 @@ const CLI_AUTH_PROVIDERS = new Set([
 const PROVIDER_ROUTES = {
     anthropic: ["github-copilot", "claude-code"],
     openai: ["github-copilot", "openai-codex"],
-    google: ["google-gemini-cli"],
+    google: ["google-antigravity", "google-gemini-cli"],
 };
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
 /**
@@ -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))
@@ -53,19 +40,21 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
         if (lock) {
             const alive = isLockProcessAlive(lock);
             if (!alive) {
-                issues.push({
-                    severity: "error",
-                    code: "stale_crash_lock",
-                    scope: "project",
-                    unitId: "project",
-                    message: `Stale auto-mode worker (PID ${lock.pid}, started ${lock.startedAt}, was executing ${lock.unitType} ${lock.unitId}) — process is no longer running`,
-                    file: "<workers table>",
-                    fixable: true,
-                });
                 if (shouldFix("stale_crash_lock")) {
                     clearStaleWorkerLock(basePath);
                     fixesApplied.push("cleared stale auto-mode worker state");
                 }
+                else {
+                    issues.push({
+                        severity: "error",
+                        code: "stale_crash_lock",
+                        scope: "project",
+                        unitId: "project",
+                        message: `Stale auto-mode worker (PID ${lock.pid}, started ${lock.startedAt}, was executing ${lock.unitType} ${lock.unitId}) — process is no longer running`,
+                        file: "<workers table>",
+                        fixable: true,
+                    });
+                }
             }
         }
     }
@@ -391,24 +380,29 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
                 ".gsd/completed-units*.json",
                 ".gsd/event-log.jsonl",
             ];
-            // If blanket .gsd/ or .gsd is present, all patterns are covered
+            // If blanket .gsd/ or .gsd is present, all .gsd/* patterns are covered —
+            // but NOT the .gsd-worktrees/ sibling, which always needs its own entry.
             const hasBlanketIgnore = existingLines.has(".gsd/") || existingLines.has(".gsd");
+            const missing = [];
+            if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
+                missing.push(".gsd-worktrees/");
+            }
             if (!hasBlanketIgnore) {
-                const missing = criticalPatterns.filter(p => !existingLines.has(p));
-                if (missing.length > 0) {
-                    issues.push({
-                        severity: "warning",
-                        code: "gitignore_missing_patterns",
-                        scope: "project",
-                        unitId: "project",
-                        message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
-                        file: ".gitignore",
-                        fixable: true,
-                    });
-                    if (shouldFix("gitignore_missing_patterns")) {
-                        ensureGitignore(basePath, { manageGitignore });
-                        fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-                    }
+                missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
+            }
+            if (missing.length > 0) {
+                issues.push({
+                    severity: "warning",
+                    code: "gitignore_missing_patterns",
+                    scope: "project",
+                    unitId: "project",
+                    message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+                    file: ".gitignore",
+                    fixable: true,
+                });
+                if (shouldFix("gitignore_missing_patterns")) {
+                    ensureGitignore(basePath, { manageGitignore });
+                    fixesApplied.push("added missing GSD runtime patterns to .gitignore");
                 }
             }
         }
@@ -435,7 +429,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

@@ -2,11 +2,14 @@ import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "nod
 import { join } from "node:path";
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, openDatabase, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.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 { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
@@ -169,7 +172,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");
@@ -286,13 +290,7 @@ export async function runGSDDoctor(basePath, options) {
     // CLI doctor can run before any tool handler has opened the DB. Runtime
     // health checks need the existing project DB to surface DB-backed crash
     // locks, paused sessions, and coordination rows.
-    const dbPath = resolveGsdPathContract(basePath).projectDb;
-    if (existsSync(dbPath)) {
-        try {
-            openDatabase(dbPath);
-        }
-        catch { /* surfaced later as db_unavailable */ }
-    }
+    openExistingWorkflowDatabase(basePath);
     // Issue codes that represent completion state transitions — creating summary
     // stubs, marking slices/milestones done in the roadmap. These belong to the
     // dispatch lifecycle (complete-slice, complete-milestone units), not to
@@ -307,6 +305,17 @@ export async function runGSDDoctor(basePath, options) {
         return true;
     };
     const prefs = loadEffectiveGSDPreferences(basePath);
+    for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+        issues.push({
+            severity: diagnostic.severity,
+            code: "invalid_preferences",
+            scope: "project",
+            unitId: "project",
+            message: `GSD preferences ${diagnostic.kind}: ${formatPreferenceDiagnosticDetail(diagnostic)}`,
+            file: diagnostic.path,
+            fixable: false,
+        });
+    }
     if (prefs) {
         const prefIssues = validatePreferenceShape(prefs.preferences);
         for (const issue of prefIssues) {
@@ -326,7 +335,7 @@ 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);
     const gitMs = Date.now() - t0git;
     // Runtime health checks — timed
     const t0runtime = Date.now();
@@ -345,7 +354,8 @@ export async function runGSDDoctor(basePath, options) {
     // Engine health checks — DB constraints and projection drift
     await checkEngineHealth(basePath, issues, fixesApplied);
     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;
@@ -389,7 +399,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)
@@ -426,8 +442,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);
@@ -567,6 +592,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",
@@ -732,7 +760,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/engine-hook-contract.js

@@ -0,0 +1,70 @@
+// Project/App: gsd-pi
+// File Purpose: Typed contract for which tool lifecycle hooks fire under which
+// engine, plus the single seam for tool-name normalization.
+//
+// ── Why this contract exists ────────────────────────────────────────────────
+// External engines (claude-code-cli) pre-execute tools inside the vendor CLI
+// and hand the agent loop a `toolCall.externalResult`. The loop short-circuits
+// before `beforeToolCall`/`afterToolCall` ever run for those calls
+// (packages/pi-agent-core/src/agent-loop.ts, prepareToolCall: the
+// externalResult branch returns an "immediate" outcome before the
+// config.beforeToolCall invocation, and "immediate" outcomes skip
+// finalizeExecutedToolCall where config.afterToolCall lives).
+// `beforeToolCall`/`afterToolCall` are exactly what the extension runner maps
+// to the `tool_call`/`tool_result` extension events
+// (packages/gsd-agent-core/src/session/agent-session-extensions.ts,
+// installAgentToolHooks).
+//
+// `tool_execution_start` is emitted unconditionally before prepareToolCall
+// and `tool_execution_end` after every finalized outcome — immediate or
+// executed — so those two are the ONLY tool lifecycle hooks that fire for
+// every tool call on every engine.
+//
+// Consequence: any enforcement attached only to `tool_call` (blocking) or
+// `tool_result` (rewriting) is silently dead under external engines. Safety
+// enforcement must ride `tool_execution_start`/`tool_execution_end`, or
+// mirror across both with toolCallId dedup. See the per-registration contract
+// comments in bootstrap/register-hooks.ts for how each registered hook
+// honors (or knowingly violates) this contract.
+import { stripMcpToolPrefix } from "./mcp-tool-name.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+/**
+ * Tool lifecycle hooks that fire for EVERY tool call on EVERY engine,
+ * including external engines (claude-code-cli) that pre-execute tools.
+ * Attach safety-critical enforcement and evidence collection here.
+ */
+export const UNIVERSAL_TOOL_HOOKS = ["tool_execution_start", "tool_execution_end"];
+/**
+ * Tool lifecycle hooks that fire ONLY for natively executed tools. External
+ * engines pre-execute tools (externalResult), short-circuiting the agent
+ * loop's beforeToolCall/afterToolCall — so handlers on these events never run
+ * for those calls. Blocking guards attached only here are dead under external
+ * engines; they need a tool_execution_start mirror to be universal.
+ */
+export const NATIVE_ONLY_TOOL_HOOKS = ["tool_call", "tool_result"];
+// Non-tool lifecycle events (session_start, agent_end, message_update, ...)
+// are intentionally NOT classified here: they are emitted by the session
+// host / extension runner independent of tool execution, so the external
+// engine short-circuit above does not apply to them. Only classify events
+// whose engine behavior has been verified against the agent loop.
+/**
+ * Canonical tool name: strips the `mcp__<server>__` prefix when present,
+ * nothing else. Use for identity checks against host/native tool names and
+ * for any guard that must NOT conflate workflow aliases with their canonical
+ * tools (e.g. write gates, evidence keys).
+ *
+ * Malformed MCP names (empty server or empty tool segment, e.g.
+ * `mcp____tool` or `mcp__server__`) are returned unchanged.
+ */
+export function canonicalToolName(toolName) {
+    return stripMcpToolPrefix(toolName);
+}
+/**
+ * Workflow-aware canonical tool name: strips the MCP prefix AND resolves
+ * workflow tool aliases to their canonical contract names. Use whenever the
+ * name is compared against the workflow tool surface (scoping, presentation,
+ * dispatch) — plain {@link canonicalToolName} would miss alias spellings.
+ */
+export function canonicalWorkflowToolName(toolName) {
+    return canonicalWorkflowSurfaceToolName(toolName);
+}

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

@@ -9,6 +9,7 @@
  *
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
+import { TOOL_SURFACE_NOT_READY, isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 export function createRetryState() {
     return { networkRetryCount: 0, consecutiveTransientCount: 0, currentRetryModelId: undefined };
 }
@@ -32,7 +33,7 @@ const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient cre
 // are emitted by SDK/harness transports for mid-stream disconnects.
 // These indicate transient network-level interruptions.
 // See: https://github.com/open-gsd/gsd-pi/issues/4558
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received/i;
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received|stream ended without finish_reason/i;
 // Context overflow errors (context window/length exceeded) should be treated as server-class
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528
@@ -44,6 +45,10 @@ const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side close
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
 const RESET_DELAY_RE = /reset in (\d+)s/i;
 const TOOL_SCHEMA_RE = /schema overload|consecutive tool validation failures/i;
+// GSD tool-surface readiness abort (claude-code stream adapter): the workflow
+// MCP server had not registered the Unit's required tools at SDK init. The
+// server typically finishes connecting within seconds — same-model retry.
+const TOOL_SURFACE_NOT_READY_RE = new RegExp(TOOL_SURFACE_NOT_READY, "i");
 // Provider rejected the request shape for the selected model (400 bad request,
 // grammar limits, etc.). Not transient — try a different model/fallback.
 // Context-window 400s stay in SERVER_RE (checked earlier).
@@ -77,6 +82,22 @@ 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 };
+    }
     const isPermanent = PERMANENT_RE.test(errorMsg);
     const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
     const isUnsupportedModel = UNSUPPORTED_MODEL_MODEL_RE.test(errorMsg) &&

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. */