gsd-pi 2.81.0-dev.72a81bdf3 → 2.82.0-dev.2841a1e44

package/README.md

@@ -27,38 +27,46 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.81
+## What's New in v2.82
 
-### Worktree Safety & Projection
+### State Reconciliation & Drift Detection (ADR-017)
 
-- **Worktree safety is now fail-closed** — write/edit operations enforce the worktree-isolation contract before touching project files. If GSD cannot prove the active worktree is healthy, rooted correctly, and attached to the intended milestone, it stops instead of guessing.
-- **Custom-engine bypasses are explicit** — custom workflow units can opt out of worktree safety checks only through the dedicated path for that runtime. That keeps normal auto-mode writes protected while avoiding false failures for engines that do not use the same worktree lifecycle.
-- **Lifecycle and projection are split into dedicated modules** — worktree entry, exit, root projection, and merge finalization now flow through clearer boundaries. This makes it easier to reason about when state is copied into a milestone worktree, when it is projected back to the project root, and which module owns each step.
-- **Milestone merge closeout is harder to wedge** — stale leases, orphaned preflight stashes, branch-mode drift, reused branches, and wrong-branch merges are detected or recovered more reliably. If GSD finds completed work stranded in a milestone branch or preflight stash, startup and closeout paths now have better recovery hooks.
-- **Projection bypasses were closed** — post-unit and phase flows now route through the Worktree State Projection path instead of ad hoc file movement. That keeps database state, milestone artifacts, and root projections aligned during long-running auto-mode sessions.
+- **Unified drift-detection framework** — a new state-reconciliation layer replaces ad-hoc recovery checks. Each drift kind (stale worker, unregistered milestone, roadmap divergence, missing completion timestamp, merge-state, stale render) is owned by a focused detector + idempotent repair handler registered in a single registry, with a cap=2 retry contract that ensures repair-then-retry settles cleanly.
+- **Stale session locks no longer block resume** — when a `/gsd auto` process is SIGKILL'd, sleep-killed, or otherwise crashes, the `auto.lock` file is left behind with a dead PID. Previously you had to wait out a 30-minute stale window before `/gsd` would resume. The new `stale-worker` drift handler verifies the PID is alive and clears orphaned locks proactively on startup.
+- **Unregistered milestones get imported automatically** — if you scaffold a milestone directory (with `ROADMAP.md`/`CONTEXT.md`/`SUMMARY.md`) but never re-imported, dispatch couldn't see it. The `unregistered-milestone` handler now imports those rows idempotently before dispatch.
+- **ROADMAP and DB stay in sync** — divergence between `ROADMAP.md` (parsed slice sequence + `depends` declarations) and the corresponding DB slice rows is detected per-milestone and reconciled via importer upserts plus an explicit `syncSliceDependencies` pass.
+- **Missing completion timestamps backfill from disk** — entities marked complete in the DB but with a null `completed_at` are now backfilled from `SUMMARY.md` mtime, deterministically and idempotently. Tasks are checked independently of their parent slice status (a bug in the first cut nested task iteration behind slice completion).
+- **Parallel spawns reconcile before fanning out** — `/gsd parallel start` and slice-parallel-dispatch now run reconciliation at the parent before spawning auto-loop workers, so workers don't independently race on shared drift. Gate failures surface a typed exit reason (`slice-parallel-reconciliation-failed`) and a user-visible message instead of a confused hang.
 
-### Memory, Context & Token Control
+### Worktree Lifecycle Refactor (ADR-016 — final phases)
 
