@opengsd/gsd-pi 1.2.0-dev.84c56d87 → 1.2.0-dev.9ad8ae33

package/dist/resources/extensions/async-jobs/job-manager.js

@@ -53,6 +53,15 @@ export class AsyncJobManager {
         };
         job.promise = runFn(abortController.signal)
             .then((resultText) => {
+            if (job.status === "cancelled") {
+                // Already cancelled by cancel(). The runFn resolves (not rejects) even
+                // when aborted — async_bash's safeResolve returns "Command aborted"
+                // rather than throwing — so without this guard the status would be
+                // clobbered back to "completed", mislabeling a user-cancelled job.
+                // Mirrors the symmetric guard in the .catch branch below.
+                this.scheduleEviction(id);
+                return;
+            }
             job.status = "completed";
             job.resultText = resultText;
             this.scheduleEviction(id);
@@ -143,8 +152,10 @@ export class AsyncJobManager {
         const cb = this.onJobComplete;
         job.deliveryTimer = setTimeout(() => {
             job.deliveryTimer = undefined;
-            if (!job.awaited)
+            if (!job.awaited) {
+                job.delivered = true;
                 cb(job);
+            }
         }, 0);
         // Allow process to exit even if timer is pending
         if (typeof job.deliveryTimer === "object" && "unref" in job.deliveryTimer) {

package/dist/resources/extensions/bg-shell/bg-shell-command.js

@@ -3,7 +3,7 @@
  */
 import { Key } from "@gsd/pi-tui";
 import { shortcutDesc } from "../shared/terminal.js";
-import { processes, killProcess, getGroupStatus, cleanupAll, } from "./process-manager.js";
+import { processes, terminateProcess, getGroupStatus, cleanupAll, } from "./process-manager.js";
 import { generateDigest, getOutput, formatDigestText, } from "./output-formatter.js";
 import { formatUptime } from "./utilities.js";
 import { BgManagerOverlay } from "./overlay.js";
@@ -119,11 +119,11 @@ export function registerBgShellCommand(pi, state) {
                     ctx.ui.notify(`No process with id '${id}'`, "error");
                     return;
                 }
-                killProcess(id, "SIGTERM");
-                await new Promise(r => setTimeout(r, 300));
-                if (bg.alive) {
-                    killProcess(id, "SIGKILL");
-                    await new Promise(r => setTimeout(r, 200));
+                // Graceful ladder (SIGTERM → grace → SIGKILL) via killProcessTree.
+                terminateProcess(id);
+                const deadline = Date.now() + 6_000; // grace (5s) + slack
+                while (bg.alive && Date.now() < deadline) {
+                    await new Promise(r => setTimeout(r, 100));
                 }
                 if (!bg.alive)
                     processes.delete(id);

package/dist/resources/extensions/bg-shell/bg-shell-tool.js

@@ -4,7 +4,7 @@
 import { StringEnum, Type } from "@gsd/pi-ai";
 import { Text } from "@gsd/pi-tui";
 import { DEFAULT_READY_TIMEOUT } from "./types.js";
-import { processes, startProcess, killProcess, restartProcess, getInfo, getGroupStatus, persistManifest, } from "./process-manager.js";
+import { processes, startProcess, killProcess, terminateProcess, restartProcess, getInfo, getGroupStatus, persistManifest, } from "./process-manager.js";
 import { generateDigest, getHighlights, getOutput, formatDigestText, } from "./output-formatter.js";
 import { waitForReady } from "./readiness-detector.js";
 import { queryShellEnv, sendAndWait, runOnSession } from "./interaction.js";
@@ -22,7 +22,8 @@ export function registerBgShellTool(pi, state) {
             "signal (send OS signal), list (all processes with status), kill (terminate), restart (kill + relaunch), " +
             "group_status (health of a process group), highlights (significant output lines only).",
         promptGuidelines: [
-            "Use bg_shell to start long-running processes (servers, watchers, builds) that should not block the agent.",
+            "Use bg_shell for processes that STAY ALIVE and you interact with over time: servers, watchers, daemons, REPLs. For a command that runs to completion and exits (terraform apply, migrations, builds, tests, installs), use async_bash or sync bash instead — NOT bg_shell.",
+            "'wait_for_ready' is for long-lived processes that signal readiness (open a port / print a pattern). Never use it on a run-to-completion command: that command exits instead of becoming ready, so a clean exit-0 is reported as 'not ready'. If you see that, switch to async_bash.",
             "After starting a server, use 'wait_for_ready' to efficiently block until it's listening — avoids polling loops entirely.",
             "Use 'digest' instead of 'output' when you just need status — it returns a structured ~30-token summary instead of ~2000 tokens of raw output.",
             "Use 'highlights' to see only significant output (errors, URLs, results) — typically 5-15 lines instead of hundreds.",
@@ -511,11 +512,13 @@ export function registerBgShellTool(pi, state) {
                             isError: true, details: undefined,
                         };
                     }
-                    const killed = killProcess(params.id, "SIGTERM");
-                    await new Promise(r => setTimeout(r, 300));
-                    if (bg.alive) {
-                        killProcess(params.id, "SIGKILL");
-                        await new Promise(r => setTimeout(r, 200));
+                    // Graceful termination: SIGTERM → grace → SIGKILL via the shared
+                    // killProcessTree ladder (same path bash/async_bash/exec use), so a
+                    // stateful process gets a clean-shutdown window instead of a bare kill.
+                    const killed = terminateProcess(params.id);
+                    const deadline = Date.now() + 6_000; // grace (5s) + slack
+                    while (bg.alive && Date.now() < deadline) {
+                        await new Promise(r => setTimeout(r, 100));
                     }
                     const info = getInfo(bg);
                     if (!bg.alive)

package/dist/resources/extensions/bg-shell/overlay.js

@@ -4,7 +4,7 @@
 import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { ERROR_PATTERNS, WARNING_PATTERNS } from "./types.js";
 import { formatUptime, formatTimeAgo } from "./utilities.js";
-import { processes, killProcess, cleanupAll, restartProcess, } from "./process-manager.js";
+import { processes, terminateProcess, cleanupAll, restartProcess, } from "./process-manager.js";
 export class BgManagerOverlay {
     tui;
     theme;
@@ -110,17 +110,20 @@ export class BgManagerOverlay {
             }
             return;
         }
-        // x or d = kill selected
+        // x or d = kill selected (graceful ladder via killProcessTree).
+        // Use a short interactive grace: the user explicitly asked to kill, so give the
+        // process a brief clean-shutdown window then force, and re-render AFTER that grace
+        // plus slack so the row reflects the SIGKILL escalation (a 300ms re-render against
+        // the default 5s grace would show the process still alive).
         if (data === "x" || data === "d") {
             const proc = procs[this.selected];
             if (proc && proc.alive) {
-                killProcess(proc.id, "SIGTERM");
+                const OVERLAY_KILL_GRACE_MS = 500;
+                terminateProcess(proc.id, OVERLAY_KILL_GRACE_MS);
                 setTimeout(() => {
-                    if (proc.alive)
-                        killProcess(proc.id, "SIGKILL");
                     this.invalidate();
                     this.tui.requestRender();
-                }, 300);
+                }, OVERLAY_KILL_GRACE_MS + 400);
             }
             return;
         }

package/dist/resources/extensions/bg-shell/process-manager.js

@@ -6,7 +6,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { getShellConfig, sanitizeCommand } from "@gsd/pi-coding-agent";
+import { getShellConfig, sanitizeCommand, killProcessTree } from "@gsd/pi-coding-agent";
 import { rewriteCommandWithRtk } from "../shared/rtk.js";
 import { MAX_BUFFER_LINES, MAX_EVENTS, DEAD_PROCESS_TTL, } from "./types.js";
 import { restoreWindowsVTInput, formatUptime } from "./utilities.js";
@@ -221,6 +221,38 @@ export function startProcess(opts) {
     return bg;
 }
 // ── Process Kill ───────────────────────────────────────────────────────────
+/**
+ * Gracefully terminate a process and its tree using the shared killProcessTree
+ * ladder (SIGTERM → grace window → SIGKILL), the same path bash/async_bash/exec
+ * use. This is the "I want it dead, cleanly" intent — use it for the `kill`
+ * action, `restart`, and session cleanup. For sending a SPECIFIC signal the
+ * agent chose on purpose (SIGINT, SIGHUP, …) use killProcess(), which delivers
+ * that exact signal once and does not escalate.
+ *
+ * `graceMs` overrides the SIGTERM→SIGKILL window (default: killProcessTree's 5s);
+ * session cleanup passes a shorter grace so it stays snappy between units.
+ *
+ * Returns false only when the process is unknown/already dead; the actual
+ * SIGKILL escalation fires asynchronously after the grace window, so callers
+ * should not assume the process is dead the instant this returns.
+ */
+export function terminateProcess(id, graceMs) {
+    const bg = processes.get(id);
+    if (!bg)
+        return false;
+    if (!bg.alive)
+        return true;
+    if (!bg.proc.pid) {
+        // No pid to target a tree; fall back to a direct graceful signal.
+        try {
+            bg.proc.kill("SIGTERM");
+        }
+        catch { /* already gone */ }
+        return true;
+    }
+    killProcessTree(bg.proc.pid, graceMs !== undefined ? { graceMs } : undefined);
+    return true;
+}
 export function killProcess(id, sig = "SIGTERM") {
     const bg = processes.get(id);
     if (!bg)
@@ -272,13 +304,14 @@ export async function restartProcess(id) {
         return null;
     const config = old.startConfig;
     const restartCount = old.restartCount + 1;
-    // Kill old process
+    // Kill old process via the graceful ladder, then wait for it to actually die.
+    // killProcessTree escalates SIGTERM → grace → SIGKILL asynchronously, so poll
+    // for death rather than assuming a fixed sleep is enough.
     if (old.alive) {
-        killProcess(id, "SIGTERM");
-        await new Promise(r => setTimeout(r, 300));
-        if (old.alive) {
-            killProcess(id, "SIGKILL");
-            await new Promise(r => setTimeout(r, 200));
+        terminateProcess(id);
+        const deadline = Date.now() + 6_000; // grace (5s) + slack
+        while (old.alive && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 100));
         }
     }
     processes.delete(id);
@@ -328,24 +361,16 @@ export function pruneDeadProcesses() {
     }
 }
 export function cleanupAll() {
+    // Deliberately a bare, synchronous SIGKILL — not the graceful ladder. This runs
+    // from process 'exit'/signal handlers where timers no longer fire, so a deferred
+    // SIGKILL would never be delivered and children would be orphaned when we vanish.
+    // Immediate force-kill is the correct teardown semantics here.
     for (const [id, bg] of processes) {
         if (bg.alive)
             killProcess(id, "SIGKILL");
     }
     processes.clear();
 }
-/**
- * Kill all alive, non-persistent bg processes.
- * Called between auto-mode units to prevent orphaned servers from
- * keeping ports bound across task boundaries (#1209).
- */
-export function killSessionProcesses() {
-    for (const [id, bg] of processes) {
-        if (bg.alive && !bg.persistAcrossSessions) {
-            killProcess(id, "SIGTERM");
-        }
-    }
-}
 async function waitForProcessExit(bg, timeoutMs) {
     if (!bg.alive)
         return true;
@@ -359,20 +384,24 @@ async function waitForProcessExit(bg, timeoutMs) {
     });
     return !bg.alive;
 }
+/**
+ * Terminate the alive, non-persistent processes owned by a session, gracefully.
+ * Routes through the shared killProcessTree ladder (SIGTERM → grace → SIGKILL)
+ * via terminateProcess, with a short grace (default 300ms) so cleanup between
+ * units stays snappy; killProcessTree handles the SIGKILL escalation itself, so
+ * there is no separate force-kill pass here.
+ */
 export async function cleanupSessionProcesses(sessionFile, options) {
     const graceMs = Math.max(0, options?.graceMs ?? 300);
     const matches = Array.from(processes.values()).filter((bg) => bg.alive && !bg.persistAcrossSessions && bg.ownerSessionFile === sessionFile);
     if (matches.length === 0)
         return [];
     for (const bg of matches) {
-        killProcess(bg.id, "SIGTERM");
+        terminateProcess(bg.id, graceMs);
     }
     if (graceMs > 0) {
-        await Promise.all(matches.map((bg) => waitForProcessExit(bg, graceMs)));
-    }
-    for (const bg of matches) {
-        if (bg.alive)
-            killProcess(bg.id, "SIGKILL");
+        // Wait past the grace so the SIGKILL escalation has fired and exits are observed.
+        await Promise.all(matches.map((bg) => waitForProcessExit(bg, graceMs + 200)));
     }
     return matches.map((bg) => bg.id);
 }

package/dist/resources/extensions/bg-shell/readiness-detector.js

@@ -72,6 +72,17 @@ export async function waitForReady(bg, timeout, signal) {
             return { ready: false, detail: "Cancelled" };
         }
         if (!bg.alive) {
+            // A clean exit-0 means the command ran to completion — it was a batch
+            // command (e.g. terraform apply, a migration, a build), not a long-lived
+            // server. That is success, not a readiness failure; say so plainly and
+            // point at the right tool so the agent stops using wait_for_ready here.
+            if (bg.exitCode === 0) {
+                return {
+                    ready: false,
+                    detail: "Process completed (exit 0) before signaling readiness — it ran to completion rather than staying alive. " +
+                        "wait_for_ready is for long-lived servers/watchers; for a run-to-completion command use async_bash (or bg_shell 'run').",
+                };
+            }
             const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-5).map(l => l.line);
             const stderrContext = stderrLines.length > 0 ? `\nstderr:\n${stderrLines.join("\n").slice(0, 500)}` : "";
             return {

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,