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

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -1,13 +1,16 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
 
+import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
+import { recoveryRemediation } from "./guidance.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
 import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
   | "tool-contract"
+  | "tool-unavailable"
   | "deterministic-policy"
   | "lifecycle-progression"
   | "stale-worker"
@@ -49,106 +52,49 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
         ? "illegal-transition"
         : input.failureKind ?? inferFailureKind(message);
 
-  switch (failureKind) {
-    case "tool-schema":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Tool schema failure${unitSuffix(input)}: ${message}`,
-        exitReason: "tool-schema",
-        remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
-      };
-    case "tool-contract":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
-        exitReason: "tool-contract",
-        remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
-      };
-    case "deterministic-policy":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Deterministic policy failure${unitSuffix(input)}: ${message}`,
-        exitReason: "deterministic-policy",
-        remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
-      };
-    case "lifecycle-progression":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
-        exitReason: "lifecycle-progression",
-        remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
-      };
-    case "stale-worker":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Stale worker failure${unitSuffix(input)}: ${message}`,
-        exitReason: "stale-worker",
-        remediation: "Clear or reconcile the stale worker before dispatching another Unit.",
-      };
-    case "worktree-invalid":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Worktree invalid${unitSuffix(input)}: ${message}`,
-        exitReason: "worktree-invalid",
-        remediation: "Repair or recreate the milestone worktree before launching source-writing Units.",
-      };
-    case "verification-drift":
-      return {
-        failureKind,
-        action: "escalate",
-        reason: `Verification drift${unitSuffix(input)}: ${message}`,
-        exitReason: "verification-drift",
-        remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
-      };
-    case "reconciliation-drift":
-      return {
-        failureKind,
-        action: "escalate",
-        reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
-        exitReason: "reconciliation-drift",
-        remediation:
-          "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
-      };
-    case "illegal-transition":
-      return {
-        failureKind,
-        action: "escalate",
-        reason: `Illegal phase transition${unitSuffix(input)}: ${message}`,
-        exitReason: "illegal-transition",
-        remediation:
-          "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
-      };
-    case "provider": {
-      const providerClass = classifyError(message, input.retryAfterMs);
-      return {
-        failureKind,
-        action: isTransient(providerClass) ? "retry" : "escalate",
-        reason: message,
-        exitReason: `provider-${providerClass.kind}`,
-        remediation: isTransient(providerClass)
-          ? "Retry after the provider/network condition clears."
-          : "Inspect provider credentials, model entitlement, or request shape.",
-        providerClass: providerClass.kind,
-      };
-    }
-    case "runtime-unknown":
-      return {
-        failureKind,
-        action: "escalate",
-        reason: message,
-        exitReason: "runtime-unknown",
-        remediation: "Inspect the runtime error and add a dedicated classification if it is repeatable.",
-      };
+  if (failureKind === "provider") {
+    const providerClass = classifyError(message, input.retryAfterMs);
+    const transient = isTransient(providerClass);
+    return {
+      failureKind,
+      action: transient ? "retry" : "escalate",
+      reason: message,
+      exitReason: `provider-${providerClass.kind}`,
+      remediation: recoveryRemediation(transient ? "provider-transient" : "provider-permanent"),
+      providerClass: providerClass.kind,
+    };
   }
+
+  const { action, label } = FAILURE_TAXONOMY[failureKind];
+  return {
+    failureKind,
+    action,
+    reason: label ? `${label}${unitSuffix(input)}: ${message}` : message,
+    exitReason: failureKind,
+    remediation: recoveryRemediation(failureKind),
+  };
 }
 
+/** Per-kind action and reason label. Remediation lives in the Guidance module. */
+const FAILURE_TAXONOMY: Record<
+  Exclude<RecoveryFailureKind, "provider">,
+  { action: RecoveryAction; label: string | null }
+> = {
+  "tool-schema": { action: "stop", label: "Tool schema failure" },
+  "tool-contract": { action: "stop", label: "Tool Contract failure" },
+  "tool-unavailable": { action: "retry", label: "Tool unavailable" },
+  "deterministic-policy": { action: "stop", label: "Deterministic policy failure" },
+  "lifecycle-progression": { action: "stop", label: "Lifecycle progression failure" },
+  "stale-worker": { action: "stop", label: "Stale worker failure" },
+  "worktree-invalid": { action: "stop", label: "Worktree invalid" },
+  "verification-drift": { action: "escalate", label: "Verification drift" },
+  "reconciliation-drift": { action: "escalate", label: "Reconciliation drift" },
+  "illegal-transition": { action: "escalate", label: "Illegal phase transition" },
+  "runtime-unknown": { action: "escalate", label: null },
+};
+
 function inferFailureKind(message: string): RecoveryFailureKind {
+  if (isToolUnavailableError(message)) return "tool-unavailable";
   if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message)) return "tool-contract";
   if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message)) return "lifecycle-progression";
   if (/schema|invalid.*tool|tool.*invalid|enum/i.test(message)) return "tool-schema";