-- **Memory relevance improved** — artifacts now carry integrity fingerprints, memories track last-hit time, and relevance scoring uses time decay. Recent, repeatedly useful memories can rank higher, while stale or superseded context is less likely to crowd out the current task.
-- **Artifact integrity is easier to preserve** — content hashes are retained through worktree reconciliation, so GSD can detect whether projected artifacts still match the state it expects. This supports safer recovery and reduces accidental drift between root and worktree state.
-- **Fallback memory search is safer** — when FTS5 is unavailable, LIKE-based fallback scans are capped and surfaced with warnings instead of silently becoming expensive. Memory ranking also guards against invalid decay settings producing unusable scores.
-- **Provider tools are scoped per request** — tool availability is narrowed at request time, with provider-boundary token audit support. The model sees the tools relevant to the current provider and task instead of carrying broad tool definitions through every request.
-- **Prompt and workflow context got leaner** — repeated workflow context is capped, prompt templates use portable paths, and many high-volume workflow prompts were compacted. The goal is less repeated instruction text in long sessions without removing the guardrails that keep planning, execution, and closeout on track.
-- **Token accounting is more accurate** — session tokens are reported separately from context in VS Code, the token encoder warms at startup, and provider-boundary audit hooks make it easier to understand where request size is coming from.
+- **Phase 2 complete** — the worktree-manager module finished absorbing fs primitives, git-CLI primitives, worktree-manager helpers, cache/preferences/paths, and the final `gitServiceFactory`. Lifecycle verbs are now first-class: `adoptOrphanWorktree`, `adoptSessionRoot`, `resumeFromPausedSession`, and `restoreToProjectRoot` are explicit entry points, and the stop-path routes through `restoreToProjectRoot` instead of ad-hoc cleanup. `mergeMilestoneStandalone` was extracted and `mergeMilestoneToMain` was privatized.
+- **Phase 3 closes strict-closure residuals** — dead defensive `s.basePath = s.originalBasePath` fallbacks were removed from both auto.ts stop-path catch blocks (the verb assigns `basePath` before any throwable work, so the fallback was unreachable). The public `WorktreeLifecycleDeps` interface dropped 15 `@deprecated` optional fields; the active dep bag is now three fields (`gitServiceFactory`, `worktreeProjection`, `mergeMilestoneToMain`). Test fixtures move to a dedicated `WorktreeLifecycleTestOverrides` type.
+
+### Auto-Mode Reliability
+
+- **`complete-slice` closeout is read-only** — the closeout prompt is no longer allowed to write project files, removing a class of races where closeout edits could fight with the next slice's setup. Write-gate planning and prompt contracts were updated to enforce this.
+- **Verification retries back off properly** — a new `verification-retry-policy.ts` adds bounded exponential backoff and runs stuck detection between attempts, so transient verification failures (slow tools, flaky LLM calls) no longer spin in tight retry loops.
+- **Auto-loop exit paths are journaled end-to-end** — post-unit finalize stops, all unit-end iteration exits, and the run-unit failsafe now journal cleanly. Auto-timeout recovery journaling completes its handoff record. The run-unit failsafe also defers when a recovery is already in flight to avoid double-firing.
+- **Ghost completions and stale telemetry are guarded** — auto-mode no longer stops on ghost completions before a milestone stop has actually fired, and unmerged-exit telemetry is gated on active worktrees so closed sessions don't generate noise.
+- **Session-switch hygiene** — completed-content aborts that fire while the session is switching are ignored instead of being misclassified as user aborts. Auto-commit skips `.gitignore`d task key files so the working tree stays clean across slices.
 
 ### TUI & Operator Experience
 
-- **Compact tool output is more useful** — compact cards show tool targets and low-signal tool output can roll up by phase.
-- **Terminal UI refreshed** — chat/tool cards align with the terminal design, adaptive refresher layouts landed, and the welcome/header lifecycle is more stable.
-- **Auto-mode stays anchored** — bottom anchoring, direct tool execution rollups, and lifecycle hook shutdown behavior were tightened.
+- **Operations console redesign** — the auto-mode dashboard, notification overlay, parallel-monitor overlay, health widget, header renderer, and welcome screen were all rebuilt against a new shared `render-kit`. The result is a more consistent visual language across overlays, with refreshed reference designs (`docs/dev/tui-recommended-design.html`, `tui-render-options.html`) and expanded test coverage for the new components.
+- **Milestone completion rollup** — at the boundary between milestones, auto-mode now renders a `CompletionDashboardSnapshot` summarizing success criteria results, definition-of-done results, requirement outcomes, deviations, follow-ups, key decisions, key files, lessons learned, total cost, total tokens, cache hit rate, and slice progress. You no longer have to scroll back through the transcript to see what a milestone actually delivered.
 
-### Reliability, Tests & CI
+See the full [Changelog](./CHANGELOG.md) for the complete v2.82 entry and prior releases.
 
-- **Auto-mode recovery tightened** — crash recovery, session handoff, stale milestone completion replay, stale leases, and complete-project restart loops were all hardened.
-- **E2E coverage expanded** — real-process MCP, fake LLM, native ABI, schema migration, Docker runtime, Windows runner, and multi-iteration loop coverage landed.
-- **CI is faster and less noisy** — merge/build gates were simplified, expensive PR jobs are gated, and merge-conflict PRs skip heavy jobs.
+<details>
+<summary>v2.81 highlights</summary>
 
