@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

package/dist/resources/extensions/claude-code-cli/turn-assembler.js

@@ -153,6 +153,38 @@ export function attachExternalResultsToToolBlocks(toolBlocks, toolResultsById) {
         block.externalResult = externalResult;
     }
 }
+function textFromExternalResult(result) {
+    return (result?.content ?? [])
+        .map((block) => typeof block.text === "string" ? block.text : "")
+        .join("\n");
+}
+function isEmptyToolArguments(value) {
+    return !!value
+        && typeof value === "object"
+        && !Array.isArray(value)
+        && Object.keys(value).length === 0;
+}
+function sameToolSurface(a, b) {
+    return a.name === b.name
+        && a.mcpServer === b.mcpServer;
+}
+export function shouldSuppressDuplicateToolUnavailableBlock(block, allBlocks) {
+    if (block.type !== "toolCall")
+        return false;
+    const externalResult = block.externalResult;
+    if (!externalResult?.isError)
+        return false;
+    if (!isEmptyToolArguments(block.arguments))
+        return false;
+    if (!/No such tool available:/i.test(textFromExternalResult(externalResult)))
+        return false;
+    return allBlocks.some((candidate) => {
+        if (candidate.type !== "toolCall" || candidate.id === block.id)
+            return false;
+        const candidateResult = candidate.externalResult;
+        return candidateResult?.isError === false && sameToolSurface(block, candidate);
+    });
+}
 /**
  * Build the final assistant content that Agent Core consumes in
  * `externalToolExecution` mode. This preserves tool-call blocks, attaches any
@@ -165,7 +197,7 @@ export function buildFinalAssistantContent(params) {
         mergePendingToolCalls(mergedToolBlocks, params.pendingContent);
     }
     attachExternalResultsToToolBlocks(mergedToolBlocks, params.toolResultsById);
-    const finalContent = [...mergedToolBlocks];
+    const finalContent = mergedToolBlocks.filter((block) => !shouldSuppressDuplicateToolUnavailableBlock(block, mergedToolBlocks));
     if (params.pendingContent && params.pendingContent.length > 0) {
         for (const block of params.pendingContent) {
             if (block.type === "text" || block.type === "thinking") {

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

@@ -0,0 +1,215 @@
+// Project/App: gsd-pi
+// File Purpose: Auto-loop closeout, milestone report, and merge helpers.
+import { importExtensionModule } from "@gsd/pi-coding-agent";
+import { MergeConflictError } from "../git-service.js";
+import { findUnmergedCompletedMilestones } from "../unmerged-milestone-guard.js";
+import { getIsolationMode } from "../preferences.js";
+import { isDbAvailable, getMilestone } from "../gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
+import { isClosedStatus } from "../status-guards.js";
+import { logWarning, logError } from "../workflow-logger.js";
+import { debugLog } from "../debug-logger.js";
+import { _resolveReportBasePath } from "./phase-helpers.js";
+/**
+ * If a unit is in-flight, close it out, then stop auto-mode.
+ */
+export async function closeoutAndStop(ctx, pi, s, deps, reason) {
+    if (s.currentUnit) {
+        await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+        s.clearCurrentUnit();
+    }
+    await deps.stopAuto(ctx, pi, reason);
+}
+export async function stopOnPostflightRecoveryNeeded(ic, result, milestoneId) {
+    if (!result.needsManualRecovery)
+        return null;
+    const { ctx, pi, deps } = ic;
+    const reason = `Post-merge stash restore failed for milestone ${milestoneId}`;
+    ctx.ui.notify(`${reason}. Resolve the working tree before resuming auto-mode. ${result.message}`, "error");
+    await deps.stopAuto(ctx, pi, reason);
+    return { action: "break", reason: "postflight-stash-restore-failed" };
+}
+export async function restorePreflightStashOrStop(ic, preflight, milestoneId) {
+    if (!preflight.stashPushed)
+        return null;
+    const { s, deps } = ic;
+    const result = deps.postflightPopStash(s.originalBasePath || s.basePath, milestoneId, preflight.stashMarker, ic.ctx.ui.notify.bind(ic.ctx.ui));
+    return stopOnPostflightRecoveryNeeded(ic, result, milestoneId);
+}
+/**
+ * Run a milestone merge surrounded by preflight stash + always-on postflight
+ * pop. The previous code popped the stash only after a successful merge, which
+ * leaked `gsd-preflight-stash:M00x:*` entries whenever `mergeAndExit` threw —
+ * leaving the user's pre-merge working tree silently stashed away after a
+ * merge-conflict or other merge error. This helper restores the stash on
+ * every exit path, then surfaces the merge or stash failure (in priority
+ * order) as the loop's stop reason.
+ *
+ * Returns a `break` action when auto-mode must stop, or `null` when the merge
+ * succeeded and the stash (if any) was restored cleanly.
+ */
+export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, options = {}) {
+    const { ctx, pi, s, deps } = ic;
+    const preflight = deps.preflightCleanRoot(s.originalBasePath || s.basePath, milestoneId, ctx.ui.notify.bind(ctx.ui));
+    if (preflight.blocked) {
+        const reason = preflight.blockedReason === "unmerged-conflicts"
+            ? `Pre-merge unresolved Git conflicts block milestone ${milestoneId}`
+            : `Pre-merge dirty working tree overlaps milestone ${milestoneId}`;
+        await deps.stopAuto(ctx, pi, reason, {
+            preserveCompletedMilestoneBranch: true,
+            preserveCloseoutTranscript: options.preserveCloseoutTranscript,
+        });
+        return {
+            action: "break",
+            reason: preflight.blockedReason === "unmerged-conflicts"
+                ? "preflight-unmerged-conflicts"
+                : "preflight-dirty-overlap",
+        };
+    }
+    let mergeError = null;
+    const exitResult = deps.lifecycle.exitMilestone(milestoneId, { merge: true }, ctx.ui);
+    if (exitResult.ok) {
+        s.milestoneMergedInPhases = true;
+        try {
+            const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+            const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+            await rebuildMarkdownProjectionsFromDb(projectRoot);
+        }
+        catch (err) {
+            logWarning("engine", `markdown projection rebuild after milestone merge failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else {
+        mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+    }
+    // Always attempt to restore the stashed working tree, even on merge error.
+    // postflightPopStash itself does not throw; failures surface via the
+    // PostflightResult.needsManualRecovery flag.
+    let stashResult = null;
+    if (preflight.stashPushed) {
+        stashResult = deps.postflightPopStash(s.originalBasePath || s.basePath, milestoneId, preflight.stashMarker, ctx.ui.notify.bind(ctx.ui));
+    }
+    // Merge failure takes priority over stash recovery — the merge is the
+    // authoritative gate. If the stash also needed manual recovery, the user
+    // already saw the postflightPopStash notify above.
+    if (mergeError) {
+        if (mergeError instanceof MergeConflictError) {
+            // A merge conflict is a recoverable human checkpoint, not an
+            // infrastructure failure — the user resolves the conflict and runs
+            // `/gsd auto` to resume. Pause (don't stop): stopAuto tears down the
+            // session and, because `milestoneMergedInPhases` stays false here,
+            // re-runs the already-failed worktree merge in its cleanup step
+            // (#2645), then drops the user out of the interactive TUI onto a
+            // "stopped" surface.
+            const conflictReason = `Merge conflict on milestone ${milestoneId}: ${mergeError.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`;
+            ctx.ui.notify(conflictReason, "error");
+            await deps.pauseAuto(ctx, pi, {
+                message: conflictReason,
+                category: "unknown",
+            });
+            return { action: "break", reason: "merge-conflict" };
+        }
+        logError("engine", "Milestone merge failed with non-conflict error", {
+            milestone: milestoneId,
+            error: String(mergeError),
+        });
+        // Like a merge conflict, a non-conflict merge failure (index lock,
+        // network, permissions) is recoverable — the user fixes the cause and
+        // runs `/gsd auto` to resume. Pause (don't stop) so the session stays
+        // resumable and stopAuto's teardown does not re-run the failed merge.
+        const mergeFailReason = `Merge error on milestone ${milestoneId}: ${mergeError instanceof Error ? mergeError.message : String(mergeError)}. Resolve and run /gsd auto to resume.`;
+        ctx.ui.notify(mergeFailReason, "error");
+        await deps.pauseAuto(ctx, pi, {
+            message: mergeFailReason,
+            category: "unknown",
+        });
+        return { action: "break", reason: "merge-failed" };
+    }
+    if (stashResult) {
+        return stopOnPostflightRecoveryNeeded(ic, stashResult, milestoneId);
+    }
+    return null;
+}
+export async function _runMilestoneMergeOnceWithStashRestore(ic, milestoneId, options = {}) {
+    if (ic.s.milestoneMergedInPhases) {
+        debugLog("autoLoop", {
+            phase: "milestone-merge-skip",
+            reason: "already-merged-in-phases",
+            milestoneId,
+        });
+        return null;
+    }
+    return _runMilestoneMergeWithStashRestore(ic, milestoneId, options);
+}
+export async function shouldSkipTerminalMilestoneCloseout(s, state, mid) {
+    const closeoutMilestoneId = mid ?? s.currentMilestoneId ?? state.lastCompletedMilestone?.id;
+    if (s.completionStopInProgress) {
+        return { skip: true, milestoneId: closeoutMilestoneId };
+    }
+    if (!closeoutMilestoneId) {
+        return { skip: false };
+    }
+    if (isDbAvailable())
+        refreshWorkflowDatabaseFromDisk();
+    const closeoutBasePath = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+    let closeoutMergePending = false;
+    if (getIsolationMode(closeoutBasePath) !== "none") {
+        try {
+            const blockers = await findUnmergedCompletedMilestones(closeoutBasePath);
+            closeoutMergePending = blockers.some((blocker) => blocker.milestoneId === closeoutMilestoneId);
+        }
+        catch {
+            // Fail open: without git/DB inspection we cannot safely treat closeout as done.
+            closeoutMergePending = true;
+        }
+    }
+    const milestoneAlreadyClosedOut = isDbAvailable()
+        && isClosedStatus(getMilestone(closeoutMilestoneId)?.status ?? "")
+        && !closeoutMergePending;
+    if (milestoneAlreadyClosedOut) {
+        return { skip: true, milestoneId: closeoutMilestoneId };
+    }
+    return { skip: false, milestoneId: closeoutMilestoneId };
+}
+/**
+ * Generate and write an HTML milestone report snapshot.
+ */
+export async function generateMilestoneReport(s, ctx, milestoneId) {
+    const { loadVisualizerData } = await importExtensionModule(import.meta.url, "../visualizer-data.js");
+    const { generateHtmlReport } = await importExtensionModule(import.meta.url, "../export-html.js");
+    const { writeReportSnapshot } = await importExtensionModule(import.meta.url, "../reports.js");
+    const { basename } = await import("node:path");
+    const reportBasePath = _resolveReportBasePath(s);
+    const snapData = await loadVisualizerData(reportBasePath);
+    const completedMs = snapData.milestones.find((m) => m.id === milestoneId);
+    const msTitle = completedMs?.title ?? milestoneId;
+    const gsdVersion = process.env.GSD_VERSION ?? "0.0.0";
+    const projName = basename(reportBasePath);
+    const doneSlices = snapData.milestones.reduce((acc, m) => acc + m.slices.filter((sl) => sl.done).length, 0);
+    const totalSlices = snapData.milestones.reduce((acc, m) => acc + m.slices.length, 0);
+    const outPath = writeReportSnapshot({
+        basePath: reportBasePath,
+        html: generateHtmlReport(snapData, {
+            projectName: projName,
+            projectPath: reportBasePath,
+            gsdVersion,
+            milestoneId,
+            indexRelPath: "index.html",
+        }),
+        milestoneId,
+        milestoneTitle: msTitle,
+        kind: "milestone",
+        projectName: projName,
+        projectPath: reportBasePath,
+        gsdVersion,
+        totalCost: snapData.totals?.cost ?? 0,
+        totalTokens: snapData.totals?.tokens.total ?? 0,
+        totalDuration: snapData.totals?.duration ?? 0,
+        doneSlices,
+        totalSlices,
+        doneMilestones: snapData.milestones.filter((m) => m.status === "complete").length,
+        totalMilestones: snapData.milestones.length,
+        phase: snapData.phase,
+    });
+    ctx.ui.notify(`Report saved: .gsd/reports/${basename(outPath)} — open index.html to browse progression.`, "info");
+}

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,120 @@
+// 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, parseDispatchKey } 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;
+/**
+ * Fetch the latest dispatch ledger error for a unit, the single canonical
+ * lookup shared by the DispatchHistory window and the legacy
+ * `loopState.recentUnits` path in dispatch.ts. The ledger keys rows by the
+ * bare unit id with the unit type in its own column, so the lookup must use
+ * the bare id and require a unit_type match (a compound `type/id` key would
+ * miss the row, and another unit type's error on the same id must never be
+ * attached — it would trip the repeat-error rule spuriously).
+ */
+export function lookupLatestLedgerError(unitType, unitId) {
+    try {
+        const row = getLatestForUnit(unitId);
+        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;
+                const rebuilt = [];
+                for (const { key } of persisted) {
+                    const normalized = normalizeDispatchKey(key);
+                    const parsed = parseDispatchKey(normalized);
+                    const error = parsed && rebuilt.some((entry) => entry.key === normalized)
+                        ? lookupLatestLedgerError(parsed.unitType, parsed.unitId)
+                        : undefined;
+                    rebuilt.push({ key: normalized, error });
+                }
+                window = rebuilt;
+                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;
+}