@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.822c9439

package/dist/resources/extensions/browser-tools/index.js

@@ -1,7 +1,7 @@
 /** browser-tools — Pi Browser Automation Contract adapter. */
 import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { closeManagedGsdBrowser, registerManagedGsdBrowserTools, warmUpManagedGsdBrowser } from "./engine/managed-gsd-browser.js";
-import { resolveBrowserEngineMode } from "./engine/selection.js";
+import { commitBrowserEngineResolution, resolveAmbientBrowserEngineResolution } from "./engine/selection.js";
 import { setArtifactRootForCwd } from "./state.js";
 import { detectWebApp } from "./web-app-detect.js";
 let legacyRegistrationPromise = null;
@@ -130,12 +130,56 @@ function withBrowserArtifactCwdScope(pi) {
         },
     };
 }
-async function registerBrowserTools(pi) {
-    const engine = resolveBrowserEngineMode();
+/** Daemon-connect budget when the probe-resolved managed engine is verified at session start. */
+const PROBE_WARMUP_TIMEOUT_MS = 10_000;
+async function registerBrowserTools(pi, ctx) {
+    const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    let engine = resolution.engine;
     if (engine === "off")
         return;
+    // A probe-resolved managed engine is only a prediction that gsd-browser
+    // works — prove it by connecting the daemon before committing the session's
+    // tool registrations to it. Connect failure falls back to legacy Playwright
+    // (the failure mode that made ADR-024 freeze the old default) and commits
+    // the outcome so ambient readers see the engine actually in use. When eager
+    // warm-up is disabled the daemon-connect proof cannot run, so the probe
+    // default treats the managed engine as unprovable and falls back to legacy
+    // rather than registering it unverified. An explicit
+    // GSD_BROWSER_ENGINE=gsd-browser override skips the gate and is honored
+    // verbatim, matching prior behavior.
+    if (engine === "gsd-browser" && resolution.source === "probe" && !registeredEngine) {
+        if (isWarmUpDisabled()) {
+            engine = commitLegacyFallback(projectRoot, "warm-up disabled; managed engine unverifiable; using legacy Playwright");
+        }
+        else {
+            const warmUp = await warmUpManagedGsdBrowser(ctx, AbortSignal.timeout(PROBE_WARMUP_TIMEOUT_MS));
+            if (!warmUp.ok) {
+                engine = commitLegacyFallback(projectRoot, `gsd-browser daemon connect failed (${warmUp.error}); using legacy Playwright`);
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`gsd-browser engine unavailable (${warmUp.error}); using Playwright browser tools for this session.`, "warning");
+                }
+            }
+            else if (warmUp.coverageWarning && ctx.hasUI) {
+                ctx.ui.notify(warmUp.coverageWarning, "warning");
+            }
+        }
+    }
+    // Browser tool registrations are process-global and cannot be swapped once
+    // live. When an earlier session in this process already registered an engine
+    // and this project resolved a different one (per-project probe resolution can
+    // diverge across projects in a multi-session process), adopt the registered
+    // engine rather than throwing — a throw surfaces as "browser-tools failed to
+    // load" and leaves this session with no browser tools at all. Commit the
+    // adoption so ambient readers (UAT guidance, warm-up) describe the engine
+    // actually in use.
     if (registeredEngine && registeredEngine !== engine) {
-        throw new Error(`Browser tools already registered with GSD_BROWSER_ENGINE=${registeredEngine}. Restart GSD before switching to ${engine}.`);
+        engine = registeredEngine;
+        commitBrowserEngineResolution(projectRoot, {
+            engine,
+            source: "probe",
+            reason: `browser tools already registered with ${engine} earlier in this process; adopting it`,
+        });
     }
     let registration;
     if (engine === "legacy") {
@@ -165,27 +209,40 @@ async function registerBrowserTools(pi) {
         throw error;
     }
 }