-See the full [Changelog](./CHANGELOG.md) for the complete v2.81 entry and prior releases.
+- **Worktree safety is fail-closed** — write/edit operations enforce the worktree-isolation contract; lifecycle and projection split into dedicated modules; milestone merge closeout is harder to wedge.
+- **Memory, context, and token control** — artifact integrity fingerprints, time-decay memory ranking, safer FTS5 fallback, request-time tool scoping, leaner workflow prompts, and more accurate session/context token accounting.
+- **TUI polish** — compact tool output with targets, refreshed chat/tool cards, adaptive refresher layouts, stable welcome/header lifecycle, and bottom-anchored auto-mode rendering.
+- **Reliability, tests, and CI** — auto-mode recovery and session handoff hardened, broad E2E coverage expansion (real-process MCP, fake LLM, native ABI, Docker, Windows), and a faster, less-noisy CI gate setup.
+
+</details>
 
 <details>
 <summary>v2.80 highlights</summary>
@@ -108,7 +116,7 @@ See the full [Changelog](./CHANGELOG.md) for the complete v2.81 entry and prior
 
 - **Context Mode** — dispatch builds task-ready context automatically (artifacts, prior session, milestone/slice signals, execution metadata); enabled by default for new projects
 - **Sandboxed execution tools** — `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output paths for context-mode flows
-- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; dual-write migration landed with decisions backfill
+- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; decisions and KNOWLEDGE patterns/lessons are memory-backed projections after the cutover
 - **Skill coverage** — 9 gap-closing skills landed plus 6 planning/design skills surfaced
 - **Hook stack** — Layer 0 shell hooks and additional Layer 2 lifecycle events
 - **TUI polish** — dedicated chat-frame style for skill invocations; active-row overflow fixes
@@ -328,7 +336,9 @@ Plan (with integrated research) → Execute (per task) → Complete → Reassess
                                                                               Validate Milestone → Complete Milestone
 ```
 
-**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded, then runs configured verification commands (lint, test, etc.) with auto-fix retries before the task closeout commit or snapshot is published. Failed or incomplete verification blocks execute-task closeout. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+
+When progressive planning is enabled, the first slice is fully planned up front while later slices may appear in `M###-ROADMAP.md` with a `` `[sketch]` `` badge. A sketch slice has an approved title, dependency shape, demo line, and scope boundary, but it has not yet been expanded into task plans; auto mode runs `refine-slice` just before execution to turn the sketch into a full slice plan using the latest prior-slice summaries.
 
 ### `/gsd auto` — The Main Event
 
@@ -340,7 +350,9 @@ This is what makes GSD different. Run it, walk away, come back to built software
 
 Auto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.
 
-The database is authoritative for milestones, slices, tasks, requirements, decisions, summaries, and completion status. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
+The database is authoritative for milestones, slices, tasks, requirements, summaries, and completion status. Durable decisions and project knowledge are stored in the `memories` table: decisions are `architecture` memories, and KNOWLEDGE patterns/lessons are `pattern`/`gotcha` memories. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
+
+`KNOWLEDGE.md` is hybrid: rules remain file-canonical, while patterns and lessons are stored in the `memories` table and rendered back into `KNOWLEDGE.md` on the next session-start projection. Existing pattern and lesson rows are backfilled into memories before projection, so newly captured patterns and lessons may appear in memory-backed prompt context before the file view refreshes.
 
 **What happens under the hood:**
 
@@ -364,7 +376,7 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 10. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
 
-11. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Auto-discovered checks from `package.json` run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
+11. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Execute-task commits and snapshots are deferred until verification passes; failed or incomplete verification blocks closeout instead of publishing changes. Auto-discovered checks from `package.json` run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
 
 12. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
 
@@ -490,6 +502,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd rethink`          | Conversational project reorganization                                         |
 | `/gsd mcp`              | MCP server status and connectivity                                            |
 | `/gsd status`           | Progress dashboard                                                            |
+| `/gsd brief <mode>`     | Generate a visual HTML brief (diagram, plan, diff, recap, table, slides)      |
 | `/gsd queue`            | Queue future milestones (safe during auto mode)                               |
 | `/gsd prefs`            | Model selection, timeouts, budget ceiling                                     |
 | `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format                           |
@@ -534,13 +547,13 @@ Every dispatch is carefully constructed. The LLM never wastes tool calls on orie
 | `gsd.db`           | Authoritative runtime state for hierarchy and completion        |
 | `PROJECT.md`       | Living doc — what the project is right now                      |
 | `REQUIREMENTS.md`  | Project-level capability contract and out-of-scope list         |
