gsd-pi 2.80.0-dev.3065f7bfa → 2.80.0-dev.488219eb6

package/dist/claude-cli-check.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Spawn the Claude CLI without triggering Node's DEP0190.
+ *
+ * Passing `args` together with `shell: true` is deprecated in Node 22+
+ * because the args are concatenated into the command string without
+ * escaping. On Windows we still need a shell to resolve `.cmd` shims, so
+ * we invoke `cmd /c <command> <args...>` explicitly. On POSIX we don't
+ * need a shell at all.
+ */
+export declare function buildClaudeSpawnInvocation(command: string, args: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
 /**
  * Platform-correct binary name for the Claude Code CLI.
  *
@@ -7,7 +20,24 @@
  * authenticated. Mirrors the `NPM_COMMAND` pattern in
  * `src/resources/extensions/gsd/pre-execution-checks.ts`.
  */
+export declare function getClaudeCommand(platform?: NodeJS.Platform): string;
 export declare const CLAUDE_COMMAND: string;
+/**
+ * Ordered list of binary names to probe for the Claude Code CLI.
+ *
+ * Windows installs vary: npm-global installs produce a `claude.cmd` shim,
+ * direct binary installs produce `claude.exe`, and Git Bash wrappers may
+ * expose a bare `claude` shim. Try all three so no valid install is missed.
+ */
+export declare function getClaudeCommandCandidates(platform?: NodeJS.Platform): string[];
+/**
+ * Decide auth state from `claude auth status` output.
+ *
+ * Newer Claude CLI builds emit JSON with a `loggedIn` boolean. Older builds
+ * emit free-form text. Prefer the structured signal; fall back to a text
+ * heuristic. The text heuristic only covers English phrasing.
+ */
+export declare function parseAuthStatus(output: string): boolean | null;
 /**
  * Check if the `claude` binary is installed (regardless of auth state).
  */

package/dist/claude-cli-check.js

@@ -14,11 +14,15 @@ import { execFileSync } from 'node:child_process';
  * we invoke `cmd /c <command> <args...>` explicitly. On POSIX we don't
  * need a shell at all.
  */
-function spawnClaude(command, args, opts) {
-    if (process.platform === 'win32') {
-        return execFileSync('cmd', ['/c', command, ...args], opts);
+export function buildClaudeSpawnInvocation(command, args, platform = process.platform) {
+    if (platform === 'win32') {
+        return { command: 'cmd', args: ['/c', command, ...args] };
     }
-    return execFileSync(command, args, opts);
+    return { command, args };
+}
+function spawnClaude(command, args, opts) {
+    const invocation = buildClaudeSpawnInvocation(command, args);
+    return execFileSync(invocation.command, invocation.args, opts);
 }
 /**
  * Platform-correct binary name for the Claude Code CLI.
@@ -29,7 +33,10 @@ function spawnClaude(command, args, opts) {
  * authenticated. Mirrors the `NPM_COMMAND` pattern in
  * `src/resources/extensions/gsd/pre-execution-checks.ts`.
  */
-export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'claude';
+export function getClaudeCommand(platform = process.platform) {
+    return platform === 'win32' ? 'claude.cmd' : 'claude';
+}
+export const CLAUDE_COMMAND = getClaudeCommand();
 /**
  * Ordered list of binary names to probe for the Claude Code CLI.
  *
@@ -37,7 +44,11 @@ export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'cla
  * direct binary installs produce `claude.exe`, and Git Bash wrappers may
  * expose a bare `claude` shim. Try all three so no valid install is missed.
  */
-const CLAUDE_COMMAND_CANDIDATES = process.platform === 'win32' ? [CLAUDE_COMMAND, 'claude.exe', 'claude'] : [CLAUDE_COMMAND];
+export function getClaudeCommandCandidates(platform = process.platform) {
+    const command = getClaudeCommand(platform);
+    return platform === 'win32' ? [command, 'claude.exe', 'claude'] : [command];
+}
+const CLAUDE_COMMAND_CANDIDATES = getClaudeCommandCandidates();
 const VERSION_TIMEOUT_MS = 5_000;
 // Auth probe needs more headroom on Windows because the spawn goes through
 // cmd.exe → claude.cmd → node → Claude CLI.
@@ -80,7 +91,7 @@ function findWorkingCommand() {
  * emit free-form text. Prefer the structured signal; fall back to a text
  * heuristic. The text heuristic only covers English phrasing.
  */
-function parseAuthStatus(output) {
+export function parseAuthStatus(output) {
     const trimmed = output.trim();
     if (!trimmed)
         return null;

package/dist/cli.js

@@ -760,25 +760,6 @@ if (!process.stdin.isTTY || !process.stdout.isTTY) {
             : 'stdout is';
     printNonTtyErrorAndExit(missing, true);
 }
-// Welcome screen — shown on every fresh interactive session before TUI takes over.
-// Skip when the first-run banner was already printed in loader.ts (prevents double banner).
-if (!process.env.GSD_FIRST_RUN_BANNER) {
-    const { printWelcomeScreen } = await import('./welcome-screen.js');
-    let remoteChannel;
-    try {
-        const { resolveRemoteConfig } = await import('./resources/extensions/remote-questions/config.js');
-        const rc = resolveRemoteConfig();
-        if (rc)
-            remoteChannel = rc.channel;
-    }
-    catch { /* non-fatal */ }
-    printWelcomeScreen({
-        version: process.env.GSD_VERSION || '0.0.0',
-        modelName: settingsManager.getDefaultModel() || undefined,
-        provider: settingsManager.getDefaultProvider() || undefined,
-        remoteChannel,
-    });
-}
 const interactiveMode = new InteractiveMode(session);
 markStartup('InteractiveMode');
 printStartupTimings();

package/dist/headless-query.d.ts

@@ -36,6 +36,13 @@ export declare function shouldUseAgentExtensionsDir(opts: {
     agentDir: string;
     useAgentDir: boolean;
 };
+declare function loadExtensionModules(): Promise<{
+    openProjectDbIfPresent: (basePath: string) => Promise<void>;
+    deriveState: (basePath: string) => Promise<GSDState>;
+    resolveDispatch: (opts: any) => Promise<any>;
+    readAllSessionStatuses: (basePath: string) => any[];
+    loadEffectiveGSDPreferences: () => any;
+}>;
 export interface QuerySnapshot {
     state: GSDState;
     next: {
@@ -59,4 +66,7 @@ export interface QueryResult {
     exitCode: number;
     data?: QuerySnapshot;
 }
+type HeadlessQueryModules = Awaited<ReturnType<typeof loadExtensionModules>>;
+export declare function runHeadlessQuery(basePath: string, modules: HeadlessQueryModules, writeOutput?: (text: string) => void): Promise<QueryResult>;
 export declare function handleQuery(basePath: string): Promise<QueryResult>;
+export {};

package/dist/headless-query.js

@@ -77,9 +77,8 @@ async function loadExtensionModules() {
         loadEffectiveGSDPreferences: prefsModule.loadEffectiveGSDPreferences,
     };
 }
-// ─── Implementation ─────────────────────────────────────────────────────────
-export async function handleQuery(basePath) {
-    const { openProjectDbIfPresent, deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences, } = await loadExtensionModules();
+export async function runHeadlessQuery(basePath, modules, writeOutput = (text) => process.stdout.write(text)) {
+    const { openProjectDbIfPresent, deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences, } = modules;
     await openProjectDbIfPresent(basePath);
     const state = await deriveState(basePath);
     // Derive next dispatch action
@@ -120,6 +119,9 @@ export async function handleQuery(basePath) {
         next,
         cost: { workers, total: workers.reduce((sum, w) => sum + w.cost, 0) },
     };
-    process.stdout.write(JSON.stringify(snapshot) + '\n');
+    writeOutput(JSON.stringify(snapshot) + '\n');
     return { exitCode: 0, data: snapshot };
 }
+export async function handleQuery(basePath) {
+    return runHeadlessQuery(basePath, await loadExtensionModules());
+}

package/dist/loader-entrypoint.d.ts

@@ -0,0 +1,8 @@
+export interface LoaderEntrypointOptions {
+    gsdRoot: string;
+    invokedBinPath: string | undefined;
+    env?: NodeJS.ProcessEnv;
+    existsSync?: (path: string) => boolean;
+}
+export declare function resolveLoaderCliEntrypoint({ gsdRoot, invokedBinPath, env, existsSync, }: LoaderEntrypointOptions): string | undefined;
+export declare function applyLoaderCliEntrypointEnv(env: NodeJS.ProcessEnv, options: LoaderEntrypointOptions): string | undefined;

package/dist/loader-entrypoint.js

@@ -0,0 +1,27 @@
+// GSD-2 - Loader child-process entrypoint resolution helpers.
+import { existsSync as defaultExistsSync } from "node:fs";
+import { join, resolve } from "node:path";
+export function resolveLoaderCliEntrypoint({ gsdRoot, invokedBinPath, env = process.env, existsSync = defaultExistsSync, }) {
+    const sourceLoaderPath = join(gsdRoot, "src", "loader.ts");
+    const devCliPath = env.GSD_DEV_CLI_PATH?.trim() || join(gsdRoot, "scripts", "dev-cli.js");
+    const explicitCliPath = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+    const isSourceLoader = Boolean(invokedBinPath && resolve(invokedBinPath) === sourceLoaderPath);
+    const rawGsdBinPath = explicitCliPath || (isSourceLoader && existsSync(devCliPath) ? devCliPath : invokedBinPath);
+    return rawGsdBinPath ? resolve(rawGsdBinPath) : undefined;
+}
+export function applyLoaderCliEntrypointEnv(env, options) {
+    const resolvedGsdBinPath = resolveLoaderCliEntrypoint({ ...options, env });
+    if (resolvedGsdBinPath) {
+        env.GSD_BIN_PATH = resolvedGsdBinPath;
+        if (!env.GSD_CLI_PATH) {
+            env.GSD_CLI_PATH = resolvedGsdBinPath;
+        }
+    }
+    else {
+        delete env.GSD_BIN_PATH;
+        if (!env.GSD_CLI_PATH) {
+            delete env.GSD_CLI_PATH;
+        }
+    }
+    return resolvedGsdBinPath;
+}

package/dist/loader.js

@@ -63,6 +63,7 @@ import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
 import { resolveBundledResourcesDirFromPackageRoot } from './bundled-resource-path.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
 import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled } from './extension-registry.js';
+import { applyLoaderCliEntrypointEnv } from './loader-entrypoint.js';
 import { renderLogo } from './logo.js';
 // pkg/ is a shim directory: contains gsd's piConfig (package.json) and pi's
 // theme assets (dist/modes/interactive/theme/) without a src/ directory.
@@ -117,17 +118,7 @@ process.env.GSD_VERSION = gsdVersion;
 // subagent/parallel workers to spawn gsd instead of pi when dispatching
 // workflow tasks. In source-dev mode this must remain scripts/dev-cli.js, not
 // src/loader.ts, because child processes need the --import resolve-ts wrapper.
-const invokedBinPath = process.argv[1];
-const sourceLoaderPath = join(gsdRoot, 'src', 'loader.ts');
-const devCliPath = process.env.GSD_DEV_CLI_PATH?.trim() || join(gsdRoot, 'scripts', 'dev-cli.js');
-const explicitCliPath = process.env.GSD_CLI_PATH?.trim() || process.env.GSD_BIN_PATH?.trim();
-const isSourceLoader = invokedBinPath && resolve(invokedBinPath) === sourceLoaderPath;
-const rawGsdBinPath = explicitCliPath || (isSourceLoader && existsSync(devCliPath) ? devCliPath : invokedBinPath);
-const resolvedGsdBinPath = rawGsdBinPath ? resolve(rawGsdBinPath) : undefined;
-process.env.GSD_BIN_PATH = resolvedGsdBinPath;
-if (!process.env.GSD_CLI_PATH) {
-    process.env.GSD_CLI_PATH = resolvedGsdBinPath;
-}
+applyLoaderCliEntrypointEnv(process.env, { gsdRoot, invokedBinPath: process.argv[1] });
 // GSD_WORKFLOW_PATH — absolute path to bundled GSD-WORKFLOW.md, used by patched gsd extension
 // when dispatching workflow prompts. Prefers dist/resources/ (stable, set at build time)
 // over src/resources/ (live working tree) — see resource-loader.ts for rationale.

package/dist/mcp-server.d.ts

@@ -22,6 +22,7 @@ export interface McpToolDef {
         isError?: boolean;
     }>;
 }
+export declare function mcpSdkSpecifier(subpath: 'server/index' | 'server/stdio' | 'types'): string;
 /**
  * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
  *

package/dist/mcp-server.js

@@ -29,6 +29,9 @@ function isPlainObject(value) {
 // built via a template string so TypeScript's NodeNext resolver treats them as
 // `any` and skips static checking.
 const MCP_PKG = '@modelcontextprotocol/sdk';
+export function mcpSdkSpecifier(subpath) {
+    return `${MCP_PKG}/${subpath}.js`;
+}
 /**
  * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
  *
@@ -45,9 +48,9 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
  */
 export async function startMcpServer(options) {
     const { tools, version = '0.0.0' } = options;
-    const serverMod = await import(`${MCP_PKG}/server/index.js`);
-    const stdioMod = await import(`${MCP_PKG}/server/stdio.js`);
-    const typesMod = await import(`${MCP_PKG}/types.js`);
+    const serverMod = await import(mcpSdkSpecifier('server/index'));
+    const stdioMod = await import(mcpSdkSpecifier('server/stdio'));
+    const typesMod = await import(mcpSdkSpecifier('types'));
     const Server = serverMod.Server;
     const StdioServerTransport = stdioMod.StdioServerTransport;
     const { ListToolsRequestSchema, CallToolRequestSchema } = typesMod;

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-89938c18ffd18359
+186fe07f8b8d9487

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

@@ -23,11 +23,15 @@ import { execFileSync } from "node:child_process";
  * we invoke `cmd /c <command> <args...>` explicitly. On POSIX we don't
  * need a shell at all.
  */
-function spawnClaude(command, args, opts) {
-    if (process.platform === "win32") {
-        return execFileSync("cmd", ["/c", command, ...args], opts);
+export function buildClaudeSpawnInvocation(command, args, platform = process.platform) {
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/c", command, ...args] };
     }
-    return execFileSync(command, args, opts);
+    return { command, args };
+}
+function spawnClaude(command, args, opts) {
+    const invocation = buildClaudeSpawnInvocation(command, args);
+    return execFileSync(invocation.command, invocation.args, opts);
 }
 /**
  * Candidate executable names for the Claude Code CLI.
@@ -35,14 +39,21 @@ function spawnClaude(command, args, opts) {
  * Keep the explicit win32 ternary selector for regression coverage (Issue #4424):
  * Node's execFileSync must target `claude.cmd` directly on Windows.
  */
-const CLAUDE_COMMAND = process.platform === "win32" ? "claude.cmd" : "claude";
+export function getClaudeCommand(platform = process.platform) {
+    return platform === "win32" ? "claude.cmd" : "claude";
+}
+const CLAUDE_COMMAND = getClaudeCommand();
 /**
  * Windows installs vary: some environments expose `claude.cmd` (npm shim),
  * `claude.exe` (direct binary install), or a bare `claude` shim on PATH
  * (for example Git Bash wrappers). Try all three to avoid false "not
  * installed" results in readiness checks.
  */
-const CLAUDE_COMMAND_CANDIDATES = process.platform === "win32" ? [CLAUDE_COMMAND, "claude.exe", "claude"] : [CLAUDE_COMMAND];
+export function getClaudeCommandCandidates(platform = process.platform) {
+    const command = getClaudeCommand(platform);
+    return platform === "win32" ? [command, "claude.exe", "claude"] : [command];
+}
+const CLAUDE_COMMAND_CANDIDATES = getClaudeCommandCandidates();
 // Keep the version probe snappy — `claude --version` is a quick path.
 const VERSION_TIMEOUT_MS = 5_000;
 // Auth status can be much slower on Windows because the spawn goes through
@@ -90,7 +101,7 @@ function findWorkingCommand() {
  * back to a text heuristic. Note: the text heuristic only covers English
  * phrasing — the JSON path is the durable signal.
  */
-function parseAuthStatus(output) {
+export function parseAuthStatus(output) {
     const trimmed = output.trim();
     if (!trimmed)
         return null;

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

@@ -261,6 +261,26 @@ function makeErrorMessage(model, errorMsg) {
         timestamp: Date.now(),
     };
 }
+export function isClaudeCodeAbortErrorMessage(message) {
+    if (!message)
+        return false;
+    return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
+}
+function isBareClaudeCodeAbortErrorMessage(message) {
+    if (!message)
+        return false;
+    const normalized = message.trim().replace(/\s+/g, " ").toLowerCase();
+    return normalized === "claude code process aborted by user"
+        || normalized === "request aborted by user"
+        || normalized === "process aborted by user";
+}
+export function resolveClaudeCodeAbortedMessageText(errorMsg, lastTextContent) {
+    const trimmedError = errorMsg.trim();
+    if (trimmedError && !isBareClaudeCodeAbortErrorMessage(trimmedError)) {
+        return trimmedError;
+    }
+    return lastTextContent;
+}
 /**
  * Generator exhaustion without a terminal result means the SDK stream was
  * interrupted mid-turn. Surface it as an error so downstream recovery logic
@@ -1512,6 +1532,15 @@ async function pumpSdkMessages(model, context, options, stream) {
     }
     catch (err) {
         const errorMsg = err instanceof Error ? err.message : String(err);
+        if (options?.signal?.aborted || isClaudeCodeAbortErrorMessage(errorMsg)) {
+            const abortedText = resolveClaudeCodeAbortedMessageText(errorMsg, lastTextContent);
+            stream.push({
+                type: "error",
+                reason: "aborted",
+                error: makeAbortedMessage(modelId, abortedText),
+            });
+            return;
+        }
         stream.push({
             type: "error",
             reason: "error",

package/dist/resources/extensions/github-sync/sync.js

@@ -79,6 +79,9 @@ export async function runGitHubSync(basePath, unitType, unitId) {
         debugLog("github-sync", { error: String(err) });
     }
 }
+export function shouldCreateSlicePrForSyncEvent(unitType, config) {
+    return unitType === "complete-slice" && config.slice_prs !== false;
+}
 // ─── Per-Event Sync Functions ───────────────────────────────────────────────
 async function syncMilestonePlan(basePath, mapping, config, mid) {
     // Skip if already synced
@@ -307,7 +310,7 @@ async function syncSliceComplete(basePath, mapping, config, mid, sid) {
     }
     if (!sliceRecord || sliceRecord.state === "closed")
         return;
-    if (!sliceRecord.prNumber && config.slice_prs !== false) {
+    if (!sliceRecord.prNumber && shouldCreateSlicePrForSyncEvent("complete-slice", config)) {
         await ensureSlicePullRequest(basePath, mapping, mid, sid);
         sliceRecord = getSliceRecord(mapping, mid, sid);
         if (!sliceRecord || !sliceRecord.prNumber)

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

@@ -16,7 +16,7 @@ import { ModelPolicyDispatchBlockedError } from "../auto-model-selection.js";
 import { resolveEngine } from "../engine-resolver.js";
 import { logWarning } from "../workflow-logger.js";
 import { recordDispatchClaim, markRunning as markDispatchRunning, markCompleted as markDispatchCompleted, markFailed as markDispatchFailed, getRecentForUnit as getRecentDispatchesForUnit, getRecentUnitKeysForProjectRoot, } from "../db/unit-dispatches.js";
-import { refreshMilestoneLease } from "../db/milestone-leases.js";
+import { claimMilestoneLease, refreshMilestoneLease } from "../db/milestone-leases.js";
 import { heartbeatAutoWorker } from "../db/auto-workers.js";
 import { getRuntimeKv, setRuntimeKv } from "../db/runtime-kv.js";
 import { resolveUokFlags } from "../uok/flags.js";
@@ -27,7 +27,7 @@ import { hydrateCustomVerifyRetryCounts, saveCustomVerifyRetryCounts, } from "./
 import { settleDispatchCompleted, settleDispatchFailed, } from "./workflow-dispatch-ledger.js";
 import { emitOpenUnitEndForUnit } from "../crash-recovery.js";
 import { writeUnitRuntimeRecord } from "../unit-runtime.js";
-import { openDispatchClaim } from "./workflow-dispatch-claim.js";
+import { ensureDispatchLease, openDispatchClaim } from "./workflow-dispatch-claim.js";
 import { completeWorkflowIteration } from "./workflow-iteration-completion.js";
 import { createWorkflowJournalReporter } from "./workflow-journal-reporter.js";
 import { createWorkflowPhaseReporter } from "./workflow-phase-reporter.js";
@@ -105,6 +105,18 @@ function logDispatchClaimFailed(err) {
         error: err instanceof Error ? err.message : String(err),
     });
 }
+function logDispatchLeaseRecovered(details) {
+    debugLog("autoLoop", {
+        phase: details.recovered ? "dispatch-lease-recovered" : "dispatch-lease-acquired",
+        ...details,
+    });
+}
+function logDispatchLeaseRecoveryFailed(details) {
+    debugLog("autoLoop", {
+        phase: "dispatch-lease-recovery-failed",
+        ...details,
+    });
+}
 function logCustomVerifyRetryLoadFailure(err) {
     debugLog("autoLoop", {
         phase: "load-custom-verify-retries-failed",
@@ -186,6 +198,10 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 phase: "heartbeat-failed",
                 error: err instanceof Error ? err.message : String(err),
             }),
+            logLeaseRefreshMiss: details => debugLog("autoLoop", {
+                phase: "lease-refresh-missed",
+                ...details,
+            }),
         });
         // ── Journal: per-iteration flow grouping ──
         const flowId = randomUUID();
@@ -581,23 +597,70 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             await enforceMinRequestInterval(s, prefs);
             // Phase B: claim a unit_dispatches row before invoking the unit. The
             // partial unique index idx_unit_dispatches_active_per_unit prevents
-            // a second worker from claiming the same unit concurrently. Returns
-            // null when DB unavailable, no worker registered, or no active lease
-            // — those degraded paths fall through to the existing single-worker
-            // semantics with no ledger entry, preserving back-compat.
-            const dispatchClaim = openDispatchClaim(s, flowId, turnId, iterData, {
+            // a second worker from claiming the same unit concurrently. When this
+            // process has a worker identity, make the milestone lease explicit before
+            // claiming so a step-mode handoff cannot leave us running with a stale
+            // in-memory token and no backing lease row.
+            const leaseBeforeClaim = ensureDispatchLease(s, iterData.mid, {
+                claimMilestoneLease,
+                logLeaseRecovered: logDispatchLeaseRecovered,
+                logLeaseRecoveryFailed: logDispatchLeaseRecoveryFailed,
+            });
+            if (leaseBeforeClaim.kind === "blocked" || leaseBeforeClaim.kind === "failed") {
+                const msg = `Lost milestone lease for ${iterData.mid ?? "unknown"} before dispatching ${iterData.unitType} ${iterData.unitId}: ${leaseBeforeClaim.reason}`;
+                ctx.ui.notify(msg, "error");
+                finishTurn("stopped", "execution", msg);
+                await deps.stopAuto(ctx, pi, msg);
+                break;
+            }
+            let dispatchClaim = openDispatchClaim(s, flowId, turnId, iterData, {
                 getRecentDispatchesForUnit,
                 recordDispatchClaim,
                 markDispatchRunning,
                 logClaimRejected: logDispatchClaimRejected,
                 logClaimFailed: logDispatchClaimFailed,
             });
-            const dispatchDecision = decideDispatchClaim(dispatchClaim.kind === "opened"
+            let dispatchDecision = decideDispatchClaim(dispatchClaim.kind === "opened"
                 ? { kind: "opened", dispatchId: dispatchClaim.dispatchId }
                 : dispatchClaim.kind === "skip"
                     ? { kind: "skip", reason: dispatchClaim.reason }
                     : { kind: "degraded" });
+            if (dispatchDecision.action === "skip" && dispatchDecision.reason === "stale-lease") {
+                const leaseRecovery = ensureDispatchLease(s, iterData.mid, {
+                    claimMilestoneLease,
+                    logLeaseRecovered: logDispatchLeaseRecovered,
+                    logLeaseRecoveryFailed: logDispatchLeaseRecoveryFailed,
+                }, { forceReclaim: true });
+                if (leaseRecovery.kind === "ready") {
+                    dispatchClaim = openDispatchClaim(s, flowId, turnId, iterData, {
+                        getRecentDispatchesForUnit,
+                        recordDispatchClaim,
+                        markDispatchRunning,
+                        logClaimRejected: logDispatchClaimRejected,
+                        logClaimFailed: logDispatchClaimFailed,
+                    });
+                    dispatchDecision = decideDispatchClaim(dispatchClaim.kind === "opened"
+                        ? { kind: "opened", dispatchId: dispatchClaim.dispatchId }
+                        : dispatchClaim.kind === "skip"
+                            ? { kind: "skip", reason: dispatchClaim.reason }
+                            : { kind: "degraded" });
+                }
+                else {
+                    const msg = `Lost milestone lease for ${iterData.mid ?? "unknown"} while claiming ${iterData.unitType} ${iterData.unitId}: ${leaseRecovery.reason}`;
+                    ctx.ui.notify(msg, "error");
+                    finishTurn("stopped", "execution", msg);
+                    await deps.stopAuto(ctx, pi, msg);
+                    break;
+                }
+            }
             if (dispatchDecision.action === "skip") {
+                if (dispatchDecision.reason === "stale-lease") {
+                    const msg = `Lost milestone lease for ${iterData.mid ?? "unknown"} while claiming ${iterData.unitType} ${iterData.unitId}; dispatch claim still failed after recovery.`;
+                    ctx.ui.notify(msg, "error");
+                    finishTurn("stopped", "execution", msg);
+                    await deps.stopAuto(ctx, pi, msg);
+                    break;
+                }
                 finishTurn("skipped", "execution", dispatchDecision.reason);
                 continue;
             }

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Auto-loop pipeline phases, merge closeout, and finalize handling.
 /**
  * auto/phases.ts — Pipeline phases for the auto-loop.
  *
@@ -76,9 +78,15 @@ const PLAN_V2_GATE_PHASES = new Set([
     "validating-milestone",
     "completing-milestone",
 ]);
-function shouldRunPlanV2Gate(phase) {
+export function shouldRunPlanV2Gate(phase) {
     return PLAN_V2_GATE_PHASES.has(phase);
 }
+export function _shouldProceedWithInvalidRepoClassificationForTest(reason, hasGit) {
+    return reason === "missing .git" && hasGit;
+}
+export function _resolveCurrentUnitStartedAtForTest(currentUnit) {
+    return currentUnit?.startedAt;
+}
 /**
  * Generate and write an HTML milestone report snapshot.
  * Extracted from the milestone-transition block in autoLoop.
@@ -202,6 +210,17 @@ export async function _runMilestoneMergeWithStashRestore(ic, milestoneId) {
     }
     return null;
 }
+export async function _runMilestoneMergeOnceWithStashRestore(ic, milestoneId) {
+    if (ic.s.milestoneMergedInPhases) {
+        debugLog("autoLoop", {
+            phase: "milestone-merge-skip",
+            reason: "already-merged-in-phases",
+            milestoneId,
+        });
+        return null;
+    }
+    return _runMilestoneMergeWithStashRestore(ic, milestoneId);
+}
 async function emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, errorContext) {
     ic.deps.emitJournalEvent({
         ts: new Date().toISOString(),
@@ -546,7 +565,7 @@ export async function runPreDispatch(ic, loopState) {
         // Worktree lifecycle on milestone transition — merge current, enter next.
         // #2909 / #5538-followup: preflight stash + always-on postflight pop.
         {
-            const stop = await _runMilestoneMergeWithStashRestore(ic, s.currentMilestoneId);
+            const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
             if (stop)
                 return stop;
         }
@@ -605,7 +624,7 @@ export async function runPreDispatch(ic, loopState) {
             // All milestones complete — merge milestone branch before stopping.
             if (s.currentMilestoneId) {
                 // #2909 / #5538-followup: preflight stash + always-on postflight pop.
-                const stop = await _runMilestoneMergeWithStashRestore(ic, s.currentMilestoneId);
+                const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
                 if (stop)
                     return stop;
                 // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
@@ -673,7 +692,7 @@ export async function runPreDispatch(ic, loopState) {
         // Milestone merge on complete (before closeout so branch state is clean).
         if (s.currentMilestoneId) {
             // #2909 / #5538-followup: preflight stash + always-on postflight pop.
-            const stop = await _runMilestoneMergeWithStashRestore(ic, s.currentMilestoneId);
+            const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
             if (stop)
                 return stop;
             // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
@@ -1145,7 +1164,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         if (projectClassification.kind === "invalid-repo") {
             const msg = `Worktree health check failed: ${s.basePath} classified as invalid-repo (${projectClassification.reason}) — refusing to dispatch ${unitType} ${unitId}`;
             debugLog("runUnitPhase", { phase: "worktree-health-invalid-repo", basePath: s.basePath, classification: projectClassification });
-            if (projectClassification.reason === "missing .git" && hasGit) {
+            if (_shouldProceedWithInvalidRepoClassificationForTest(projectClassification.reason, hasGit)) {
                 ctx.ui.notify(`Warning: ${s.basePath} project classification could not confirm .git; assuming it has no project content yet — proceeding as greenfield project because worktree health reported .git present`, "warning");
             }
             else {
@@ -1527,7 +1546,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     {
         const currentLedger = deps.getLedger();
         if (currentLedger?.units) {
-            const lastUnit = [...currentLedger.units].reverse().find((u) => u.type === unitType && u.id === unitId && u.startedAt === s.currentUnit?.startedAt);
+            const lastUnit = [...currentLedger.units].reverse().find((u) => u.type === unitType && u.id === unitId && u.startedAt === _resolveCurrentUnitStartedAtForTest(s.currentUnit));
             if (lastUnit && lastUnit.toolCalls === 0) {
                 if (USER_DRIVEN_DEEP_UNITS.has(unitType) && isAwaitingUserInput(s.lastUnitAgentEndMessages ?? undefined)) {
                     debugLog("runUnitPhase", {
@@ -1546,7 +1565,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
                     ctx.ui.notify(`${unitType} ${unitId} completed with 0 tool calls — context exhaustion, will retry`, "warning");
                     // Fall through to next iteration where dispatch will re-derive
                     // and re-dispatch this unit.
-                    return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt, requestDispatchedAt: unitResult.requestDispatchedAt } };
+                    return { action: "next", data: { unitStartedAt: _resolveCurrentUnitStartedAtForTest(s.currentUnit), requestDispatchedAt: unitResult.requestDispatchedAt } };
                 }
             }
         }
@@ -1600,7 +1619,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         }
         s.checkpointSha = null;
     }
-    return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt, requestDispatchedAt: unitResult.requestDispatchedAt } };
+    return { action: "next", data: { unitStartedAt: _resolveCurrentUnitStartedAtForTest(s.currentUnit), requestDispatchedAt: unitResult.requestDispatchedAt } };
 }
 // ─── runFinalize ──────────────────────────────────────────────────────────────
 /**
@@ -1733,6 +1752,11 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
         debugLog("autoLoop", { phase: "exit", reason: "step-wizard" });
         return { action: "break", reason: "step-wizard" };
     }
+    if (preUnitSnapshot?.type === "complete-milestone" && s.currentMilestoneId) {
+        const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
+        if (stop)
+            return stop;
+    }
     // Both pre and post verification completed without timeout — reset counter
     loopState.consecutiveFinalizeTimeouts = 0;
     if (preUnitSnapshot) {