+function commitLegacyFallback(projectRoot, reason) {
+    commitBrowserEngineResolution(projectRoot, { engine: "legacy", source: "probe", reason });
+    return "legacy";
+}
 function isWarmUpDisabled() {
     const value = process.env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
     return value === "0" || value === "false" || value === "off";
 }
 /**
- * Auto-initialize the managed gsd-browser engine only when explicitly selected
- * for a web app. Best-effort and non-blocking: warm-up runs in the background
- * and only surfaces a warning if it fails.
+ * Auto-initialize the managed gsd-browser engine when it was selected via the
+ * explicit GSD_BROWSER_ENGINE override, which registers without the
+ * daemon-connect gate. Best-effort and non-blocking: warm-up runs in the
+ * background and only surfaces a warning if it fails. Probe-resolved sessions
+ * already connected (or fell back) during registration, so they are excluded
+ * to avoid re-warming and double-notifying.
  */
 function maybeWarmUpManagedEngine(pi, ctx) {
     if (isWarmUpDisabled())
         return;
-    if (resolveBrowserEngineMode() !== "gsd-browser")
-        return;
     const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    if (resolution.engine !== "gsd-browser" || resolution.source !== "env")
+        return;
     if (!detectWebApp(projectRoot))
         return;
     void warmUpManagedGsdBrowser(ctx).then((result) => {
-        if (!result.ok && ctx.hasUI) {
+        if (!ctx.hasUI)
+            return;
+        if (!result.ok) {
             ctx.ui.notify(`gsd-browser auto-init failed: ${result.error}. Browser UAT tools will retry on first use; run /gsd doctor if this persists.`, "warning");
         }
+        else if (result.coverageWarning) {
+            ctx.ui.notify(result.coverageWarning, "warning");
+        }
     });
 }
 async function closeActiveBrowserEngines() {
@@ -198,14 +255,14 @@ async function closeActiveBrowserEngines() {
 export default function (pi) {
     pi.on("session_start", async (_event, ctx) => {
         if (ctx.hasUI) {
-            void registerBrowserTools(pi)
+            void registerBrowserTools(pi, ctx)
                 .then(() => maybeWarmUpManagedEngine(pi, ctx))
                 .catch((error) => {
                 ctx.ui.notify(`browser-tools failed to load: ${error instanceof Error ? error.message : String(error)}`, "warning");
             });
             return;
         }
-        await registerBrowserTools(pi);
+        await registerBrowserTools(pi, ctx);
         maybeWarmUpManagedEngine(pi, ctx);
     });
     pi.on("session_shutdown", async () => {

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

@@ -37,6 +37,15 @@ export const CLAUDE_CODE_MODELS = [
         contextWindow: 1_000_000,
         maxTokens: 128_000,
     },
+    {
+        id: "claude-fable-5",
+        name: "Claude Fable 5 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 1_000_000,
+        maxTokens: 128_000,
+    },
     {
         id: "claude-sonnet-4-6",
         name: "Claude Sonnet 4.6 (via Claude Code)",

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

@@ -24,6 +24,8 @@ import { markToolStart, markToolEnd } from "../gsd/auto.js";
 import { markInteractiveElicitationStart, markInteractiveElicitationEnd, } from "../gsd/auto-tool-tracking.js";
 import { discoverBrowserMcpServerName, discoverMcpServers, discoverMcpServerNames, discoverUserMcpServerNames, discoverWorkflowMcpServerName, computeMcpDisallowedTools, } from "../gsd/mcp-filter.js";
 import { RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES, resolveToolPresentationPlan } from "../gsd/tool-presentation-plan.js";
+import { getToolSurfaceReadinessError } from "../gsd/tool-surface-readiness.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound } from "../shared/tui.js";
 export { buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, mergePendingToolCalls, } from "./turn-assembler.js";
 export function serverToolUseToToolCallLike(block) {
@@ -1242,6 +1244,8 @@ function modelSupportsAdaptiveThinking(modelId) {
         || modelId.includes("opus-4.7")
         || modelId.includes("opus-4-8")
         || modelId.includes("opus-4.8")
+        || modelId.includes("fable-5")
+        || modelId.includes("fable.5")
         || modelId.includes("sonnet-4-6")
         || modelId.includes("sonnet-4.6")
         || modelId.includes("sonnet-4-7")
@@ -1263,7 +1267,9 @@ function mapThinkingLevelToAnthropicEffort(level, modelId) {
             if (modelId.includes("opus-4-7")
                 || modelId.includes("opus-4.7")
                 || modelId.includes("opus-4-8")
-                || modelId.includes("opus-4.8"))
+                || modelId.includes("opus-4.8")
+                || modelId.includes("fable-5")
+                || modelId.includes("fable.5"))
                 return "xhigh";
             if (modelId.includes("opus-4-6") || modelId.includes("opus-4.6"))
                 return "max";
@@ -1285,7 +1291,7 @@ function browserMcpServerNameFromAllowedTools(allowedTools) {
         const parsed = parseAllowedMcpToolName(toolName);
         if (!parsed)
             continue;
-        if (parsed.server === "gsd-browser" || parsed.tool.startsWith("browser_")) {
+        if (parsed.server === "gsd-browser" || hasBrowserContractPrefix(parsed.tool)) {
             return parsed.server;
         }
     }
@@ -1299,7 +1305,7 @@ function workflowMcpServerNameFromAllowedTools(allowedTools) {
         if (typeof toolName !== "string")
             continue;
         const parsed = parseAllowedMcpToolName(toolName);
-        if (!parsed || parsed.server === browserServerName || parsed.tool.startsWith("browser_"))
+        if (!parsed || parsed.server === browserServerName || hasBrowserContractPrefix(parsed.tool))
             continue;
         return parsed.server;
     }
@@ -1564,7 +1570,9 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
             || modelId.includes("opus-4-7")
             || modelId.includes("opus-4.7")
             || modelId.includes("opus-4-8")
-            || modelId.includes("opus-4.8")) ? ["context-1m-2025-08-07"] : [],
+            || modelId.includes("opus-4.8")
+            || modelId.includes("fable-5")
+            || modelId.includes("fable.5")) ? ["context-1m-2025-08-07"] : [],
         ...(thinkingConfig ?? {}),
         ...(effort ? { effort } : {}),
         ...sdkExtraOptions,
@@ -1629,8 +1637,9 @@ async function pumpSdkMessages(model, context, options, stream) {
                 }
                 : {}),
         });
+        const workflowMcpServerName = workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools);
         const prompt = buildPromptFromContext(context, {
-            workflowMcpServerName: workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+            workflowMcpServerName,
             browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
         });
         const queryPrompt = buildSdkQueryPrompt(context, prompt);
@@ -1668,7 +1677,30 @@ async function pumpSdkMessages(model, context, options, stream) {
             switch (msg.type) {
                 // -- Init --
                 case "system": {
-                    // Nothing to emit — the stream is already started.
+                    // Tool Surface Readiness gate: the init message is the first (and
+                    // only) point where the session reports its live tool surface and
+                    // MCP server statuses. If the workflow server failed or has not
+                    // registered this Unit's required tools, abort before the first
+                    // model turn with a transient, recovery-classifiable error
+                    // (tool-unavailable → retry) instead of letting the model hit
+                    // "No such tool available" mid-Unit and improvise around it.
+                    const init = msg;
+                    if (init.subtype === "init") {
+                        const readinessError = getToolSurfaceReadinessError({
+                            unitType: gsdPhase,
+                            workflowServerName: workflowMcpServerName,
+                            observation: { tools: init.tools ?? [], mcpServers: init.mcp_servers ?? [] },
+                        });
+                        if (readinessError) {
+                            controller.abort();
+                            stream.push({
+                                type: "error",
+                                reason: "error",
+                                error: makeErrorMessage(modelId, readinessError),
+                            });
+                            return;
+                        }
+                    }
                     break;
                 }
                 // -- Streaming partial messages --

package/dist/resources/extensions/gsd/auto/custom-verify-retry-store.js

@@ -4,6 +4,12 @@ import { readFileSync, mkdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteSync } from "../atomic-write.js";
 import { gsdRoot } from "../paths.js";
+function ensureExhaustedVerificationUnits(s) {
+    if (!s.exhaustedVerificationUnits) {
+        s.exhaustedVerificationUnits = new Set();
+    }
+    return s.exhaustedVerificationUnits;
+}
 export function customVerifyRetryStateDir(s) {
     return s.activeRunDir ? join(s.activeRunDir, "runtime") : join(gsdRoot(s.basePath), "runtime");
 }
@@ -11,7 +17,8 @@ export function customVerifyRetryStatePath(s) {
     return join(customVerifyRetryStateDir(s), "custom-verify-retries.json");
 }
 export function hydrateCustomVerifyRetryCounts(s, deps) {
-    if (s.verificationRetryCount.size > 0) {
+    const exhaustedUnits = ensureExhaustedVerificationUnits(s);
+    if (s.verificationRetryCount.size > 0 || exhaustedUnits.size > 0) {
         return s.verificationRetryCount;
     }
     try {
@@ -24,6 +31,12 @@ export function hydrateCustomVerifyRetryCounts(s, deps) {
                 s.verificationRetryCount.set(key, Math.floor(value));
             }
         }
+        const exhausted = raw && typeof raw === "object" && Array.isArray(raw.exhausted) ? raw.exhausted : [];
+        for (const key of exhausted) {
+            if (typeof key === "string" && key.length > 0) {
+                exhaustedUnits.add(key);
+            }
+        }
     }
     catch (err) {
         deps.logFailure(err);
@@ -32,15 +45,17 @@ export function hydrateCustomVerifyRetryCounts(s, deps) {
 }
 export function saveCustomVerifyRetryCounts(s, deps) {
     const retryCounts = s.verificationRetryCount;
+    const exhaustedUnits = ensureExhaustedVerificationUnits(s);
     const filePath = customVerifyRetryStatePath(s);
     try {
-        if (!retryCounts || retryCounts.size === 0) {
+        if ((!retryCounts || retryCounts.size === 0) && (!exhaustedUnits || exhaustedUnits.size === 0)) {
             unlinkSync(filePath);
             return;
         }
         mkdirSync(customVerifyRetryStateDir(s), { recursive: true });
         atomicWriteSync(filePath, JSON.stringify({
             counts: Object.fromEntries(retryCounts),
+            exhausted: [...exhaustedUnits],
             updatedAt: new Date().toISOString(),
         }) + "\n");
     }

package/dist/resources/extensions/gsd/auto/detect-stuck.js

@@ -3,6 +3,7 @@
  *
  * Leaf node in the import DAG.
  */
+import { parseDispatchKey } from "./dispatch-key.js";
 import { summarizeLogs } from "../workflow-logger.js";
 import { getLatestForUnit } from "../db/unit-dispatches.js";
 /**
@@ -11,6 +12,18 @@ import { getLatestForUnit } from "../db/unit-dispatches.js";
  * and similar Node.js filesystem error messages.
  */
 const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
+function rowInsideRetryBudget(row) {
+    if (!row)
+        return false;
+    if (row.attempt_n >= row.max_attempts)
+        return false;
+    if (!row.next_run_at)
+        return false;
+    const nextRun = Date.parse(row.next_run_at);
+    if (!Number.isFinite(nextRun))
+        return false;
+    return nextRun > Date.now();
+}
 /**
  * Phase B / codex review MEDIUM B3 — retry coupling.
  *
@@ -20,23 +33,26 @@ const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
  * waiting on its own backoff. Suppress the stuck verdict in that case so
  * the retry budget can fully drain before we declare stuck.
  *
+ * Window keys are compound (`unitType:unitId`, legacy `unitType/unitId`)
+ * while the production dispatch ledger keys rows by the bare unit id with
+ * the unit type in its own column. Look the bare unit id up first (with a
+ * unit_type match — the production shape), then fall back to the full
+ * compound key (test fixtures / legacy rows).
+ *
  * Returns true if the dispatch ledger says we should suppress the stuck
  * signal; false (no suppression) when the ledger is unavailable or has
  * no opinion.
  */
 function retryBudgetSuppresses(unitKey) {
     try {
-        const latest = getLatestForUnit(unitKey);
-        if (!latest)
-            return false;
-        if (latest.attempt_n >= latest.max_attempts)
-            return false;
-        if (!latest.next_run_at)
-            return false;
-        const nextRun = Date.parse(latest.next_run_at);
-        if (!Number.isFinite(nextRun))
-            return false;
-        return nextRun > Date.now();
+        const parsed = parseDispatchKey(unitKey);
+        if (parsed) {
+            const bare = getLatestForUnit(parsed.unitId);
+            if (bare && bare.unit_type === parsed.unitType && rowInsideRetryBudget(bare)) {
+                return true;
+            }
+        }
+        return rowInsideRetryBudget(getLatestForUnit(unitKey));
     }
     catch {
         return false;
@@ -66,6 +82,10 @@ export function detectStuck(window, _retryContext) {
     const suffix = loggerSummary ? ` — ${loggerSummary}` : "";
     const last = window[window.length - 1];
     const prev = window[window.length - 2];
+    // Rules 2 and 2b share one retry-budget verdict for `last.key` — compute it
+    // at most once per invocation (it hits the dispatch ledger).
+    let suppressionVerdict;
+    const suppressed = () => (suppressionVerdict ??= retryBudgetSuppresses(last.key));
     // Rule 1: Same error repeated consecutively
     if (last.error && prev.error && last.error === prev.error) {
         return {
@@ -77,7 +97,7 @@ export function detectStuck(window, _retryContext) {
     // says we're inside the retry-backoff window (codex MEDIUM B3).
     if (window.length >= 3) {
         const lastThree = window.slice(-3);
-        if (lastThree.every((u) => u.key === last.key) && !retryBudgetSuppresses(last.key)) {
+        if (lastThree.every((u) => u.key === last.key) && !suppressed()) {
             return {
                 stuck: true,
                 reason: `${last.key} derived 3 consecutive times without progress${suffix}`,
@@ -87,7 +107,7 @@ export function detectStuck(window, _retryContext) {
     // Rule 2b: Same unit key 3+ times anywhere in the active window — same
     // retry-budget suppression as Rule 2.
     const countInWindow = window.filter((entry) => entry.key === last.key).length;
-    if (countInWindow >= 3 && !retryBudgetSuppresses(last.key)) {
+    if (countInWindow >= 3 && !suppressed()) {
         return {
             stuck: true,
             reason: `${last.key} derived ${countInWindow} times in last ${window.length} attempts without progress${suffix}`,

package/dist/resources/extensions/gsd/auto/dispatch-history.js

@@ -0,0 +1,105 @@
+// Project/App: gsd-pi
+// File Purpose: Dispatch History module — the single home for the auto
+// orchestrator's dispatch-decision window, cross-session rehydration, and
+// stuck detection (#482 / #442 deepening).
+/**
+ * auto/dispatch-history.ts — Dispatch History module.
+ *
+ * Owns the sliding window of recent dispatch decisions that the Auto
+ * Orchestration module consults for idempotency and stuck-loop detection.
+ *
+ * Before this module existed the orchestrator kept a private in-memory
+ * `dispatchKeyWindow: string[]` that was reset to `[]` in start()/resume().
+ * Because a fresh orchestrator is constructed per session, the window never
+ * saw dispatches from a previous session — a unit could be re-dispatched
+ * across session restarts indefinitely (issue #482: 146 re-dispatches of the
+ * same unit). This module rehydrates the window from the DB dispatch ledger
+ * (`unit_dispatches`, via getRecentUnitKeysForProjectRoot) so stuck detection
+ * survives process restarts, and it delegates the verdict to the full
+ * detect-stuck rule set (repeat-error / consecutive / oscillation / ENOENT,
+ * with retry-budget suppression) instead of the bare saturation count.
+ *
+ * Key format: the canonical dispatch key is `${unitType}:${unitId}`
+ * (e.g. "execute-task:M001/S01/T01"). The legacy auto/phases.ts path and the
+ * DB rehydration helper use `${unitType}/${unitId}`; normalizeDispatchKey
+ * converts those on rehydrate so one format lives in the window. The key
+ * grammar itself lives in auto/dispatch-key.ts and is re-exported here for
+ * import stability.
+ */
+import { buildDispatchKey, normalizeDispatchKey } from "./dispatch-key.js";
+import { detectStuck } from "./detect-stuck.js";
+import { getLatestForUnit, getRecentUnitKeysForProjectRoot, } from "../db/unit-dispatches.js";
+import { debugLog } from "../debug-logger.js";
+export { buildDispatchKey, normalizeDispatchKey, parseDispatchKey } from "./dispatch-key.js";
+/**
+ * Size of the dispatch-decision ring buffer. Mirrors the legacy
+ * `STUCK_WINDOW_SIZE` in auto/phases.ts so behaviour is preserved across the
+ * cutover (issue #5791).
+ */
+export const STUCK_WINDOW_SIZE = 6;
+function lookupLatestLedgerError(unitType, unitId) {
+    try {
+        const row = getLatestForUnit(unitId);
+        // The ledger keys rows by bare unit id; require a unit_type match so
+        // another unit type's error on the same id is never attached (it would
+        // trip the repeat-error rule spuriously).
+        if (!row || row.unit_type !== unitType)
+            return undefined;
+        return row.error_summary ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createDispatchHistory(options) {
+    const windowSize = options.windowSize ?? STUCK_WINDOW_SIZE;
+    let window = [];
+    return {
+        recordDispatch(unitType, unitId) {
+            const key = buildDispatchKey(unitType, unitId);
+            // Ledger errors only feed the repeat-error/ENOENT rules, which need a
+            // prior occurrence of the same unit in the window — first-dispatch
+            // advances (the common case) pay zero DB cost.
+            const error = window.some((entry) => entry.key === key)
+                ? lookupLatestLedgerError(unitType, unitId)
+                : undefined;
+            window.push({ key, error });
+            while (window.length > windowSize)
+                window.shift();
+            return key;
+        },
+        getRecentWindow() {
+            return window;
+        },
+        countMatching(key) {
+            return window.filter((entry) => entry.key === key).length;
+        },
+        detectStuck() {
+            return detectStuck(window);
+        },
+        rehydrate() {
+            const scopeId = options.resolveScopeId();
+            if (!scopeId)
+                return 0;
+            try {
+                const persisted = getRecentUnitKeysForProjectRoot(scopeId, windowSize);
+                if (persisted.length === 0)
+                    return 0;
+                window = persisted.map(({ key }) => ({ key: normalizeDispatchKey(key) }));
+                while (window.length > windowSize)
+                    window.shift();
+                return window.length;
+            }
+            catch (err) {
+                debugLog("dispatchHistory", {
+                    phase: "rehydrate-failed",
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return 0;
+            }
+        },
+        clearOnRecovery() {
+            window = [];
+        },
+    };
+}

package/dist/resources/extensions/gsd/auto/dispatch-key.js

@@ -0,0 +1,37 @@
+// Project/App: gsd-pi
+// File Purpose: Dispatch-key grammar — the single home for building, parsing,
+// and normalizing the auto orchestrator's dispatch keys.
+/**
+ * auto/dispatch-key.ts — Dispatch-key grammar.
+ *
+ * Canonical key: `${unitType}:${unitId}` (e.g. "execute-task:M001/S01/T01").
+ * Legacy key: `${unitType}/${unitId}` (auto/phases.ts, DB rehydration). Unit
+ * ids themselves contain "/" (M001/S01/T01) — the first segment is the unit
+ * type.
+ *
+ * Leaf node in the import DAG: both dispatch-history.ts and detect-stuck.ts
+ * consume this grammar, so it lives below them.
+ */
+/** Build the canonical dispatch key for a unit. One format, one home. */
+export function buildDispatchKey(unitType, unitId) {
+    return `${unitType}:${unitId}`;
+}
+/** Split a canonical or legacy dispatch key into its unit type and id. */
+export function parseDispatchKey(key) {
+    const colon = key.indexOf(":");
+    if (colon > 0) {
+        return { unitType: key.slice(0, colon), unitId: key.slice(colon + 1) };
+    }
+    const slash = key.indexOf("/");
+    if (slash > 0) {
+        return { unitType: key.slice(0, slash), unitId: key.slice(slash + 1) };
+    }
+    return null;
+}
+/** Normalize a legacy `${unitType}/${unitId}` key to the canonical format. */
+export function normalizeDispatchKey(key) {
+    if (key.includes(":"))
+        return key;
+    const parsed = parseDispatchKey(key);
+    return parsed ? buildDispatchKey(parsed.unitType, parsed.unitId) : key;
+}

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

@@ -13,7 +13,8 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { MAX_LOOP_ITERATIONS, } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
-import { runGuards, runFinalize, STUCK_WINDOW_SIZE } from "./phases.js";
+import { runGuards, runFinalize } from "./phases.js";
+import { STUCK_WINDOW_SIZE } from "./dispatch-history.js";
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
 import { ModelPolicyDispatchBlockedError } from "../auto-model-selection.js";
@@ -278,6 +279,8 @@ export async function autoLoop(ctx, pi, s, deps, options) {
     const unitDispatchDeps = createExecutionGraphUnitDispatchDeps();
     // Load persisted stuck state so counters survive session restarts (#3704)
     const persisted = loadStuckState(s);
+    // Load persisted verification retry state so the exhausted-unit guard fires on restart (#651)
+    hydrateCustomVerifyRetryCounts(s, { logFailure: logCustomVerifyRetryLoadFailure });
     const loopState = {
         recentUnits: persisted.recentUnits,
         stuckRecoveryAttempts: persisted.stuckRecoveryAttempts,