-| `DECISIONS.md`     | Append-only register of architectural decisions                 |
-| `KNOWLEDGE.md`     | Cross-session rules, patterns, and lessons learned              |
+| `DECISIONS.md`     | Projected register of memory-backed architectural decisions     |
+| `KNOWLEDGE.md`     | Hybrid knowledge projection: manual Rules plus memory-backed Patterns/Lessons |
 | `RUNTIME.md`       | Runtime context — API endpoints, env vars, services (v2.39)     |
 | `runtime/research-decision.json` | Deep-mode marker for project research vs skip       |
 | `research/*.md`    | Optional deep-mode project research: stack, features, architecture, pitfalls |
 | `STATE.md`         | Quick-glance dashboard rendered from the database                |
-| `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies |
+| `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies, and `` `[sketch]` `` badges for slices awaiting `refine-slice` |
 | `M001-CONTEXT.md`  | User decisions from the discuss phase                           |
 | `M001-RESEARCH.md` | Codebase and ecosystem research                                 |
 | `S01-PLAN.md`      | Slice task decomposition with must-haves                        |
@@ -577,6 +590,12 @@ Every task has must-haves — mechanically checkable outcomes:
 
 The verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).
 
+### Project Knowledge
+
+`.gsd/KNOWLEDGE.md` remains the human-readable register for durable project knowledge, but the memory store is now authoritative for generated Patterns and Lessons. On startup, GSD backfills existing `## Patterns` and `## Lessons Learned` rows into `gsd.db` memories, then rewrites `KNOWLEDGE.md` as a hybrid projection: the manual `## Rules` section is preserved from the file, while Patterns and Lessons are rendered from the backfilled memory rows.
+
+Keep hand-authored operating rules in `## Rules` or add them with `/gsd knowledge rule`. Patterns and Lessons that agents discover are retrieved through the memory system for prompts and projected back into `KNOWLEDGE.md` for review, reports, and git history.
+
 ### Dashboard
 
 `Ctrl+Alt+G` or `/gsd status` opens a real-time overlay showing:
@@ -821,7 +840,7 @@ gsd (CLI binary)
 - **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
 - **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
 - **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
-- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. No in-memory state survives across sessions.
+- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. `KNOWLEDGE.md` keeps rules file-canonical and projects patterns/lessons from `memories` at session start. No in-memory state survives across sessions.
 
 ---
 

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

@@ -1 +1 @@
-cec78fe13fe69412
+0829fe9060dc3f75

package/dist/resources/GSD-WORKFLOW.md

@@ -560,7 +560,7 @@ In all modes, slices and tasks commit sequentially on the active branch; there a
 
 1. **Milestone starts** → capture the current integration branch.
 2. **Optional isolation** → create `milestone/M001` only when `git.isolation` is `worktree` or `branch`.
-3. **Per-task commits** — atomic, descriptive, bisectable.
+3. **Per-task commits** — atomic, descriptive, bisectable, and published only after execute-task verification passes.
 4. **Slice completes** → write slice summary, UAT script, roadmap checkbox, and milestone summary.
 5. **Milestone completes** → if isolated, squash-merge the milestone branch back to the captured integration branch and clean up the worktree/branch.
 
@@ -574,6 +574,8 @@ fix: handle empty state rebuild
 
 In `none` mode these commits land directly on the current branch. In isolated modes they land on `milestone/<MID>` and are squashed back at milestone completion.
 
+Execute-task closeout is fail-closed: the system writes verification evidence first, defers the task commit or snapshot until verification passes, and pauses instead of publishing changes when verification fails or cannot complete.
+
 ### Commit Conventions
 
 | When | Format | Example |

package/dist/resources/extensions/browser-tools/tools/screenshot.js