package/src/resources/extensions/gsd/safety/destructive-confirmation.ts

@@ -0,0 +1,134 @@
+/**
+ * One-shot confirmation token for destructive bash commands.
+ *
+ * The destructive-command guard hard-blocks classified commands (force push,
+ * rm -rf, SQL drop, etc.) in all modes. The block instructs the model to
+ * confirm via ask_user_questions and re-issue the command. This module is the
+ * missing escape hatch: it records the user's confirmation and lets the exact
+ * confirmed command through exactly once.
+ *
+ * Design constraints:
+ *  - In-memory only, never persisted. A confirmation token written to disk
+ *    could silently auto-approve a destructive command in a later session —
+ *    confirmation must be re-obtained every process lifetime.
+ *  - One-shot. Consuming a token clears it, so a second destructive command
+ *    (even an identical one) re-blocks and re-prompts.
+ *  - Command-bound. The token only matches the exact (normalized) command
+ *    string the user confirmed. A reworded command re-blocks, which is safe.
+ *  - Per basePath, so concurrent workspaces in one process never share tokens.
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+
+import { resolve } from "node:path";
+
+/**
+ * Question-id substring that marks an ask_user_questions call as a
+ * destructive-command confirmation. The tool_result handler promotes the
+ * pending command to a confirmed token when an affirmative answer arrives for
+ * a question whose id contains this marker.
+ */
+export const DESTRUCTIVE_CONFIRM_GATE_MARKER = "destructive_confirm";
+
+interface DestructiveConfirmationState {
+  /** Command awaiting confirmation, captured when the guard blocked it. */
+  pendingCommand: string | null;
+  /** Confirmed command cleared on first matching consume. */
+  confirmedCommand: string | null;
+}
+
+const statesByBasePath = new Map<string, DestructiveConfirmationState>();
+
+function stateKey(basePath: string): string {
+  return resolve(basePath);
+}
+
+function getState(basePath: string): DestructiveConfirmationState {
+  const key = stateKey(basePath);
+  let state = statesByBasePath.get(key);
+  if (!state) {
+    state = { pendingCommand: null, confirmedCommand: null };
+    statesByBasePath.set(key, state);
+  }
+  return state;
+}
+
+/**
+ * Normalize a command for stable matching across block → confirm → retry.
+ * Trims surrounding whitespace and collapses internal runs of whitespace so
+ * cosmetic reformatting of the same command still matches the token.
+ */
+export function normalizeDestructiveCommand(command: string): string {
+  return command.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Whether an ask_user_questions question id is a destructive-confirm gate.
+ */
+export function isDestructiveConfirmGateId(questionId: unknown): boolean {
+  return typeof questionId === "string" && questionId.includes(DESTRUCTIVE_CONFIRM_GATE_MARKER);
+}
+
+/**
+ * Record that a destructive command was blocked and is awaiting confirmation.
+ * Called by the guard at block time. Overwrites any prior pending command —
+ * only the most recently blocked command can be confirmed.
+ */
+export function requestDestructiveConfirmation(
+  command: string,
+  basePath: string = process.cwd(),
+): void {
+  const state = getState(basePath);
+  state.pendingCommand = normalizeDestructiveCommand(command);
+  // A fresh request invalidates any stale confirmed token for a different
+  // command so confirmation cannot leak across distinct destructive actions.
+  state.confirmedCommand = null;
+}
+
+/**
+ * Promote the pending command to a confirmed, one-shot token. Called by the
+ * tool_result handler when the user gives an affirmative answer to a
+ * destructive-confirm gate. Returns the confirmed command, or null if there
+ * was nothing pending (e.g. confirmation arrived without a preceding block).
+ */
+export function confirmDestructiveCommand(
+  basePath: string = process.cwd(),
+): string | null {
+  const state = getState(basePath);
+  if (!state.pendingCommand) return null;
+  state.confirmedCommand = state.pendingCommand;
+  state.pendingCommand = null;
+  return state.confirmedCommand;
+}
+
+/**
+ * Check whether the given command has been confirmed, consuming the token if
+ * so. Returns true exactly once per confirmation; subsequent calls (or a
+ * non-matching command) return false. Called by the guard before blocking.
+ */
+export function consumeDestructiveConfirmation(
+  command: string,
+  basePath: string = process.cwd(),
+): boolean {
+  const state = getState(basePath);
+  if (!state.confirmedCommand) return false;
+  if (state.confirmedCommand !== normalizeDestructiveCommand(command)) return false;
+  state.confirmedCommand = null;
+  return true;
+}
+
+/**
+ * Inspect the pending command without consuming it (diagnostics/tests).
+ */
+export function peekPendingDestructiveCommand(
+  basePath: string = process.cwd(),
+): string | null {
+  return getState(basePath).pendingCommand;
+}
+
+/**
+ * Clear all destructive-confirmation state for a basePath (tests / flow reset).
+ */
+export function resetDestructiveConfirmation(basePath: string = process.cwd()): void {
+  statesByBasePath.delete(stateKey(basePath));
+}

package/src/resources/extensions/gsd/state.ts

@@ -13,6 +13,11 @@ import type {
   MilestoneRegistryEntry,
 } from './types.js';
 
+// Pre-migration fallback ONLY (ADR-017): deriveState must work on projects
+// whose DB does not exist yet (before md-importer runs), so it parses markdown
+// projections when `isDbAvailable()` is false or the DB has no rows. Once the
+// DB is populated, decision reads go through gsd-db queries — these parsers
+// must never be consulted when DB data is present.
 import {
   parseRoadmap,
   parsePlan,
@@ -71,27 +76,10 @@ import {
   readinessNeedsDiscussion,
 } from './milestone-readiness.js';
 
-function formatNeedsAttentionBlocker(milestoneId: string): string {
-  return [
-    `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
-    `Fix options:`,
-    `1. Review the validation details: \`/gsd status\``,
-    `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
-    `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-    `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-    `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
-  ].join("\n");
-}
-
-function formatNeedsRemediationBlocker(milestoneId: string): string {
-  return [
-    `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
-    `Fix options:`,
-    `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
-    `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-    `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-  ].join("\n");
-}
+import {
+  needsAttentionBlockerGuidance as formatNeedsAttentionBlocker,
+  needsRemediationBlockerGuidance as formatNeedsRemediationBlocker,
+} from './guidance.js';
 
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive

package/src/resources/extensions/gsd/stop-notice.ts

@@ -0,0 +1,75 @@
+// Project/App: gsd-pi
+// File Purpose: Stop Notice module — single owner of the auto/step-mode
+// stop/pause notice vocabulary. Both sides of the wire live here: the
+// formatters that produce the canonical prefixes (used by stopAuto/pauseAuto)
+// and the classifiers that recognize them (used by the headless host to pick
+// exit codes). Wording changes in this file keep emitter and detector in
+// lockstep; round-trip tests enforce it.
+
+export type StopNoticeKind = "stopped" | "blocked";
+
+/** A reason string of the form "Blocked: …" marks a blocked stop. */
+export function isBlockedStopReason(reason?: string | null): boolean {
+  return /^Blocked:\s*/i.test(reason ?? "");
+}
+
+/** Strip the "Blocked: " marker for display. */
+export function stopNoticeDisplayReason(reason?: string | null): string {
+  return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
+}
+
+export function stopNoticeKind(reason?: string | null): StopNoticeKind {
+  return isBlockedStopReason(reason) ? "blocked" : "stopped";
+}
+
+/** Canonical stop-notice prefix: "Auto-mode blocked — reason" / "Auto-mode stopped". */
+export function formatStopNoticePrefix(reason?: string | null): string {
+  const displayReason = stopNoticeDisplayReason(reason);
+  const prefix = stopNoticeKind(reason) === "blocked" ? "Auto-mode blocked" : "Auto-mode stopped";
+  return displayReason ? `${prefix} — ${displayReason}` : prefix;
+}
+
+// ─── Classification (headless host side) ────────────────────────────────
+// The canonical lowercase prefixes the headless event loop recognizes in
+// notify messages. Emitters above and ad-hoc emitters elsewhere must start
+// their terminal notices with one of these.
+
+export const PAUSED_NOTICE_PREFIXES = ["auto-mode paused", "step-mode paused"] as const;
+
+export const TERMINAL_NOTICE_PREFIXES = [
+  "auto-mode stopped",
+  "step-mode stopped",
+  "auto-mode complete",
+  "no active milestone",
+  "auto-mode idle",
+] as const;
+
+/** Manual-resolution notices emitted before auto-mode can formally pause/stop. */
+export function isManualResolutionNotice(message: string): boolean {
+  return (
+    message.includes("resolve manually and re-run /gsd auto") ||
+    message.includes("resolve conflicts manually and run /gsd auto to resume") ||
+    message.includes("resolve and run /gsd auto to resume")
+  );
+}
+
+export function isPauseNotice(message: string): boolean {
+  return PAUSED_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+export function isTerminalNotice(message: string): boolean {
+  return TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+/** Pauses that do not require operator intervention in headless mode. */
+export function isNonBlockingPauseNotice(message: string): boolean {
+  return message.includes("idempotent advance: unit already active");
+}
+
+export function isBlockedNoticeMessage(message: string): boolean {
+  return (
+    message.includes("blocked:") ||
+    (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
+    isManualResolutionNotice(message)
+  );
+}

package/src/resources/extensions/gsd/tests/auto-model-selection.test.ts

@@ -857,3 +857,25 @@ test("resolveModelId: claude-code wins when session is claude-code regardless of
   assert.ok(result, "should resolve a model");
   assert.equal(result.provider, "claude-code", "claude-code must win when it is the session provider");
 });
+
+test("resolveModelId: openai-codex wins over openai for bare GPT IDs when both are available", () => {
+  const availableModels = [
+    { id: "gpt-5.5", provider: "openai" },
+    { id: "gpt-5.5", provider: "openai-codex" },
+  ];
+
+  const result = resolveModelId("gpt-5.5", availableModels, undefined);
+  assert.ok(result, "should resolve a model");
+  assert.equal(result.provider, "openai-codex", "ChatGPT OAuth must win over platform API for bare IDs");
+});
+
+test("resolveModelId: github-copilot wins over openai when both offer the same GPT model", () => {
+  const availableModels = [
+    { id: "gpt-5.5", provider: "openai" },
+    { id: "gpt-5.5", provider: "github-copilot" },
+  ];
+
+  const result = resolveModelId("gpt-5.5", availableModels, undefined);
+  assert.ok(result);
+  assert.equal(result.provider, "github-copilot");
+});

package/src/resources/extensions/gsd/tests/auto-orchestrator.test.ts

@@ -22,8 +22,8 @@ import {
   createAutoOrchestrator,
   decideOrchestratorDispatch,
   resolveLiveOrchestratorBasePath,
-  STUCK_WINDOW_SIZE,
 } from "../auto/orchestrator.js";
+import { STUCK_WINDOW_SIZE } from "../auto/dispatch-history.js";
 import type { OrchestratorContext } from "../auto/orchestrator.js";
 import type { AutoOrchestrationModule, AutoSessionContext } from "../auto/contracts.js";
 import type { GSDState } from "../types.js";
@@ -41,6 +41,10 @@ import {
   openDatabase,
 } from "../gsd-db.js";
 import { AutoSession } from "../auto/session.js";
+import { registerAutoWorker } from "../db/auto-workers.js";
+import { claimMilestoneLease } from "../db/milestone-leases.js";
+import { recordDispatchClaim, markFailed } from "../db/unit-dispatches.js";
+import { normalizeRealPath } from "../paths.js";
 import { acquireSessionLock, releaseSessionLock } from "../session-lock.js";
 import { queryJournal } from "../journal.js";
 import { invalidateAllCaches } from "../cache.js";
@@ -518,13 +522,12 @@ test("advance() is idempotent for the same active unit", async (t) => {
   if (first.kind === "advanced") {
     assert.deepEqual(first.unit, { unitType: "execute-task", unitId: "M001/S01/T01" });
   }
-  assert.equal(second.kind, "blocked");
-  if (second.kind !== "blocked") return;
+  assert.equal(second.kind, "skipped");
+  if (second.kind !== "skipped") return;
   assert.equal(second.reason, "idempotent advance: unit already active");
-  assert.equal(second.action, "pause");
 });
 
-test("idempotency block fires with its own reason before saturation", async (t) => {
+test("idempotency skip fires with its own reason before saturation", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());
 
@@ -532,10 +535,9 @@ test("idempotency block fires with its own reason before saturation", async (t)
   const second = await f.orchestrator.advance();
 
   assert.equal(first.kind, "advanced");
-  assert.equal(second.kind, "blocked");
-  if (second.kind !== "blocked") return;
+  assert.equal(second.kind, "skipped");
+  if (second.kind !== "skipped") return;
   assert.equal(second.reason, "idempotent advance: unit already active");
-  assert.equal(second.action, "pause");
 });
 
 test("completeActiveUnit clears in-flight idempotency and stops stale same-unit advance", async (t) => {
@@ -671,12 +673,12 @@ test("resume() clears idempotent lock and allows re-advance", async (t) => {
   t.after(() => f.cleanup());
 
   const first = await f.orchestrator.advance();
-  const blocked = await f.orchestrator.advance();
+  const idempotent = await f.orchestrator.advance();
   const resumed = await f.orchestrator.resume();
   const next = await f.orchestrator.advance();
 
   assert.equal(first.kind, "advanced");
-  assert.equal(blocked.kind, "blocked");
+  assert.equal(idempotent.kind, "skipped");
   assert.equal(resumed.kind, "resumed");
   assert.equal(next.kind, "advanced");
 });
@@ -686,11 +688,11 @@ test("start() clears prior idempotent lock", async (t) => {
   t.after(() => f.cleanup());
 
   await f.orchestrator.advance();
-  const blocked = await f.orchestrator.advance();
+  const idempotent = await f.orchestrator.advance();
   const restarted = await f.orchestrator.start(SESSION_CONTEXT);
   const next = await f.orchestrator.advance();
 
-  assert.equal(blocked.kind, "blocked");
+  assert.equal(idempotent.kind, "skipped");
   assert.equal(restarted.kind, "started");
   assert.equal(next.kind, "advanced");
 });
@@ -700,32 +702,28 @@ test("stop() clears idempotent unit lock so advance can run again", async (t) =>
   t.after(() => f.cleanup());
 
   const first = await f.orchestrator.advance();
-  const blocked = await f.orchestrator.advance();
+  const idempotent = await f.orchestrator.advance();
   const stopped = await f.orchestrator.stop("reset");
   const second = await f.orchestrator.advance();
 
   assert.equal(first.kind, "advanced");
-  assert.equal(blocked.kind, "blocked");
+  assert.equal(idempotent.kind, "skipped");
   assert.equal(stopped.kind, "stopped");
   assert.equal(second.kind, "advanced");
 });
 
-test("blocked path journals advance-blocked and records a health snapshot", async (t) => {
+test("idempotent path journals advance-skipped and records a health snapshot", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());
 
   await f.orchestrator.advance();
   await f.orchestrator.advance();
 
-  assert.ok(f.journalNames().includes("advance-blocked"));
+  assert.ok(f.journalNames().includes("advance-skipped"));
 });
 
 // ─── Stuck-loop ring buffer (issue #5787) ──────────────────────────────────
 
-test("STUCK_WINDOW_SIZE matches the legacy auto/phases.ts constant", () => {
-  assert.equal(STUCK_WINDOW_SIZE, 6);
-});
-
 test("stuck-loop: empty ring on a freshly constructed orchestrator advances normally", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());
@@ -761,21 +759,24 @@ test("stuck-loop: ring saturated with same unit blocks with action 'stop' and st
   // First call advances.
   assert.equal(results[0].kind, "advanced");
 
-  // Intermediate calls are blocked by idempotency (not stuck-loop yet).
+  // Intermediate calls are skipped by idempotency (not stuck-loop yet).
   for (let i = 1; i < STUCK_WINDOW_SIZE - 1; i++) {
     const r = results[i];
-    assert.equal(r.kind, "blocked", `round ${i} should be blocked`);
-    if (r.kind !== "blocked") return;
+    assert.equal(r.kind, "skipped", `round ${i} should be skipped`);
+    if (r.kind !== "skipped") return;
     assert.equal(r.reason, "idempotent advance: unit already active");
-    assert.equal(r.action, "pause");
   }
 
-  // The final call (ring now holds STUCK_WINDOW_SIZE copies) returns stuck-loop.
+  // The final call (ring now holds STUCK_WINDOW_SIZE copies) returns stuck-loop
+  // with the detect-stuck rule verdict in the reason.
   const last = results[STUCK_WINDOW_SIZE - 1];
   assert.equal(last.kind, "blocked");
   if (last.kind !== "blocked") return;
   assert.equal(last.action, "stop");
-  assert.equal(last.reason, `stuck-loop: execute-task:M001/S01/T01 picked ${STUCK_WINDOW_SIZE} times`);
+  assert.ok(
+    last.reason.startsWith("stuck-loop: execute-task:M001/S01/T01 derived"),
+    `expected detect-stuck verdict reason, got: ${last.reason}`,
+  );
 });
 
 test("stuck-loop: start() resets the ring so a fresh saturation cycle is required", async (t) => {
@@ -855,6 +856,80 @@ test("stuck-loop: stop('user-request') resets the ring (hard stop)", async (t) =
   assert.equal(next.kind, "advanced");
 });
 
+test("stuck-loop #482 regression: start() rehydrates the window from the dispatch ledger so cross-session re-dispatch loops are detected", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
+
+  // Simulate a PRIOR session: the dispatch ledger recorded the same unit
+  // being re-dispatched repeatedly without progress. The orchestrator under test is a
+  // fresh instance (as it would be after a session restart) — before the
+  // Dispatch History module, start() reset the window to [] and the loop
+  // would silently re-dispatch the unit forever (#482: 146 re-dispatches).
+  const worker = registerAutoWorker({ projectRootRealpath: normalizeRealPath(f.base) });
+  const lease = claimMilestoneLease(worker, "M001");
+  assert.equal(lease.ok, true);
+  if (!lease.ok) return;
+  for (let i = 0; i < STUCK_WINDOW_SIZE - 1; i++) {
+    const claim = recordDispatchClaim({
+      traceId: `prior-session-${i}`,
+      workerId: worker,
+      milestoneLeaseToken: lease.token,
+      milestoneId: "M001",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+    assert.equal(claim.ok, true);
+    if (!claim.ok) return;
+    markFailed(claim.dispatchId, { errorSummary: "" });
+  }
+
+  const started = await f.orchestrator.start(SESSION_CONTEXT);
+  assert.equal(started.kind, "started");
+
+  // The very next decision for the same unit must trip the stuck verdict
+  // instead of advancing.
+  const result = await f.orchestrator.advance();
+  assert.equal(result.kind, "blocked");
+  if (result.kind !== "blocked") return;
+  assert.equal(result.action, "stop");
+  assert.ok(result.reason.startsWith("stuck-loop:"), `expected stuck-loop reason, got: ${result.reason}`);
+});
+
+test("stuck-loop #482: resume() with an empty window rehydrates from the dispatch ledger", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
+
+  const worker = registerAutoWorker({ projectRootRealpath: normalizeRealPath(f.base) });
+  const lease = claimMilestoneLease(worker, "M001");
+  assert.equal(lease.ok, true);
+  if (!lease.ok) return;
+  for (let i = 0; i < STUCK_WINDOW_SIZE - 1; i++) {
+    const claim = recordDispatchClaim({
+      traceId: `prior-session-resume-${i}`,
+      workerId: worker,
+      milestoneLeaseToken: lease.token,
+      milestoneId: "M001",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+    assert.equal(claim.ok, true);
+    if (!claim.ok) return;
+    markFailed(claim.dispatchId, { errorSummary: "" });
+  }
+
+  // Fresh orchestrator resuming a prior session: window starts empty, so
+  // resume() must rehydrate (while in-process resume keeps the live window —
+  // see the #572 preservation tests above).
+  const resumed = await f.orchestrator.resume();
+  assert.equal(resumed.kind, "resumed");
+
+  const result = await f.orchestrator.advance();
+  assert.equal(result.kind, "blocked");
+  if (result.kind !== "blocked") return;
+  assert.equal(result.action, "stop");
+  assert.ok(result.reason.startsWith("stuck-loop:"), `expected stuck-loop reason, got: ${result.reason}`);
+});
+
 test("stuck-loop: journal records the stuck-loop reason on advance-blocked", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());