gsd-pi 2.81.0 → 2.82.0-dev.2841a1e44

package/README.md

@@ -27,36 +27,56 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.80
+## What's New in v2.82
 
-### DB-Authoritative Context
+### State Reconciliation & Drift Detection (ADR-017)
 
-- **UOK contracts are DB-authoritative** — runtime contract state now flows through the database instead of file-first projections.
-- **Auto-run context mode fully wired** — context-mode execution is connected end-to-end for auto runs.
-- **Planned slice recovery** — planned slices recover correctly after artifact writes.
+- **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.
 
-### Auto, Deep Mode & Gates
+### Worktree Lifecycle Refactor (ADR-016 — final phases)
 
-- **Deep queued milestones continue** — deep project milestones can resume through queued work instead of stalling.
-- **Deep project registration** — deep project milestones are registered as part of the workflow.
-- **Depth-verification gate fixes** — gate workflow regressions were closed, including case-insensitive plan-slice artifact resolution.
-- **Task commits bound to milestone completion** — automated task commits now respect the milestone completion guard.
+- **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.
 
-### MCP, Post-Exec & Cross-Platform
+### Auto-Mode Reliability
 
-- **Post-exec import hardening** — explicit extension fallbacks, dotted module stems, React Router `+types`, and `+types` guards are handled more carefully.
-- **MCP write gating** — `gsd_exec` writes are gated, with Windows path-separator test coverage tightened.
-- **Project saves stay successful** — saving a project no longer fails just because registration fails.
-- **Home-directory fallback** — `currentDirectoryRoot` uses `homedir()` fallback behavior for better cross-platform consistency.
+- **`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.
 
-### Reliability & Review Hardening
+### TUI & Operator Experience
 
-- **Auto orchestration seams and contracts** — orchestration boundaries were made more explicit and review feedback was folded in.
-- **Cancellation context preserved** — auto-mode pauses keep cancellation context instead of dropping it.
-- **Recovery stop lifecycle** — recovery stop now emits the expected lifecycle event.
-- **Trace and cleanup fixes** — trace correlation, cleanup-on-throw, audit context reset, and `onTurnResult` phase-result guards 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.
 
-See the full [Changelog](./CHANGELOG.md) for the complete v2.80 entry and prior releases.
+See the full [Changelog](./CHANGELOG.md) for the complete v2.82 entry and prior releases.
+
+<details>
+<summary>v2.81 highlights</summary>
+
+- **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>
+
+- **DB-authoritative context** — UOK contracts moved through database-backed runtime state, auto-run context mode was wired end-to-end, and planned slices recover after artifact writes.
+- **Auto, deep mode, and gates** — deep queued milestones continue, deep project milestones register cleanly, depth-verification regressions were closed, and task commits respect the milestone completion guard.
+- **MCP, post-exec, and cross-platform hardening** — post-exec import fallback handling, React Router `+types` imports, `gsd_exec` write gating, project-save behavior, and home-directory fallback behavior were tightened.
+- **Reliability and review hardening** — auto orchestration contracts, cancellation context preservation, recovery stop lifecycle events, trace correlation, cleanup-on-throw, and phase-result guards were improved.
+
+</details>
 
 <details>
 <summary>v2.79 highlights</summary>
@@ -96,7 +116,7 @@ See the full [Changelog](./CHANGELOG.md) for the complete v2.80 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
@@ -316,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
 
@@ -328,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:**
 
@@ -346,13 +370,13 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 7. **Stuck and artifact detection** — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). Missing expected artifacts use a separate bounded path: GSD retries artifact verification up to 3 times with failure context, then pauses auto mode with the missing artifact error instead of looping indefinitely.
 
-8. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
+8. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout starts recovery and only pauses auto mode if durable progress cannot be made. Runtime progress is recorded under `.gsd/runtime/`, and journal events close out unit, finalize, and iteration phases for later forensics.
 
 9. **Cost tracking** — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
 
 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.
 
@@ -478,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                           |
@@ -522,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                        |
@@ -565,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:
@@ -738,7 +769,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/metrics.json
 # Raw JSONL session dumps — crash recovery forensics, auto-pruned
 .gsd/activity/
-# Unit execution records — dispatch phase, timeouts, and recovery tracking
+# Unit execution records — dispatch phase, timeout recovery progress, and finalize tracking
 .gsd/runtime/
 # Git worktree working copies
 .gsd/worktrees/
@@ -746,7 +777,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/parallel/
 # SQLite database and WAL sidecars — authoritative runtime state, local only
 .gsd/gsd.db*
-# Daily-rotated event journal — structured event log for forensics
+# Daily-rotated event journal — structured unit/finalize/iteration event log for forensics
 .gsd/journal/
 # Doctor run history — diagnostic check results
 .gsd/doctor-history.jsonl
@@ -809,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 @@
-195cc0a83851a027
+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/loop.js

@@ -287,6 +287,13 @@ export async function autoLoop(ctx, pi, s, deps, options) {
         }
         let dispatchId = null;
         let dispatchSettled = false;
+        let iterationEndEmitted = false;
+        const emitIterationEnd = (details = {}) => {
+            if (iterationEndEmitted)
+                return;
+            iterationEndEmitted = true;
+            journalReporter.emit("iteration-end", { iteration, ...details });
+        };
         const completeIteration = () => {
             completeWorkflowIteration({
                 get consecutiveErrors() { return consecutiveErrors; },
@@ -295,11 +302,15 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 set consecutiveCooldowns(value) { consecutiveCooldowns = value; },
                 recentErrorMessages,
             }, {
-                emitIterationEnd: () => journalReporter.emit("iteration-end", { iteration }),
+                emitIterationEnd: () => emitIterationEnd(),
                 saveStuckState: () => saveStuckState(s, loopState),
                 logIterationComplete: () => debugLog("autoLoop", { phase: "iteration-complete", iteration }),
             });
         };
+        const finishIncompleteIteration = (details) => {
+            emitIterationEnd(details);
+            saveStuckState(s, loopState);
+        };
         try {
             // ── Blanket try/catch: one bad iteration must not kill the session
             const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
@@ -373,6 +384,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 if (engineState.isComplete) {
                     finishTurn("completed");
+                    emitIterationEnd({ status: "completed", reason: "custom-engine-complete" });
                     await deps.stopAuto(ctx, pi, "Workflow complete");
                     break;
                 }
@@ -389,15 +401,22 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 if (dispatchFlow.action === "break") {
                     finishTurn("stopped", "manual-attention", "custom-engine-dispatch-stop");
+                    finishIncompleteIteration({
+                        status: "stopped",
+                        reason: "custom-engine-dispatch-stop",
+                        failureClass: "manual-attention",
+                    });
                     break;
                 }
                 if (dispatchFlow.action === "continue") {
                     finishTurn("skipped");
+                    emitIterationEnd({ status: "skipped", reason: "custom-engine-dispatch-skip" });
                     continue;
                 }
                 // dispatch.action === "dispatch"
                 if (dispatch.action !== "dispatch") {
                     finishTurn("skipped");
+                    emitIterationEnd({ status: "skipped", reason: "custom-engine-dispatch-mismatch" });
                     continue;
                 }
                 const step = dispatch.step;
@@ -424,6 +443,13 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 if (guardsResult.action === "break") {
                     finishTurn("stopped", "manual-attention", "guard-break");
+                    finishIncompleteIteration({
+                        status: "stopped",
+                        reason: "guard-break",
+                        unitType: iterData.unitType,
+                        unitId: iterData.unitId,
+                        failureClass: "manual-attention",
+                    });
                     break;
                 }
                 // ── Unit execution (shared with dev path) ──
@@ -449,6 +475,13 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     unitId: iterData.unitId,
                 });
                 if (unitPhaseResult.action === "break") {
+                    finishIncompleteIteration({
+                        status: "stopped",
+                        reason: unitPhaseResult.reason ?? "unit-break",
+                        unitType: iterData.unitType,
+                        unitId: iterData.unitId,
+                        failureClass: "execution",
+                    });
                     finishTurn("stopped", "execution", "unit-break");
                     break;
                 }
@@ -466,8 +499,16 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                             finishTurn,
                         },
                     });
-                    if (verifyFlow.action === "break")
+                    if (verifyFlow.action === "break") {
+                        finishIncompleteIteration({
+                            status: "paused",
+                            reason: "custom-engine-verify-pause",
+                            unitType: iterData.unitType,
+                            unitId: iterData.unitId,
+                            failureClass: "manual-attention",
+                        });
                         break;
+                    }
                 }
                 if (verifyResult === "retry") {
                     const retryOutcome = await handleCustomEngineVerifyRetry({
@@ -501,8 +542,22 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                             finishTurn,
                         },
                     });
-                    if (retryFlow.action === "break")
+                    if (retryFlow.action === "break") {
+                        finishIncompleteIteration({
+                            status: retryOutcome.action === "stop" ? "stopped" : "paused",
+                            reason: retryOutcome.action === "retry" ? "custom-engine-verify-retry" : retryOutcome.turnError,
+                            unitType: iterData.unitType,
+                            unitId: iterData.unitId,
+                            failureClass: "manual-attention",
+                        });
                         break;
+                    }
+                    finishIncompleteIteration({
+                        status: "retry",
+                        reason: "custom-engine-verify-retry",
+                        unitType: iterData.unitType,
+                        unitId: iterData.unitId,
+                    });
                     continue;
                 }
                 // Verification passed — mark step complete
@@ -694,16 +749,36 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     markFailed: markDispatchFailed,
                     logWriteFailure: logDispatchLedgerWriteFailure,
                 }) || dispatchSettled;
+                finishIncompleteIteration({
+                    status: "stopped",
+                    reason: unitPhaseResult.reason ?? "unit-break",
+                    unitType: iterData.unitType,
+                    unitId: iterData.unitId,
+                    failureClass: "execution",
+                });
                 finishTurn("stopped", "execution", "unit-break");
                 break;
             }
             // ── Phase 5: Finalize ───────────────────────────────────────────────
             let finalizeResult;
+            journalReporter.emit("post-unit-finalize-start", {
+                iteration,
+                unitType: iterData.unitType,
+                unitId: iterData.unitId,
+            });
             try {
                 finalizeResult = await runFinalize(ic, iterData, loopState, sidecarItem);
             }
             catch (err) {
-                dispatchSettled = settleDispatchFailed(dispatchId, formatDispatchExceptionSummary({ error: err }), {
+                const error = formatDispatchExceptionSummary({ error: err });
+                journalReporter.emit("post-unit-finalize-end", {
+                    iteration,
+                    unitType: iterData.unitType,
+                    unitId: iterData.unitId,
+                    status: "failed",
+                    error,
+                });
+                dispatchSettled = settleDispatchFailed(dispatchId, error, {
                     markFailed: markDispatchFailed,
                     logWriteFailure: logDispatchLedgerWriteFailure,
                 }) || dispatchSettled;
@@ -713,6 +788,15 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 unitType: iterData.unitType,
                 unitId: iterData.unitId,
             });
+            const finalizeReason = finalizeResult.action === "break" ? finalizeResult.reason : undefined;
+            journalReporter.emit("post-unit-finalize-end", {
+                iteration,
+                unitType: iterData.unitType,
+                unitId: iterData.unitId,
+                status: finalizeResult.action === "next" ? "completed" : finalizeResult.action === "continue" ? "retry" : "stopped",
+                action: finalizeResult.action,
+                ...(finalizeReason ? { reason: finalizeReason } : {}),
+            });
             const finalizeDecision = decideFinalizeResult(finalizeResult.action === "break"
                 ? { action: "break", reason: finalizeResult.reason }
                 : finalizeResult.action === "continue"
@@ -723,6 +807,13 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     markFailed: markDispatchFailed,
                     logWriteFailure: logDispatchLedgerWriteFailure,
                 }) || dispatchSettled;
+                finishIncompleteIteration({
+                    status: "stopped",
+                    reason: finalizeReason ?? "finalize-break",
+                    unitType: iterData.unitType,
+                    unitId: iterData.unitId,
+                    failureClass: finalizeDecision.failureClass,
+                });
                 finishTurn("stopped", finalizeDecision.failureClass, finalizeDecision.turnError);
                 break;
             }
@@ -731,6 +822,12 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     markFailed: markDispatchFailed,
                     logWriteFailure: logDispatchLedgerWriteFailure,
                 }) || dispatchSettled;
+                finishIncompleteIteration({
+                    status: "retry",
+                    reason: "finalize-retry",
+                    unitType: iterData.unitType,
+                    unitId: iterData.unitId,
+                });
                 finishTurn("retry");
                 continue;
             }
@@ -750,10 +847,6 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     logWriteFailure: logDispatchLedgerWriteFailure,
                 }) || dispatchSettled;
             }
-            // Always emit iteration-end on error so the journal records iteration
-            // completion even on failure (#2344). Without this, errors in
-            // runFinalize leave the journal incomplete, making diagnosis harder.
-            journalReporter.emit("iteration-end", { iteration, error: msg });
             // ── Pre-send model-policy block: not a retryable error (#4959 / #4850) ──
             // The model-policy gate runs before the prompt is sent.  When every
             // candidate model is denied (cross-provider disabled + flat-rate
@@ -778,6 +871,12 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 ctx.ui.notify(policyDecision.notifyMessage, "error");
                 journalReporter.emit("unit-end", policyDecision.journalData);
+                finishIncompleteIteration({
+                    status: "blocked",
+                    reason: "model-policy-dispatch-blocked",
+                    unitType: loopErr.unitType,
+                    unitId: loopErr.unitId,
+                });
                 // Carry the blocked unit identity into the turn-result observer:
                 // the throw originated inside dispatch, so observedUnitType/Id were
                 // not assigned by the success path at lines 453/631/647 — but the
@@ -790,6 +889,10 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 // not a transient runtime fault.
                 break;
             }
+            // Always emit iteration-end on error so the journal records iteration
+            // completion even on failure (#2344). Without this, errors in
+            // runFinalize leave the journal incomplete, making diagnosis harder.
+            finishIncompleteIteration({ status: "failed", error: msg });
             // ── Infrastructure errors: immediate stop, no retry ──
             // These are unrecoverable (disk full, OOM, etc.). Retrying just burns
             // LLM budget on guaranteed failures.