gsd-pi 2.75.0-next.9c0ec0ba1 → 2.76.0-dev.b072ebb73

package/dist/onboarding.js

@@ -15,6 +15,8 @@ import { dirname, join } from 'node:path';
 import { renderLogo } from './logo.js';
 import { agentDir } from './app-paths.js';
 import { isClaudeCliReady } from './claude-cli-check.js';
+import { markOnboardingComplete, markStepCompleted, markStepSkipped, isOnboardingComplete, } from './resources/extensions/gsd/onboarding-state.js';
+import { getLlmProviderIds } from './resources/extensions/gsd/setup-catalog.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
 const TOOL_KEYS = [
     {
@@ -36,25 +38,17 @@ const TOOL_KEYS = [
         hint: 'voice transcription — free at console.groq.com',
     },
 ];
-/** Known LLM provider IDs that, if authed, mean the user doesn't need onboarding */
-const LLM_PROVIDER_IDS = [
-    'anthropic',
+/**
+ * Known LLM provider IDs that, if authed, mean the user doesn't need onboarding.
+ * Sourced from the shared setup-catalog so adding a provider lands in one place.
+ * 'anthropic-vertex' and 'ollama' aren't in PROVIDER_REGISTRY but are still
+ * treated as "authed = no onboarding needed" for back-compat.
+ */
+const LLM_PROVIDER_IDS = Array.from(new Set([
+    ...getLlmProviderIds(),
     'anthropic-vertex',
-    'claude-code',
-    'openai',
-    'github-copilot',
-    'openai-codex',
-    'google-gemini-cli',
-    'google-antigravity',
-    'google',
-    'groq',
-    'xai',
-    'openrouter',
-    'mistral',
     'ollama',
-    'ollama-cloud',
-    'custom-openai',
-];
+]));
 /** API key prefix validation — loose checks to catch obvious mistakes */
 const API_KEY_PREFIXES = {
     anthropic: ['sk-ant-'],
@@ -178,6 +172,10 @@ async function runStep(p, warnLabel, fn, opts = {}) {
 export function shouldRunOnboarding(authStorage, settingsDefaultProvider) {
     if (!process.stdin.isTTY)
         return false;
+    // Explicit completion record wins — user has already finished onboarding (and
+    // our flowVersion hasn't bumped since).
+    if (isOnboardingComplete())
+        return false;
     if (settingsDefaultProvider)
         return false;
     // Check if any LLM provider has credentials
@@ -196,7 +194,7 @@ export function shouldRunOnboarding(authStorage, settingsDefaultProvider) {
  * All steps are skippable. All errors are recoverable.
  * Writes status to stderr during execution.
  */
-export async function runOnboarding(authStorage) {
+export async function runOnboarding(authStorage, opts = {}) {
     let p;
     let pc;
     try {
@@ -209,31 +207,62 @@ export async function runOnboarding(authStorage) {
         return;
     }
     // ── Intro ─────────────────────────────────────────────────────────────────
-    process.stderr.write(renderLogo(pc.cyan));
-    p.intro(pc.bold('Welcome to GSD — let\'s get you set up'));
+    if (opts.showIntro !== false) {
+        process.stderr.write(renderLogo(pc.cyan));
+        p.intro(pc.bold('Welcome to GSD — let\'s get you set up'));
+    }
+    const completedSteps = [];
     // ── LLM Provider Selection ────────────────────────────────────────────────
     const llmResult = await runStep(p, 'LLM setup failed', () => runLlmStep(p, pc, authStorage), {
-        cancelMessage: 'Setup cancelled — you can run /login inside GSD later.',
+        cancelMessage: 'Setup cancelled — you can run /gsd onboarding --resume later.',
         errorInfo: 'You can configure your LLM provider later with /login inside GSD.',
     });
     if (llmResult === STEP_CANCELLED)
         return;
     const llmConfigured = llmResult ?? false;
+    if (llmConfigured) {
+        markStepCompleted('llm');
+        completedSteps.push('llm');
+    }
+    else {
+        markStepSkipped('llm');
+    }
     // ── Web Search Provider ──────────────────────────────────────────────────
     const searchResult = await runStep(p, 'Web search setup failed', () => runWebSearchStep(p, pc, authStorage, llmConfigured));
     if (searchResult === STEP_CANCELLED)
         return;
     const searchConfigured = searchResult;
+    if (searchConfigured) {
+        markStepCompleted('search');
+        completedSteps.push('search');
+    }
+    else {
+        markStepSkipped('search');
+    }
     // ── Remote Questions ─────────────────────────────────────────────────────
     const remoteResult = await runStep(p, 'Remote questions setup failed', () => runRemoteQuestionsStep(p, pc, authStorage));
     if (remoteResult === STEP_CANCELLED)
         return;
     const remoteConfigured = remoteResult;
+    if (remoteConfigured) {
+        markStepCompleted('remote');
+        completedSteps.push('remote');
+    }
+    else {
+        markStepSkipped('remote');
+    }
     // ── Tool API Keys ─────────────────────────────────────────────────────────
     const toolResult = await runStep(p, 'Tool key setup failed', () => runToolKeysStep(p, pc, authStorage));
     if (toolResult === STEP_CANCELLED)
         return;
     const toolKeyCount = toolResult ?? 0;
+    if (toolKeyCount > 0) {
+        markStepCompleted('tool-keys');
+        completedSteps.push('tool-keys');
+    }
+    else {
+        markStepSkipped('tool-keys');
+    }
     // ── Summary ───────────────────────────────────────────────────────────────
     const summaryLines = [];
     if (llmConfigured) {
@@ -268,11 +297,17 @@ export async function runOnboarding(authStorage) {
     else {
         summaryLines.push(`${pc.dim('↷')} Tool keys: none configured`);
     }
+    // Persist completion record so re-entry, web boot probe, and shouldRunOnboarding
+    // all agree the wizard finished. Required steps drive the "complete" semantics
+    // in onboarding-state.ts; here we mark wizard-level completion regardless.
+    markOnboardingComplete(completedSteps);
+    summaryLines.push('');
+    summaryLines.push(`${pc.dim('Tip:')} re-run anytime with ${pc.cyan('/gsd onboarding')}`);
     p.note(summaryLines.join('\n'), 'Setup complete');
     p.outro(pc.dim('Launching GSD...'));
 }
 // ─── LLM Authentication Step ──────────────────────────────────────────────────
-async function runLlmStep(p, pc, authStorage) {
+export async function runLlmStep(p, pc, authStorage) {
     // Build the OAuth provider list dynamically from what's registered
     const oauthProviders = authStorage.getOAuthProviders();
     const oauthMap = new Map(oauthProviders.map(op => [op.id, op]));
@@ -572,7 +607,7 @@ async function runCustomOpenAIFlow(p, pc, authStorage) {
     return true;
 }
 // ─── Web Search Provider Step ─────────────────────────────────────────────────
-async function runWebSearchStep(p, pc, authStorage, isAnthropicAuth) {
+export async function runWebSearchStep(p, pc, authStorage, isAnthropicAuth) {
     // Check which LLM provider was configured
     const authed = authStorage.list().filter(id => LLM_PROVIDER_IDS.includes(id));
     const isAnthropic = isAnthropicAuth && authed.includes('anthropic');
@@ -633,7 +668,7 @@ async function runWebSearchStep(p, pc, authStorage, isAnthropicAuth) {
     return null;
 }
 // ─── Tool API Keys Step ───────────────────────────────────────────────────────
-async function runToolKeysStep(p, pc, authStorage) {
+export async function runToolKeysStep(p, pc, authStorage) {
     // Filter to keys not already configured
     const missing = TOOL_KEYS.filter(tk => !authStorage.has(tk.provider) && !process.env[tk.envVar]);
     if (missing.length === 0)
@@ -668,7 +703,7 @@ async function runToolKeysStep(p, pc, authStorage) {
     return savedCount;
 }
 // ─── Remote Questions Step ────────────────────────────────────────────────────
-async function runRemoteQuestionsStep(p, pc, authStorage) {
+export async function runRemoteQuestionsStep(p, pc, authStorage) {
     // Check existing config — use getCredentialsForProvider to skip empty-key entries
     const hasValidKey = (provider) => authStorage
         .getCredentialsForProvider(provider)

package/dist/resources/agents/researcher.md

@@ -1,7 +1,7 @@
 ---
 name: researcher
 description: Web researcher that finds and synthesizes current information using Brave Search
-tools: search-the-web, bash
+tools: search-the-web, bash, capture_thought, memory_query, gsd_graph
 ---
 
 You are a web researcher. You find current, accurate information using web search and synthesize it into a clear, well-structured report.

package/dist/resources/extensions/ask-user-questions.js

@@ -316,10 +316,13 @@ export default function AskUserQuestions(pi) {
                             lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
                             continue;
                         }
-                        const answerText = answer.answers.length > 0 ? answer.answers.join(", ") : "(custom)";
+                        const selected = answer.selected;
+                        const answerText = Array.isArray(selected)
+                            ? (selected.length > 0 ? selected.join(", ") : "(custom)")
+                            : (selected || "(custom)");
                         let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
-                        if (answer.user_note) {
-                            line += ` ${theme.fg("muted", `[note: ${answer.user_note}]`)}`;
+                        if (answer.notes) {
+                            line += ` ${theme.fg("muted", `[note: ${answer.notes}]`)}`;
                         }
                         lines.push(line);
                     }

package/dist/resources/extensions/claude-code-cli/readiness.js

@@ -9,6 +9,38 @@
  * and check the exit code + output for an authenticated session.
  */
 import { execFileSync } from "node:child_process";
+/**
+ * Candidate executable names for the Claude Code CLI.
+ *
+ * Keep the explicit win32 ternary selector for regression coverage (Issue #4424):
+ * Node's execFileSync must target `claude.cmd` directly on Windows.
+ */
+const CLAUDE_COMMAND = process.platform === "win32" ? "claude.cmd" : "claude";
+/**
+ * Windows installs vary: some environments expose `claude.cmd` (npm shim),
+ * others expose a `claude` shim on PATH (for example Git Bash wrappers).
+ * Try both to avoid false "not installed" results in readiness checks.
+ */
+const CLAUDE_COMMAND_CANDIDATES = process.platform === "win32" ? [CLAUDE_COMMAND, "claude"] : [CLAUDE_COMMAND];
+function execClaude(args) {
+    let lastError;
+    for (const command of CLAUDE_COMMAND_CANDIDATES) {
+        try {
+            return execFileSync(command, args, { timeout: 5_000, stdio: "pipe" });
+        }
+        catch (error) {
+            lastError = error;
+            const code = error?.code;
+            // Windows Git Bash can surface `.cmd` spawn failures as EINVAL instead
+            // of ENOENT. Treat both as "try next candidate".
+            if (code === "ENOENT" || code === "EINVAL") {
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw lastError ?? new Error(`Claude CLI executable not found (tried: ${CLAUDE_COMMAND_CANDIDATES.join(", ")})`);
+}
 let cachedBinaryPresent = null;
 let cachedAuthed = null;
 let lastCheckMs = 0;
@@ -22,7 +54,7 @@ function refreshCache() {
     lastCheckMs = now;
     // Check binary presence
     try {
-        execFileSync("claude", ["--version"], { timeout: 5_000, stdio: "pipe" });
+        execClaude(["--version"]);
         cachedBinaryPresent = true;
     }
     catch {
@@ -32,7 +64,7 @@ function refreshCache() {
     }
     // Check auth status — exit code 0 with non-error output means authenticated
     try {
-        const output = execFileSync("claude", ["auth", "status"], { timeout: 5_000, stdio: "pipe" })
+        const output = execClaude(["auth", "status"])
             .toString()
             .toLowerCase();
         // The CLI outputs "not logged in", "no credentials", or similar when unauthenticated

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -11,7 +11,9 @@ import { execSync } from "node:child_process";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
 import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js";
 import { showInterviewRound } from "../shared/tui.js";
+/** Label used for the free-text fallback option in single-choice elicitation questions. */
 const OTHER_OPTION_LABEL = "None of the above";
+/** Regex pattern that identifies field names and descriptions that should be treated as sensitive/secure inputs. */
 const SENSITIVE_FIELD_PATTERN = /(password|passphrase|secret|token|api[_\s-]*key|private[_\s-]*key|credential)/i;
 // ---------------------------------------------------------------------------
 // Stream factory
@@ -29,6 +31,7 @@ function createAssistantStream() {
         throw new Error("Unexpected event type for final result");
     });
 }
+/** Extract a human-readable error string from an SDK result message. */
 export function getResultErrorMessage(result) {
     if ("errors" in result && Array.isArray(result.errors) && result.errors.length > 0) {
         return result.errors.join("; ");
@@ -41,10 +44,13 @@ export function getResultErrorMessage(result) {
 // ---------------------------------------------------------------------------
 // Claude binary resolution
 // ---------------------------------------------------------------------------
+/** Cached result of the `which`/`where claude` lookup so the shell is only spawned once per process. */
 let cachedClaudePath = null;
+/** Return the shell command used to locate the `claude` binary on the given platform. */
 export function getClaudeLookupCommand(platform = process.platform) {
     return platform === "win32" ? "where claude" : "which claude";
 }
+/** Extract the first line of `which`/`where` output as the resolved binary path. */
 export function parseClaudeLookupOutput(output) {
     return output
         .toString()
@@ -123,6 +129,7 @@ export function buildPromptFromContext(context) {
     }
     return parts.join("\n\n");
 }
+/** Strip the `data:<mime>;base64,` prefix from a data URI, returning only the raw base64 payload. */
 function stripDataUriPrefix(value) {
     const commaIndex = value.indexOf(",");
     if (value.startsWith("data:") && commaIndex !== -1) {
@@ -130,10 +137,12 @@ function stripDataUriPrefix(value) {
     }
     return value;
 }
+/** Extract the MIME type from a data URI string, or return `null` if the value is not a valid data URI. */
 function inferMimeTypeFromDataUri(value) {
     const match = /^data:([^;,]+);base64,/.exec(value);
     return match?.[1] ?? null;
 }
+/** Collect all base64 image blocks from user messages in the context for inclusion in the SDK prompt. */
 export function extractImageBlocksFromContext(context) {
     const imageBlocks = [];
     for (const msg of context.messages) {
@@ -162,6 +171,7 @@ export function extractImageBlocksFromContext(context) {
     }
     return imageBlocks;
 }
+/** Build the SDK query prompt, wrapping image blocks into an async iterable user message when present. */
 export function buildSdkQueryPrompt(context, textPrompt = buildPromptFromContext(context)) {
     const imageBlocks = extractImageBlocksFromContext(context);
     if (imageBlocks.length === 0) {
@@ -183,6 +193,7 @@ export function buildSdkQueryPrompt(context, textPrompt = buildPromptFromContext
 // ---------------------------------------------------------------------------
 // Error helper
 // ---------------------------------------------------------------------------
+/** Build a minimal error `AssistantMessage` with the given model ID and error text. */
 function makeErrorMessage(model, errorMsg) {
     return {
         role: "assistant",
@@ -209,6 +220,7 @@ export function makeStreamExhaustedErrorMessage(model, lastTextContent) {
     }
     return message;
 }
+/** Extract the string labels from an array of SDK elicitation option objects, filtering out blank entries. */
 function readElicitationChoices(options) {
     if (!Array.isArray(options))
         return [];
@@ -216,6 +228,7 @@ function readElicitationChoices(options) {
         .map((option) => (typeof option?.const === "string" ? option.const : typeof option?.title === "string" ? option.title : ""))
         .filter((option) => option.length > 0);
 }
+/** Parse an SDK elicitation request into structured multiple-choice questions, or null if the schema is unsupported. */
 export function parseAskUserQuestionsElicitation(request) {
     if (request.mode && request.mode !== "form")
         return null;
@@ -265,6 +278,7 @@ export function parseAskUserQuestionsElicitation(request) {
     }
     return questions.length > 0 ? questions : null;
 }
+/** Return true if the elicitation field should be treated as sensitive and rendered as a secure/password input. */
 function isSecureElicitationField(requestMessage, fieldId, field) {
     if (field.format === "password")
         return true;
@@ -283,6 +297,7 @@ function isSecureElicitationField(requestMessage, fieldId, field) {
         .toLowerCase();
     return SENSITIVE_FIELD_PATTERN.test(haystack);
 }
+/** Parse an SDK elicitation request into free-text input field descriptors, or null if unsupported. */
 export function parseTextInputElicitation(request) {
     if (request.mode && request.mode !== "form")
         return null;
@@ -315,6 +330,7 @@ export function parseTextInputElicitation(request) {
     }
     return fields.length > 0 ? fields : null;
 }
+/** Convert a TUI interview round result into the SDK elicitation content map. */
 export function roundResultToElicitationContent(questions, result) {
     const content = {};
     for (const question of questions) {
@@ -334,6 +350,7 @@ export function roundResultToElicitationContent(questions, result) {
     }
     return content;
 }
+/** Build the dialog title string for a multiple-choice elicitation question, combining server name, header, and question text. */
 function buildElicitationPromptTitle(request, question) {
     const parts = [
         request.serverName ? `[${request.serverName}]` : "",
@@ -342,6 +359,7 @@ function buildElicitationPromptTitle(request, question) {
     ].filter((part) => part && part.trim().length > 0);
     return parts.join("\n\n");
 }
+/** Drive each multiple-choice elicitation question through the extension UI's `select` dialog, collecting answers into an SDK result. */
 async function promptElicitationWithDialogs(request, questions, ui, signal) {
     const content = {};
     for (const question of questions) {
@@ -379,6 +397,7 @@ async function promptElicitationWithDialogs(request, questions, ui, signal) {
     }
     return { action: "accept", content };
 }
+/** Build the dialog title string for a free-text input field, combining server name, field title, and description. */
 function buildTextInputPromptTitle(request, field) {
     const parts = [
         request.serverName ? `[${request.serverName}]` : "",
@@ -387,6 +406,7 @@ function buildTextInputPromptTitle(request, field) {
     ].filter((part) => typeof part === "string" && part.trim().length > 0);
     return parts.join("\n\n");
 }
+/** Derive a placeholder hint for a free-text input field from its description, falling back to "Required" or "Leave empty to skip". */
 function buildTextInputPlaceholder(field) {
     const desc = field.description.trim();
     if (!desc)
@@ -400,6 +420,7 @@ function buildTextInputPlaceholder(field) {
     const hint = formatLine.replace(/^format:\s*/i, "").trim();
     return hint.length > 0 ? hint : field.required ? "Required" : "Leave empty to skip";
 }
+/** Collect each free-text input field via the extension UI's `input` dialog, returning the filled SDK elicitation result. */
 async function promptTextInputElicitation(request, fields, ui, signal) {
     const content = {};
     for (const field of fields) {
@@ -411,6 +432,7 @@ async function promptTextInputElicitation(request, fields, ui, signal) {
     }
     return { action: "accept", content };
 }
+/** Create an SDK elicitation handler that routes requests through the extension UI dialogs, or undefined if no UI is available. */
 export function createClaudeCodeElicitationHandler(ui) {
     if (!ui)
         return undefined;
@@ -485,14 +507,20 @@ export async function resolveClaudePermissionMode(env = process.env) {
 // NOTE: These helpers intentionally mirror @gsd/pi-ai anthropic-shared
 // behavior so this extension remains typecheck-stable even when the published
 // @gsd/pi-ai barrel lags behind monorepo source exports.
+/** Return true for model IDs that support the adaptive thinking API (Opus 4.6/4.7, Sonnet 4.6/4.7, Haiku 4.5). */
 function modelSupportsAdaptiveThinking(modelId) {
     return (modelId.includes("opus-4-6")
         || modelId.includes("opus-4.6")
         || modelId.includes("opus-4-7")
         || modelId.includes("opus-4.7")
         || modelId.includes("sonnet-4-6")
-        || modelId.includes("sonnet-4.6"));
+        || modelId.includes("sonnet-4.6")
+        || modelId.includes("sonnet-4-7")
+        || modelId.includes("sonnet-4.7")
+        || modelId.includes("haiku-4-5")
+        || modelId.includes("haiku-4.5"));
 }
+/** Map a GSD thinking level to the Anthropic effort value, clamping xhigh to max for models that lack native xhigh support. */
 function mapThinkingLevelToAnthropicEffort(level, modelId) {
     switch (level) {
         case "minimal":
@@ -543,9 +571,18 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         "Bash(pwd)",
         ...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
     ];
-    const effort = reasoning && modelSupportsAdaptiveThinking(modelId)
+    const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
+    const effort = reasoning && supportsAdaptive
         ? mapThinkingLevelToAnthropicEffort(reasoning, modelId)
         : undefined;
+    // Bug B: SDK requires thinking:{type:"adaptive"} alongside effort for adaptive thinking to activate.
+    // Bug C: SDK requires thinking:{type:"disabled"} to actually stop adaptive thinking when reasoning is off;
+    //        omitting the field leaves the SDK in its adaptive default (or persisted session state).
+    const thinkingConfig = supportsAdaptive
+        ? effort
+            ? { thinking: { type: "adaptive" } }
+            : { thinking: { type: "disabled" } }
+        : undefined;
     return {
         pathToClaudeCodeExecutable: getClaudePath(),
         model: modelId,
@@ -560,10 +597,12 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         ...(allowedTools.length > 0 ? { allowedTools } : {}),
         ...(mcpServers ? { mcpServers } : {}),
         betas: (modelId.includes("sonnet") || modelId.includes("opus-4-7") || modelId.includes("opus-4.7")) ? ["context-1m-2025-08-07"] : [],
+        ...(thinkingConfig ?? {}),
         ...(effort ? { effort } : {}),
         ...sdkExtraOptions,
     };
 }
+/** Normalise heterogeneous SDK tool-result content (string, array, or object) into a uniform `ExternalToolResultContentBlock[]`. */
 function normalizeToolResultContent(content) {
     if (typeof content === "string") {
         return [{ type: "text", text: content }];
@@ -598,6 +637,7 @@ function normalizeToolResultContent(content) {
     }
     return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
 }
+/** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
 export function extractToolResultsFromSdkUserMessage(message) {
     const extracted = [];
     const seen = new Set();
@@ -642,6 +682,7 @@ export function extractToolResultsFromSdkUserMessage(message) {
     }
     return extracted;
 }
+/** Attach external tool results from the SDK synthetic user message to their corresponding tool-call blocks by ID. */
 function attachExternalResultsToToolBlocks(toolBlocks, toolResultsById) {
     for (const block of toolBlocks) {
         if (block.type !== "toolCall" && block.type !== "serverToolUse")
@@ -689,6 +730,7 @@ export function streamViaClaudeCode(model, context, options) {
     void pumpSdkMessages(model, context, options, stream);
     return stream;
 }
+/** Async pump that drives the Claude Agent SDK's async-iterable message stream and pushes events into `stream`. */
 async function pumpSdkMessages(model, context, options, stream) {
     const modelId = model.id;
     let builder = null;

package/dist/resources/extensions/gsd/auto/phases.js

@@ -607,6 +607,8 @@ export async function runDispatch(ic, preData, loopState) {
         prefs,
         session: s,
         structuredQuestionsAvailable,
+        sessionContextWindow: ctx.model?.contextWindow,
+        modelRegistry: ctx.modelRegistry,
     });
     if (dispatchResult.action === "stop") {
         deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "dispatch-stop", rule: dispatchResult.matchedRule, data: { reason: dispatchResult.reason } });
@@ -821,16 +823,44 @@ export async function runGuards(ic, mid) {
         if (threshold) {
             s.lastBudgetAlertLevel =
                 newBudgetAlertLevel;
-            if (threshold.pct === 100 && budgetEnforcementAction !== "none") {
+            // Emit Layer 2 budget_threshold event (post-plan hook recommendation).
+            // Extensions / Layer 0 shell hooks may return an action override.
+            let hookAction;
+            try {
+                const { emitBudgetThreshold } = await import("../hook-emitter.js");
+                const hookResult = await emitBudgetThreshold({
+                    fraction: budgetPct,
+                    spent: totalCost,
+                    limit: budgetCeiling,
+                });
+                if (hookResult?.action)
+                    hookAction = hookResult.action;
+            }
+            catch (hookErr) {
+                logWarning("engine", `budget_threshold hook emission failed: ${hookErr.message}`);
+            }
+            // Apply hook override to enforcement action. "continue" → "none" (no enforcement),
+            // "pause" and "downgrade" map to the matching enforcement path below.
+            let effectiveAction = budgetEnforcementAction;
+            if (hookAction === "continue") {
+                effectiveAction = "none";
+            }
+            else if (hookAction === "pause") {
+                effectiveAction = "pause";
+            }
+            else if (hookAction === "downgrade") {
+                effectiveAction = "warn";
+            }
+            if (threshold.pct === 100 && effectiveAction !== "none") {
                 // 100% — special enforcement logic (halt/pause/warn)
                 const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`;
-                if (budgetEnforcementAction === "halt") {
+                if (effectiveAction === "halt") {
                     deps.sendDesktopNotification("GSD", msg, "error", "budget", basename(s.originalBasePath || s.basePath));
                     await deps.stopAuto(ctx, pi, "Budget ceiling reached");
                     debugLog("autoLoop", { phase: "exit", reason: "budget-halt" });
                     return { action: "break", reason: "budget-halt" };
                 }
-                if (budgetEnforcementAction === "pause") {
+                if (effectiveAction === "pause") {
                     ctx.ui.notify(`${msg} Pausing auto-mode — /gsd auto to override and continue.`, "warning");
                     deps.sendDesktopNotification("GSD", msg, "warning", "budget", basename(s.originalBasePath || s.basePath));
                     deps.logCmuxEvent(prefs, msg, "warning");
@@ -1171,20 +1201,23 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         }
     }
     if (unitResult.status === "cancelled") {
+        const errorCategory = unitResult.errorContext?.category;
         // Provider-error pause: pauseAuto already handled cleanup and scheduled
         // recovery. Don't hard-stop — just break out of the loop (#2762).
-        if (unitResult.errorContext?.category === "provider") {
+        if (errorCategory === "provider") {
             await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
-            debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext.isTransient });
+            debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext?.isTransient });
             return { action: "break", reason: "provider-pause" };
         }
         // Timeout category covers two distinct scenarios:
         //   1. Session creation timeout (120s) — transient, auto-resume with backoff
         //   2. Unit hard timeout (30min+) — stuck agent, pause for manual review
+        // Transient session-failed covers recoverable newSession failures and should
+        // pause instead of hard-stopping.
         // Structural errors (TypeError, is not a function) are NOT transient
         // and must hard-stop to avoid infinite retry loops.
         if (unitResult.errorContext?.isTransient &&
-            unitResult.errorContext?.category === "timeout") {
+            errorCategory === "timeout") {
             const isSessionCreationTimeout = unitResult.errorContext.message?.includes("Session creation timed out");
             if (isSessionCreationTimeout) {
                 consecutiveSessionTimeouts += 1;
@@ -1227,6 +1260,15 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
             await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
             return { action: "break", reason: "unit-hard-timeout" };
         }
+        if (unitResult.errorContext?.isTransient &&
+            errorCategory === "session-failed") {
+            ctx.ui.notify(`Session creation failed transiently for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Pausing auto-mode (recoverable).`, "warning");
+            debugLog("autoLoop", { phase: "session-start-transient-pause", unitType, unitId, category: errorCategory });
+            await deps.pauseAuto(ctx, pi);
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            return { action: "break", reason: "session-timeout" };
+        }
         // All other cancelled states (structural errors, non-transient failures): hard stop
         if (s.currentUnit) {
             await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));

package/dist/resources/extensions/gsd/auto-artifact-paths.js

@@ -29,6 +29,16 @@ export function resolveExpectedArtifactPath(unitType, unitId, base) {
             return dir ? join(dir, buildMilestoneFileName(mid, "ROADMAP")) : null;
         }
         case "research-slice": {
+            // #4414: Sentinel unitId "{mid}/parallel-research" fans out across
+            // multiple slices. Resolve to a milestone-level placeholder path so
+            // blocker escalation has somewhere to write. Verification for this
+            // sentinel is handled directly in verifyExpectedArtifact.
+            if (sid === "parallel-research") {
+                const mdir = resolveMilestonePath(base, mid);
+                return mdir
+                    ? join(mdir, buildMilestoneFileName(mid, "PARALLEL-BLOCKER"))
+                    : null;
+            }
             const dir = resolveSlicePath(base, mid, sid);
             return dir ? join(dir, buildSliceFileName(sid, "RESEARCH")) : null;
         }
@@ -36,6 +46,11 @@ export function resolveExpectedArtifactPath(unitType, unitId, base) {
             const dir = resolveSlicePath(base, mid, sid);
             return dir ? join(dir, buildSliceFileName(sid, "PLAN")) : null;
         }
+        case "refine-slice": {
+            // ADR-011: refine-slice expands a sketch and writes the same PLAN.md as plan-slice.
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir ? join(dir, buildSliceFileName(sid, "PLAN")) : null;
+        }
         case "reassess-roadmap": {
             const dir = resolveSlicePath(base, mid, sid);
             return dir ? join(dir, buildSliceFileName(sid, "ASSESSMENT")) : null;
@@ -90,9 +105,14 @@ export function diagnoseExpectedArtifact(unitType, unitId, base) {
         case "plan-milestone":
             return `${relMilestoneFile(base, mid, "ROADMAP")} (milestone roadmap)`;
         case "research-slice":
+            if (sid === "parallel-research") {
+                return `${relMilestoneFile(base, mid, "PARALLEL-BLOCKER")} (parallel slice research sentinel)`;
+            }
             return `${relSliceFile(base, mid, sid, "RESEARCH")} (slice research)`;
         case "plan-slice":
             return `${relSliceFile(base, mid, sid, "PLAN")} (slice plan)`;
+        case "refine-slice":
+            return `${relSliceFile(base, mid, sid, "PLAN")} (refined slice plan from sketch)`;
         case "execute-task": {
             return `Task ${tid} marked [x] in ${relSliceFile(base, mid, sid, "PLAN")} + summary written`;
         }