gsd-pi 2.33.1 → 2.34.0-dev.6769913

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

@@ -0,0 +1,765 @@
+/**
+ * GSD Auto Mode — Fresh Session Per Unit
+ *
+ * State machine driven by .gsd/ files on disk. Each "unit" of work
+ * (plan slice, execute task, complete slice) gets a fresh session via
+ * the stashed ctx.newSession() pattern.
+ *
+ * The extension reads disk state after each agent_end, determines the
+ * next unit type, creates a fresh session, and injects a focused prompt
+ * telling the LLM which files to read and what to do.
+ */
+import { deriveState } from "./state.js";
+import { getManifestStatus } from "./files.js";
+export { inlinePriorMilestoneSummary } from "./files.js";
+import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
+import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, } from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
+import { clearActivityLogState } from "./activity-log.js";
+import { synthesizeCrashRecovery, getDeepDiagnostic, } from "./session-forensics.js";
+import { writeLock, clearLock, readCrashLock, isLockProcessAlive, } from "./crash-recovery.js";
+import { acquireSessionLock, validateSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
+import { clearUnitRuntimeRecord, readUnitRuntimeRecord, writeUnitRuntimeRecord, } from "./unit-runtime.js";
+import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode, } from "./preferences.js";
+import { sendDesktopNotification } from "./notifications.js";
+import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, } from "./auto-budget.js";
+import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, } from "./auto-tool-tracking.js";
+import { collectObservabilityWarnings as _collectObservabilityWarnings, buildObservabilityRepairBlock, } from "./auto-observability.js";
+import { closeoutUnit } from "./auto-unit-closeout.js";
+import { selectAndApplyModel } from "./auto-model-selection.js";
+import { syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree-sync.js";
+import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
+import { resetHookState, runPreDispatchHooks, restoreHookState, clearPersistedHookState, } from "./post-unit-hooks.js";
+import { runGSDDoctor, rebuildState } from "./doctor.js";
+import { preDispatchHealthGate, resetProactiveHealing, } from "./doctor-proactive.js";
+import { clearSkillSnapshot } from "./skill-discovery.js";
+import { captureAvailableSkills, resetSkillTelemetry, } from "./skill-telemetry.js";
+import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
+import { join } from "node:path";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
+import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
+import { GitServiceImpl } from "./git-service.js";
+import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
+import { createAutoWorktree, enterAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, } from "./auto-worktree.js";
+import { pruneQueueOrder } from "./queue-order.js";
+import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
+import { verifyExpectedArtifact, reconcileMergeState, } from "./auto-recovery.js";
+import { resolveDispatch } from "./auto-dispatch.js";
+import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, hideFooter, } from "./auto-dashboard.js";
+import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
+import { isDbAvailable } from "./gsd-db.js";
+import { countPendingCaptures } from "./captures.js";
+// ── Extracted modules ──────────────────────────────────────────────────────
+import { startUnitSupervision } from "./auto-timers.js";
+import { runPostUnitVerification } from "./auto-verification.js";
+import { postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
+import { bootstrapAutoSession } from "./auto-start.js";
+import { autoLoop, resolveAgentEnd } from "./auto-loop.js";
+import { WorktreeResolver, } from "./worktree-resolver.js";
+import { reorderForCaching } from "./prompt-ordering.js";
+// Worktree sync, resource staleness, stale worktree escape → auto-worktree-sync.ts
+// ─── Session State ─────────────────────────────────────────────────────────
+import { AutoSession, } from "./auto/session.js";
+export { MAX_UNIT_DISPATCHES, STUB_RECOVERY_THRESHOLD, MAX_LIFETIME_DISPATCHES, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
+// ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
+// ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
+// This file must NOT declare module-level `let` or `var` variables for state.
+// The single `s` instance below is the only mutable module-level binding.
+//
+// When adding features or fixing bugs:
+//   - New mutable state → add a property to AutoSession, not a module-level variable
+//   - New constants → module-level `const` is fine (immutable)
+//   - New state that needs reset on stopAuto → add to AutoSession.reset()
+//
+// Tests in auto-session-encapsulation.test.ts enforce this invariant.
+// ─────────────────────────────────────────────────────────────────────────────
+const s = new AutoSession();
+/** Throttle STATE.md rebuilds — at most once per 30 seconds */
+const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
+export function shouldUseWorktreeIsolation() {
+    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+    if (prefs?.isolation === "none")
+        return false;
+    if (prefs?.isolation === "branch")
+        return false;
+    return true; // default: worktree
+}
+/** Crash recovery prompt — set by startAuto, consumed by the main loop */
+/** Pending verification retry — set when gate fails with retries remaining, consumed by autoLoop */
+/** Verification retry count per unitId — separate from s.unitDispatchCount which tracks artifact-missing retries */
+/** Session file path captured at pause — used to synthesize recovery briefing on resume */
+/** Dashboard tracking */
+/** Track dynamic routing decision for the current unit (for metrics) */
+/** Queue of quick-task captures awaiting dispatch after triage resolution */
+/**
+ * Model captured at auto-mode start. Used to prevent model bleed between
+ * concurrent GSD instances sharing the same global settings.json (#650).
+ * When preferences don't specify a model for a unit type, this ensures
+ * the session's original model is re-applied instead of reading from
+ * the shared global settings (which another instance may have overwritten).
+ */
+/** Track current milestone to detect transitions */
+/** Model the user had selected before auto-mode started */
+/** Progress-aware timeout supervision */
+/** Context-pressure continue-here monitor — fires once when context usage >= 70% */
+/** Prompt character measurement for token savings analysis (R051). */
+/** SIGTERM handler registered while auto-mode is active — cleared on stop/pause. */
+/**
+ * Tool calls currently being executed — prevents false idle detection during long-running tools.
+ * Maps toolCallId → start timestamp (ms) so the idle watchdog can detect tools that have been
+ * running suspiciously long (e.g., a Bash command hung because `&` kept stdout open).
+ */
+// Re-export budget utilities for external consumers
+export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, } from "./auto-budget.js";
+/** Wrapper: register SIGTERM handler and store reference. */
+function registerSigtermHandler(currentBasePath) {
+    s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
+}
+/** Wrapper: deregister SIGTERM handler and clear reference. */
+function deregisterSigtermHandler() {
+    _deregisterSigtermHandler(s.sigtermHandler);
+    s.sigtermHandler = null;
+}
+export function getAutoDashboardData() {
+    const ledger = getLedger();
+    const totals = ledger ? getProjectTotals(ledger.units) : null;
+    // Pending capture count — lazy check, non-fatal
+    let pendingCaptureCount = 0;
+    try {
+        if (s.basePath) {
+            pendingCaptureCount = countPendingCaptures(s.basePath);
+        }
+    }
+    catch {
+        // Non-fatal — captures module may not be loaded
+    }
+    return {
+        active: s.active,
+        paused: s.paused,
+        stepMode: s.stepMode,
+        startTime: s.autoStartTime,
+        elapsed: s.active || s.paused ? Date.now() - s.autoStartTime : 0,
+        currentUnit: s.currentUnit ? { ...s.currentUnit } : null,
+        completedUnits: [...s.completedUnits],
+        basePath: s.basePath,
+        totalCost: totals?.cost ?? 0,
+        totalTokens: totals?.tokens.total ?? 0,
+        pendingCaptureCount,
+    };
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+export function isAutoActive() {
+    return s.active;
+}
+export function isAutoPaused() {
+    return s.paused;
+}
+/**
+ * Return the model captured at auto-mode start for this session.
+ * Used by error-recovery to fall back to the session's own model
+ * instead of reading (potentially stale) preferences from disk (#1065).
+ */
+export function getAutoModeStartModel() {
+    return s.autoModeStartModel;
+}
+// Tool tracking — delegates to auto-tool-tracking.ts
+export function markToolStart(toolCallId) {
+    _markToolStart(toolCallId, s.active);
+}
+export function markToolEnd(toolCallId) {
+    _markToolEnd(toolCallId);
+}
+export function getOldestInFlightToolAgeMs() {
+    return _getOldestInFlightToolAgeMs();
+}
+/**
+ * Return the base path to use for the auto.lock file.
+ * Always uses the original project root (not the worktree) so that
+ * a second terminal can discover and stop a running auto-mode session.
+ *
+ * Delegates to AutoSession.lockBasePath — the single source of truth.
+ */
+function lockBase() {
+    return s.lockBasePath;
+}
+/**
+ * Attempt to stop a running auto-mode session from a different process.
+ * Reads the lock file at the project root, checks if the PID is alive,
+ * and sends SIGTERM to gracefully stop it.
+ *
+ * Returns true if a remote session was found and signaled, false otherwise.
+ */
+export function stopAutoRemote(projectRoot) {
+    const lock = readCrashLock(projectRoot);
+    if (!lock)
+        return { found: false };
+    if (!isLockProcessAlive(lock)) {
+        // Stale lock — clean it up
+        clearLock(projectRoot);
+        return { found: false };
+    }
+    // Send SIGTERM — the auto-mode process has a handler that clears the lock and exits
+    try {
+        process.kill(lock.pid, "SIGTERM");
+        return { found: true, pid: lock.pid };
+    }
+    catch (err) {
+        return { found: false, error: err.message };
+    }
+}
+export function isStepMode() {
+    return s.stepMode;
+}
+function clearUnitTimeout() {
+    if (s.unitTimeoutHandle) {
+        clearTimeout(s.unitTimeoutHandle);
+        s.unitTimeoutHandle = null;
+    }
+    if (s.wrapupWarningHandle) {
+        clearTimeout(s.wrapupWarningHandle);
+        s.wrapupWarningHandle = null;
+    }
+    if (s.idleWatchdogHandle) {
+        clearInterval(s.idleWatchdogHandle);
+        s.idleWatchdogHandle = null;
+    }
+    if (s.continueHereHandle) {
+        clearInterval(s.continueHereHandle);
+        s.continueHereHandle = null;
+    }
+    clearInFlightTools();
+}
+/** Build snapshot metric opts, enriching with continueHereFired from the runtime record. */
+function buildSnapshotOpts(unitType, unitId) {
+    const runtime = s.currentUnit
+        ? readUnitRuntimeRecord(s.basePath, unitType, unitId)
+        : null;
+    return {
+        promptCharCount: s.lastPromptCharCount,
+        baselineCharCount: s.lastBaselineCharCount,
+        ...(s.currentUnitRouting ?? {}),
+        ...(runtime?.continueHereFired ? { continueHereFired: true } : {}),
+    };
+}
+function handleLostSessionLock(ctx) {
+    debugLog("session-lock-lost", { lockBase: lockBase() });
+    s.active = false;
+    s.paused = false;
+    clearUnitTimeout();
+    deregisterSigtermHandler();
+    ctx?.ui.notify("Session lock lost — another GSD process appears to have taken over. Stopping gracefully.", "error");
+    ctx?.ui.setStatus("gsd-auto", undefined);
+    ctx?.ui.setWidget("gsd-progress", undefined);
+    ctx?.ui.setFooter(undefined);
+}
+export async function stopAuto(ctx, pi, reason) {
+    if (!s.active && !s.paused)
+        return;
+    const reasonSuffix = reason ? ` — ${reason}` : "";
+    clearUnitTimeout();
+    if (lockBase())
+        clearLock(lockBase());
+    if (lockBase())
+        releaseSessionLock(lockBase());
+    clearSkillSnapshot();
+    resetSkillTelemetry();
+    // Remove SIGTERM handler registered at auto-mode start
+    deregisterSigtermHandler();
+    // ── Auto-worktree: exit worktree and reset s.basePath on stop ──
+    if (s.currentMilestoneId) {
+        const notifyCtx = ctx
+            ? { notify: ctx.ui.notify.bind(ctx.ui) }
+            : { notify: () => { } };
+        buildResolver().exitMilestone(s.currentMilestoneId, notifyCtx, {
+            preserveBranch: true,
+        });
+    }
+    // ── DB cleanup: close the SQLite connection ──
+    if (isDbAvailable()) {
+        try {
+            const { closeDatabase } = await import("./gsd-db.js");
+            closeDatabase();
+        }
+        catch (e) {
+            debugLog("db-close-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    if (s.originalBasePath) {
+        s.basePath = s.originalBasePath;
+        try {
+            process.chdir(s.basePath);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    const ledger = getLedger();
+    if (ledger && ledger.units.length > 0) {
+        const totals = getProjectTotals(ledger.units);
+        ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`, "info");
+    }
+    else {
+        ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}.`, "info");
+    }
+    if (s.basePath) {
+        try {
+            await rebuildState(s.basePath);
+        }
+        catch (e) {
+            debugLog("stop-rebuild-state-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    if (isDebugEnabled()) {
+        const logPath = writeDebugSummary();
+        if (logPath) {
+            ctx?.ui.notify(`Debug log written → ${logPath}`, "info");
+        }
+    }
+    resetMetrics();
+    resetRoutingHistory();
+    resetHookState();
+    if (s.basePath)
+        clearPersistedHookState(s.basePath);
+    s.active = false;
+    s.paused = false;
+    s.stepMode = false;
+    s.unitDispatchCount.clear();
+    s.unitRecoveryCount.clear();
+    clearInFlightTools();
+    s.lastBudgetAlertLevel = 0;
+    s.lastStateRebuildAt = 0;
+    s.unitLifetimeDispatches.clear();
+    s.currentUnit = null;
+    s.autoModeStartModel = null;
+    s.currentMilestoneId = null;
+    s.originalBasePath = "";
+    s.completedUnits = [];
+    s.pendingQuickTasks = [];
+    clearSliceProgressCache();
+    clearActivityLogState();
+    resetProactiveHealing();
+    s.pendingCrashRecovery = null;
+    s.pendingVerificationRetry = null;
+    s.verificationRetryCount.clear();
+    s.pausedSessionFile = null;
+    ctx?.ui.setStatus("gsd-auto", undefined);
+    ctx?.ui.setWidget("gsd-progress", undefined);
+    ctx?.ui.setFooter(undefined);
+    if (pi && ctx && s.originalModelId && s.originalModelProvider) {
+        const original = ctx.modelRegistry.find(s.originalModelProvider, s.originalModelId);
+        if (original)
+            await pi.setModel(original);
+        s.originalModelId = null;
+        s.originalModelProvider = null;
+    }
+    s.cmdCtx = null;
+}
+/**
+ * Pause auto-mode without destroying state. Context is preserved.
+ * The user can interact with the agent, then `/gsd auto` resumes
+ * from disk state. Called when the user presses Escape during auto-mode.
+ */
+export async function pauseAuto(ctx, _pi) {
+    if (!s.active)
+        return;
+    clearUnitTimeout();
+    s.pausedSessionFile = ctx?.sessionManager?.getSessionFile() ?? null;
+    if (lockBase())
+        clearLock(lockBase());
+    if (lockBase())
+        releaseSessionLock(lockBase());
+    deregisterSigtermHandler();
+    s.active = false;
+    s.paused = true;
+    s.pendingVerificationRetry = null;
+    s.verificationRetryCount.clear();
+    ctx?.ui.setStatus("gsd-auto", "paused");
+    ctx?.ui.setWidget("gsd-progress", undefined);
+    ctx?.ui.setFooter(undefined);
+    const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
+    ctx?.ui.notify(`${s.stepMode ? "Step" : "Auto"}-mode paused (Escape). Type to interact, or ${resumeCmd} to resume.`, "info");
+}
+/**
+ * Build a WorktreeResolverDeps from auto.ts private scope.
+ * Shared by buildResolver() and buildLoopDeps().
+ */
+function buildResolverDeps() {
+    return {
+        isInAutoWorktree,
+        shouldUseWorktreeIsolation,
+        getIsolationMode,
+        mergeMilestoneToMain,
+        syncWorktreeStateBack,
+        teardownAutoWorktree,
+        createAutoWorktree,
+        enterAutoWorktree,
+        getAutoWorktreePath,
+        autoCommitCurrentBranch,
+        getCurrentBranch,
+        autoWorktreeBranch,
+        resolveMilestoneFile,
+        readFileSync: (path, encoding) => readFileSync(path, encoding),
+        GitServiceImpl: GitServiceImpl,
+        loadEffectiveGSDPreferences: loadEffectiveGSDPreferences,
+        invalidateAllCaches,
+        captureIntegrationBranch,
+    };
+}
+/**
+ * Build a WorktreeResolver wrapping the current session.
+ * Cheap to construct — it's just a thin wrapper over `s` + deps.
+ * Used by stopAuto(), resume path, and buildLoopDeps().
+ */
+function buildResolver() {
+    return new WorktreeResolver(s, buildResolverDeps());
+}
+/**
+ * Build the LoopDeps object from auto.ts private scope.
+ * This bundles all private functions that autoLoop needs without exporting them.
+ */
+function buildLoopDeps() {
+    return {
+        lockBase,
+        buildSnapshotOpts,
+        stopAuto,
+        pauseAuto,
+        clearUnitTimeout,
+        updateProgressWidget,
+        // State and cache
+        invalidateAllCaches,
+        deriveState,
+        loadEffectiveGSDPreferences,
+        // Pre-dispatch health gate
+        preDispatchHealthGate,
+        // Worktree sync
+        syncProjectRootToWorktree,
+        // Resource version guard
+        checkResourcesStale,
+        // Session lock
+        validateSessionLock,
+        updateSessionLock,
+        handleLostSessionLock,
+        // Milestone transition
+        sendDesktopNotification,
+        setActiveMilestoneId,
+        pruneQueueOrder,
+        isInAutoWorktree,
+        shouldUseWorktreeIsolation,
+        mergeMilestoneToMain,
+        teardownAutoWorktree,
+        createAutoWorktree,
+        captureIntegrationBranch,
+        getIsolationMode,
+        getCurrentBranch,
+        autoWorktreeBranch,
+        resolveMilestoneFile,
+        reconcileMergeState,
+        // Budget/context/secrets
+        getLedger,
+        getProjectTotals,
+        formatCost,
+        getBudgetAlertLevel,
+        getNewBudgetAlertLevel,
+        getBudgetEnforcementAction,
+        getManifestStatus,
+        collectSecretsFromManifest,
+        // Dispatch
+        resolveDispatch,
+        runPreDispatchHooks,
+        getPriorSliceCompletionBlocker,
+        getMainBranch,
+        collectObservabilityWarnings: _collectObservabilityWarnings,
+        buildObservabilityRepairBlock,
+        // Unit closeout + runtime records
+        closeoutUnit,
+        verifyExpectedArtifact,
+        clearUnitRuntimeRecord,
+        writeUnitRuntimeRecord,
+        recordOutcome,
+        writeLock,
+        captureAvailableSkills,
+        ensurePreconditions,
+        updateSliceProgressCache,
+        // Model selection + supervision
+        selectAndApplyModel,
+        startUnitSupervision,
+        // Prompt helpers
+        getDeepDiagnostic,
+        isDbAvailable,
+        reorderForCaching,
+        // Filesystem
+        existsSync,
+        readFileSync: (path, encoding) => readFileSync(path, encoding),
+        atomicWriteSync,
+        // Git
+        GitServiceImpl: GitServiceImpl,
+        // WorktreeResolver
+        resolver: buildResolver(),
+        // Post-unit processing
+        postUnitPreVerification,
+        runPostUnitVerification,
+        postUnitPostVerification,
+        // Session manager
+        getSessionFile: (ctx) => {
+            try {
+                return ctx.sessionManager?.getSessionFile() ?? "";
+            }
+            catch {
+                return "";
+            }
+        },
+    };
+}
+export async function startAuto(ctx, pi, base, verboseMode, options) {
+    const requestedStepMode = options?.step ?? false;
+    // Escape stale worktree cwd from a previous milestone (#608).
+    base = escapeStaleWorktree(base);
+    // If resuming from paused state, just re-activate and dispatch next unit.
+    if (s.paused) {
+        const resumeLock = acquireSessionLock(base);
+        if (!resumeLock.acquired) {
+            ctx.ui.notify(`Cannot resume: ${resumeLock.reason}`, "error");
+            return;
+        }
+        s.paused = false;
+        s.active = true;
+        s.verbose = verboseMode;
+        s.stepMode = requestedStepMode;
+        s.cmdCtx = ctx;
+        s.basePath = base;
+        s.unitDispatchCount.clear();
+        s.unitLifetimeDispatches.clear();
+        if (!getLedger())
+            initMetrics(base);
+        if (s.currentMilestoneId)
+            setActiveMilestoneId(base, s.currentMilestoneId);
+        // ── Auto-worktree: re-enter worktree on resume ──
+        if (s.currentMilestoneId &&
+            shouldUseWorktreeIsolation() &&
+            s.originalBasePath &&
+            !isInAutoWorktree(s.basePath) &&
+            !detectWorktreeName(s.basePath) &&
+            !detectWorktreeName(s.originalBasePath)) {
+            buildResolver().enterMilestone(s.currentMilestoneId, {
+                notify: ctx.ui.notify.bind(ctx.ui),
+            });
+        }
+        registerSigtermHandler(lockBase());
+        ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
+        ctx.ui.setFooter(hideFooter);
+        ctx.ui.notify(s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
+        restoreHookState(s.basePath);
+        try {
+            await rebuildState(s.basePath);
+        }
+        catch (e) {
+            debugLog("resume-rebuild-state-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+        try {
+            const report = await runGSDDoctor(s.basePath, { fix: true });
+            if (report.fixesApplied.length > 0) {
+                ctx.ui.notify(`Resume: applied ${report.fixesApplied.length} fix(es) to state.`, "info");
+            }
+        }
+        catch (e) {
+            debugLog("resume-doctor-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+        invalidateAllCaches();
+        if (s.pausedSessionFile) {
+            const activityDir = join(gsdRoot(s.basePath), "activity");
+            const recovery = synthesizeCrashRecovery(s.basePath, s.currentUnit?.type ?? "unknown", s.currentUnit?.id ?? "unknown", s.pausedSessionFile ?? undefined, activityDir);
+            if (recovery && recovery.trace.toolCallCount > 0) {
+                s.pendingCrashRecovery = recovery.prompt;
+                ctx.ui.notify(`Recovered ${recovery.trace.toolCallCount} tool calls from paused session. Resuming with context.`, "info");
+            }
+            s.pausedSessionFile = null;
+        }
+        updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
+        writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
+        await autoLoop(ctx, pi, s, buildLoopDeps());
+        return;
+    }
+    // ── Fresh start path — delegated to auto-start.ts ──
+    const bootstrapDeps = {
+        shouldUseWorktreeIsolation,
+        registerSigtermHandler,
+        lockBase,
+        buildResolver,
+    };
+    const ready = await bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, bootstrapDeps);
+    if (!ready)
+        return;
+    // Dispatch the first unit
+    await autoLoop(ctx, pi, s, buildLoopDeps());
+}
+// ─── Agent End Handler ────────────────────────────────────────────────────────
+/**
+ * Deprecated thin wrapper — kept as export for backward compatibility.
+ * The actual agent_end processing now happens via resolveAgentEnd() in auto-loop.ts,
+ * which is called directly from index.ts. The autoLoop() while loop handles all
+ * post-unit processing (verification, hooks, dispatch) that this function used to do.
+ *
+ * If called by straggler code, it simply resolves the pending promise so the loop
+ * can continue.
+ */
+export async function handleAgentEnd(ctx, pi) {
+    if (!s.active || !s.cmdCtx)
+        return;
+    clearUnitTimeout();
+    resolveAgentEnd({ messages: [] });
+}
+// describeNextUnit is imported from auto-dashboard.ts and re-exported
+export { describeNextUnit } from "./auto-dashboard.js";
+/** Thin wrapper: delegates to auto-dashboard.ts, passing state accessors. */
+function updateProgressWidget(ctx, unitType, unitId, state) {
+    const badge = s.currentUnitRouting?.tier
+        ? ({ light: "L", standard: "S", heavy: "H" }[s.currentUnitRouting.tier] ??
+            undefined)
+        : undefined;
+    _updateProgressWidget(ctx, unitType, unitId, state, widgetStateAccessors, badge);
+}
+/** State accessors for the widget — closures over module globals. */
+const widgetStateAccessors = {
+    getAutoStartTime: () => s.autoStartTime,
+    isStepMode: () => s.stepMode,
+    getCmdCtx: () => s.cmdCtx,
+    getBasePath: () => s.basePath,
+    isVerbose: () => s.verbose,
+};
+// ─── Preconditions ────────────────────────────────────────────────────────────
+/**
+ * Ensure directories, branches, and other prerequisites exist before
+ * dispatching a unit. The LLM should never need to mkdir or git checkout.
+ */
+function ensurePreconditions(unitType, unitId, base, state) {
+    const parts = unitId.split("/");
+    const mid = parts[0];
+    const mDir = resolveMilestonePath(base, mid);
+    if (!mDir) {
+        const newDir = join(milestonesDir(base), mid);
+        mkdirSync(join(newDir, "slices"), { recursive: true });
+    }
+    if (parts.length >= 2) {
+        const sid = parts[1];
+        const mDirResolved = resolveMilestonePath(base, mid);
+        if (mDirResolved) {
+            const slicesDir = join(mDirResolved, "slices");
+            const sDir = resolveDir(slicesDir, sid);
+            if (!sDir) {
+                mkdirSync(join(slicesDir, sid, "tasks"), { recursive: true });
+            }
+            const resolvedSliceDir = resolveDir(slicesDir, sid) ?? sid;
+            const tasksDir = join(slicesDir, resolvedSliceDir, "tasks");
+            if (!existsSync(tasksDir)) {
+                mkdirSync(tasksDir, { recursive: true });
+            }
+        }
+    }
+}
+// ─── Diagnostics ──────────────────────────────────────────────────────────────
+/** Build recovery context from module state for recoverTimedOutUnit */
+function buildRecoveryContext() {
+    return {
+        basePath: s.basePath,
+        verbose: s.verbose,
+        currentUnitStartedAt: s.currentUnit?.startedAt ?? Date.now(),
+        unitRecoveryCount: s.unitRecoveryCount,
+    };
+}
+// Re-export recovery functions for external consumers
+export { resolveExpectedArtifactPath, verifyExpectedArtifact, writeBlockerPlaceholder, skipExecuteTask, buildLoopRemediationSteps, } from "./auto-recovery.js";
+/**
+ * Test-only: expose skip-loop state for unit tests.
+ * Not part of the public API.
+ */
+/**
+ * Dispatch a hook unit directly, bypassing normal pre-dispatch hooks.
+ * Used for manual hook triggers via /gsd run-hook.
+ */
+export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, triggerUnitId, hookPrompt, hookModel, targetBasePath) {
+    if (!s.active) {
+        s.active = true;
+        s.stepMode = true;
+        s.cmdCtx = ctx;
+        s.basePath = targetBasePath;
+        s.autoStartTime = Date.now();
+        s.currentUnit = null;
+        s.completedUnits = [];
+        s.pendingQuickTasks = [];
+    }
+    const hookUnitType = `hook/${hookName}`;
+    const hookStartedAt = Date.now();
+    s.currentUnit = {
+        type: triggerUnitType,
+        id: triggerUnitId,
+        startedAt: hookStartedAt,
+    };
+    const result = await s.cmdCtx.newSession();
+    if (result.cancelled) {
+        await stopAuto(ctx, pi);
+        return false;
+    }
+    s.currentUnit = {
+        type: hookUnitType,
+        id: triggerUnitId,
+        startedAt: hookStartedAt,
+    };
+    writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
+        phase: "dispatched",
+        wrapupWarningSent: false,
+        timeoutAt: null,
+        lastProgressAt: hookStartedAt,
+        progressCount: 0,
+        lastProgressKind: "dispatch",
+    });
+    if (hookModel) {
+        const availableModels = ctx.modelRegistry.getAvailable();
+        const match = availableModels.find((m) => m.id === hookModel || `${m.provider}/${m.id}` === hookModel);
+        if (match) {
+            try {
+                await pi.setModel(match);
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+    }
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    writeLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
+    clearUnitTimeout();
+    const supervisor = resolveAutoSupervisorConfig();
+    const hookHardTimeoutMs = (supervisor.hard_timeout_minutes ?? 30) * 60 * 1000;
+    s.unitTimeoutHandle = setTimeout(async () => {
+        s.unitTimeoutHandle = null;
+        if (!s.active)
+            return;
+        if (s.currentUnit) {
+            writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
+                phase: "timeout",
+                timeoutAt: Date.now(),
+            });
+        }
+        ctx.ui.notify(`Hook ${hookName} exceeded ${supervisor.hard_timeout_minutes ?? 30}min timeout. Pausing auto-mode.`, "warning");
+        resetHookState();
+        await pauseAuto(ctx, pi);
+    }, hookHardTimeoutMs);
+    ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
+    ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
+    debugLog("dispatchHookUnit", {
+        phase: "send-message",
+        promptLength: hookPrompt.length,
+    });
+    pi.sendMessage({ customType: "gsd-auto", content: hookPrompt, display: true }, { triggerTurn: true });
+    return true;
+}
+// Direct phase dispatch → auto-direct-dispatch.ts
+export { dispatchDirectPhase } from "./auto-direct-dispatch.js";