@@ -5,6 +5,7 @@ export function registerScreenshotTools(pi, deps) {
         name: "browser_screenshot",
         label: "Browser Screenshot",
         description: "Take a screenshot of the current browser page and return it as an inline image. Uses JPEG for viewport/fullpage (smaller, configurable quality) and PNG for element crops (preserves transparency). Optionally crop to a specific element by CSS selector.",
+        compatibility: { producesImages: true },
         parameters: Type.Object({
             fullPage: Type.Optional(Type.Boolean({ description: "Capture the full scrollable page (default: false)" })),
             selector: Type.Optional(Type.String({

package/dist/resources/extensions/browser-tools/tools/zoom.js

@@ -9,6 +9,7 @@ export function registerZoomTools(pi, deps) {
         description: "Capture and optionally upscale a specific rectangular region of the page for detailed inspection. " +
             "Useful for dense UIs where full-page screenshots have text too small to read. " +
             "Returns the region as an inline image, same as browser_screenshot.",
+        compatibility: { producesImages: true },
         parameters: Type.Object({
             x: Type.Number({ description: "Left coordinate of the region in CSS pixels." }),
             y: Type.Number({ description: "Top coordinate of the region in CSS pixels." }),

package/dist/resources/extensions/cmux/index.js

@@ -319,6 +319,11 @@ export class CmuxClient {
         const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);
         return stdout !== null;
     }
+    // Send Ctrl-C (ETX) to a surface to interrupt the running command.
+    async sendInterrupt(surfaceId) {
+        const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, "\x03"]);
+        return stdout !== null;
+    }
 }
 export function syncCmuxSidebar(preferences, state) {
     const client = CmuxClient.fromPreferences(preferences);

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

@@ -3,6 +3,15 @@
 function now() {
     return Date.now();
 }
+/**
+ * Size of the dispatch-decision ring buffer used by the Auto Orchestration
+ * module's stuck-loop detector. When the same `${unitType}:${unitId}` key
+ * fills the window, advance() blocks with `action: "stop"`.
+ *
+ * Mirrors the legacy `STUCK_WINDOW_SIZE` in auto/phases.ts so behaviour is
+ * preserved across the eventual cutover (issue #5791).
+ */
+export const STUCK_WINDOW_SIZE = 6;
 export class AutoOrchestrator {
     status = {
         phase: "idle",
@@ -10,11 +19,13 @@ export class AutoOrchestrator {
     };
     deps;
     lastAdvanceKey = null;
+    dispatchKeyWindow = [];
     constructor(deps) {
         this.deps = deps;
     }
     async start(_sessionContext) {
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.status.phase = "running";
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "start" });
@@ -24,18 +35,70 @@ export class AutoOrchestrator {
     async advance() {
         try {
             await this.deps.runtime.ensureLockOwnership();
+            const staleMsg = this.deps.health.checkResourcesStale();
+            if (staleMsg) {
+                await this.deps.uokGate.emit({
+                    gateId: "resource-version-guard",
+                    gateType: "policy",
+                    outcome: "fail",
+                    failureClass: "policy",
+                    rationale: "resource version guard blocked dispatch",
+                    findings: staleMsg,
+                });
+                const blocked = { kind: "blocked", reason: staleMsg, action: "stop" };
+                await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
+                await this.deps.health.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            await this.deps.uokGate.emit({
+                gateId: "resource-version-guard",
+                gateType: "policy",
+                outcome: "pass",
+                failureClass: "none",
+                rationale: "resource version guard passed",
+            });
             const gate = await this.deps.health.preAdvanceGate();
-            if (!gate.allow) {
-                const blocked = { kind: "blocked", reason: gate.reason ?? "health gate blocked" };
+            if (gate.kind === "fail") {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "manual-attention",
+                    failureClass: "manual-attention",
+                    rationale: "pre-dispatch health gate blocked dispatch",
+                    findings: gate.reason,
+                });
+                const blocked = { kind: "blocked", reason: gate.reason, action: "pause" };
                 await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
                 await this.deps.health.postAdvanceRecord(blocked);
                 return blocked;
             }
+            if (gate.kind === "threw") {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "manual-attention",
+                    failureClass: "manual-attention",
+                    rationale: "pre-dispatch health gate threw unexpectedly",
+                    findings: String(gate.error),
+                });
+                // intentional fall-through: matches runPreDispatch behaviour
+            }
+            else {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "pass",
+                    failureClass: "none",
+                    rationale: "pre-dispatch health gate passed",
+                    findings: gate.fixesApplied?.join(", ") ?? "",
+                });
+            }
             const reconciliation = await this.deps.stateReconciliation.reconcileBeforeDispatch();
             if (!reconciliation.ok || !reconciliation.stateSnapshot) {
                 const blocked = {
                     kind: "blocked",
-                    reason: reconciliation.reason,
+                    reason: reconciliation.reason ?? "state reconciliation produced no snapshot",
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
@@ -48,14 +111,49 @@ export class AutoOrchestrator {
                 this.status.phase = "stopped";
                 this.status.activeUnit = undefined;
                 this.lastAdvanceKey = null;
+                this.dispatchKeyWindow = [];
                 this.bumpTransition();
                 await this.deps.runtime.journalTransition({ name: "advance-stopped", reason: stopped.reason });
                 await this.deps.health.postAdvanceRecord(stopped);
                 return stopped;
             }
             const nextKey = `${decision.unitType}:${decision.unitId}`;
-            if (this.lastAdvanceKey === nextKey) {
-                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active" };
+            // Record every dispatch decision in the ring buffer before pre-flight
+            // checks so the stuck-loop detector observes the full decision history
+            // (including decisions that idempotency would otherwise short-circuit).
+            // The ring is capped at STUCK_WINDOW_SIZE and evicts oldest-first.
+            this.dispatchKeyWindow.push(nextKey);
+            if (this.dispatchKeyWindow.length > STUCK_WINDOW_SIZE) {
+                this.dispatchKeyWindow.shift();
+            }
+            // Idempotency: same key as immediately previous successful advance.
+            // This is the soft, fast-path block kept from #5786. It only fires when
+            // the ring is NOT yet saturated for this key — once the ring is full of
+            // `nextKey`, the stuck-loop verdict takes precedence (see below). Both
+            // checks coexist: idempotency for the common immediate-repeat case,
+            // stuck-loop for the saturated-window case.
+            const matchingCount = this.dispatchKeyWindow.filter((k) => k === nextKey).length;
+            if (this.lastAdvanceKey === nextKey && matchingCount < STUCK_WINDOW_SIZE) {
+                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active", action: "stop" };
+                await this.deps.runtime.journalTransition({
+                    name: "advance-blocked",
+                    reason: blocked.reason,
+                    unitType: decision.unitType,
+                    unitId: decision.unitId,
+                });
+                await this.deps.health.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            // Stuck-loop detection: when the ring is saturated with copies of
+            // `nextKey` (count >= STUCK_WINDOW_SIZE), the orchestrator has been
+            // picking the same unit across the whole window and must hard-stop with
+            // a diagnosable reason.
+            if (matchingCount >= STUCK_WINDOW_SIZE) {
+                const blocked = {
+                    kind: "blocked",
+                    reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+                    action: "stop",
+                };
                 await this.deps.runtime.journalTransition({
                     name: "advance-blocked",
                     reason: blocked.reason,
@@ -70,6 +168,7 @@ export class AutoOrchestrator {
                 const blocked = {
                     kind: "blocked",
                     reason: contract.reason,
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({
@@ -86,6 +185,7 @@ export class AutoOrchestrator {
                 const blocked = {
                     kind: "blocked",
                     reason: worktree.reason,
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({
@@ -108,7 +208,11 @@ export class AutoOrchestrator {
                 unitId: decision.unitId,
             });
             await this.deps.worktree.syncAfterUnit(decision.unitType, decision.unitId);
-            const advanced = { kind: "advanced", stateSnapshot: reconciliation.stateSnapshot };
+            const advanced = {
+                kind: "advanced",
+                unit: { unitType: decision.unitType, unitId: decision.unitId },
+                stateSnapshot: reconciliation.stateSnapshot,
+            };
             await this.deps.health.postAdvanceRecord(advanced);
             return advanced;
         }
@@ -134,6 +238,7 @@ export class AutoOrchestrator {
             }
             if (result.kind === "stopped") {
                 this.lastAdvanceKey = null;
+                this.dispatchKeyWindow = [];
                 this.status.activeUnit = undefined;
             }
             this.bumpTransition();
@@ -158,6 +263,7 @@ export class AutoOrchestrator {
     }
     async resume() {
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.status.phase = "running";
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "resume" });
@@ -172,6 +278,7 @@ export class AutoOrchestrator {
         this.status.phase = "stopped";
         this.status.activeUnit = undefined;
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "stop", reason });
         await this.deps.notifications.notifyLifecycle({ name: "stop", detail: reason });

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

@@ -1656,6 +1656,15 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
             await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
             return { action: "break", reason: "session-timeout" };
         }
+        if (unitResult.errorContext?.isTransient &&
+            errorCategory === "aborted") {
+            ctx.ui.notify(`Unit ${unitType} ${unitId} was aborted by the user. Pausing auto-mode (recoverable).`, "warning");
+            debugLog("autoLoop", { phase: "unit-aborted-transient-pause", unitType, unitId, category: errorCategory });
+            await deps.pauseAuto(ctx, pi);
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            return { action: "break", reason: "unit-aborted-pause" };
+        }
         // All other cancelled states (structural errors, non-transient failures): hard stop
         if (s.currentUnit) {
             await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));