gsd-pi 2.79.0 → 2.80.0

package/README.md

@@ -27,54 +27,95 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.78
+## What's New in v2.79
 
-### Worktree Lifecycle & Forensics
+### DB-Authoritative Runtime State
 
-- **Slice-cadence worktree collapse (#4765)** — new `git.collapse_cadence: "milestone" | "slice"` preference. With `slice`, each validated slice squash-merges to main immediately, shrinking the orphan window from milestone-size to slice-size. Pair with `git.milestone_resquash: true` to collapse per-slice commits into one milestone commit at completion.
-- **Worktree telemetry (#4764)** — new journal events (`worktree-created`, `worktree-merged`, `worktree-orphaned`, `auto-exit`, `canonical-root-redirect`, `slice-merged`, `milestone-resquash`) and a `summarizeWorktreeTelemetry` aggregator that reports orphan breakdowns, merge durations, conflict counts, exit reasons, and unmerged-exit metrics.
-- **`/gsd forensics` worktree section** — surfaces the telemetry above with two new anomalies: `worktree-orphan` and `worktree-unmerged-exit`.
-- **Worktree-aware canonical milestone root (#4761)** — `resolveCanonicalMilestoneRoot` routes validators and cross-session readers through the live worktree, so milestone validation no longer silently reads stale project-root state.
-- **Bootstrap orphan audit (#4762)** — in-progress milestones with commits ahead of main no longer get skipped; the audit emits a warning with commit count and worktree location so interrupted auto-runs are visible.
+- **Auto-mode coordination tables (#5247)** — workers, leases, dispatches, and a command queue are now first-class DB rows, replacing ad-hoc files for cross-process auto coordination.
+- **`auto.lock` + `paused-session.json` → DB (#5250)** — phase C pt 2 of the runtime-state migration. The on-disk lockfile and paused-session JSON are gone; lock acquisition, stale-lock detection, and pause state all live in `gsd.db`.
+- **Stuck-state migration (#5249)** — `copyPlanningArtifacts` / `reconcile` deleted; auto-mode writers canonicalize through the DB instead of mirroring artifacts to disk.
+- **`gsd headless recover`** — non-TTY DB recovery command for unattended environments where the interactive recover flow can't run.
+- **Doctor surfaces DB locks** — `gsd doctor` reports DB-backed stale locks and flags exhausted `run-uat` retry counters so wedged runs are visible without log archaeology.
 
-### Auto Pipeline & Component System
+### Workspace & Worktree Isolation
 
-- **Unified component system** — skills, agents, pipelines, and marketplace are now one component model wired through runtime, dispatch, and telemetry, replacing per-surface plumbing.
-- **UnitContextManifest v2 (#4924, #4934)** — auto dispatch runs through a typed manifest with declarative tools-policy and typed computed artifacts. CI guards the schema so drift fails fast.
-- **Composer migration phase 3 (#4782)** — `complete-slice`, `research-milestone`, `run-uat`, and `reassess-roadmap` now build context through the manifest composer for a consistent shape across units.
-- **Milestone scope classifier + pipeline variants (#4781)** — auto picks a pipeline variant from milestone shape, so research-heavy and execution-heavy milestones no longer share a one-size dispatch path.
-- **Per-unit-type skill manifest resolver (#4779)** — skills wire into specific unit types instead of being globally on, with manifests expanded across the remaining types.
-- **Single-writer-v3 control plane** — closes outstanding gaps in the durable-state writer model so concurrent writers can't desync workflow state.
-- **Opt-in `reassess-roadmap` (#4778)** — gated behind the `skip_clean_reassess` preference per ADR-003 §4; auto no longer triggers reassessment unprompted.
+- **`GsdWorkspace` + `MilestoneScope` handle types** — workspace identity is now an explicit handle threaded through writers, metrics, and the DB connection instead of a module singleton.
+- **Symlink-safe canonicalization** — `deriveState` read root and cache key are canonicalized; path normalization unified on `realpathSync.native`; `gsdRootCache` keys normalized and decoupled from per-turn cache clears; `git-root` anchor guarded against `~/.gsd` resolution.
+- **Worktree-scoped DB + metrics** — `gsd-db` connections and metrics ledgers are scoped by workspace identity, so concurrent milestones in separate worktrees can't cross-contaminate state.
+- **Worktree cwd anchoring** — subagent dispatch anchors to the canonical worktree path, `mergeAndExit` anchors cwd at project root (closes [#5079](https://github.com/gsd-build/GSD-2/issues/5079)), MCP cwd is hardened against drift, and dispatch stops on cwd anchor failures.
+- **Slice isolation through resolver (#5246)** — slice merge isolation routed through the worktree resolver; `originalBase` checks use `isSamePath` instead of string equality; `auto-worktree` validates `milestoneId` match in `ByScope` wrappers.
+- **Worktree CLI commands** — `gsd worktree {list, merge, clean, remove}` exposed in the TUI dispatcher.
 
-### Extensions Framework
+### Deep Planning Mode (Phase 11)
 
-- **Extension lifecycle commands** — `gsd extensions install / update / uninstall / list / info / validate` for npm, git, and local sources, with dependency warnings and user-metadata tracking.
-- **Topological extension load order** — Kahn's-algorithm sort with surfaced `ExtensionLoadWarning`s, so dependent extensions resolve deterministically and misconfigurations are visible instead of silent.
-- **cmux ↔ gsd decoupling** — static cross-imports replaced with a shared `cmux-events` contract and dynamic imports, isolating extension boundaries.
-- **Extracted `@gsd-extensions/google-search` workspace** — first reference extension carved out of core; legacy in-tree source replaced with a deprecation stub.
+- **`/gsd new-project --deep`** — opt-in deep mode for new projects, with `research-decision` and `research-project` dispatch units, deep-mode artifact validators, and gated approval flows that pause the milestone instead of aborting on grounding/discovery questions.
+- **EVAL-REVIEW system** — `/gsd eval-review` command, frontmatter schema, pre-ship soft warning when EVAL-REVIEW status is incomplete, and registration in the catalog + ops dispatcher.
+- **Project-shape-aware discuss depth** — discuss-phase questioning depth scales via the project-shape classifier; tiny apps cap research and auto-skip stale research blockers; deep research is opt-in and blocked while a marker is in flight.
+- **Approval-gate hardening** — deep approval gates verified, opening interview question protected from approval abort, plain-text setup approvals gated, deep setup state guarded against phantom transitions.
 
-### Models, Agent, and UX
+### Auto Pipeline & Dispatch
 
-- **GPT-5.5 Codex support** — added across `gsd` and `pi-ai`, including `xhigh` thinking level for custom GPT-5.5 models.
-- **Auth mode in `/model`** — providers display alongside auth mode for clearer routing.
-- **Permission granularity picker** — Claude Code "Always Allow" prompts let you scope the grant instead of approving the broad case.
-- **Headless auto default → `bypassPermissions` (#4657)** — Claude Code CLI headless auto-mode runs without permission prompts by default.
-- **`skillFilter` for system prompts** — `pi-coding-agent` filters which skills are surfaced in `buildSystemPrompt`, with consumer exceptions guarded.
-- **Visual postinstall (#4641)** — install shows a spinner/banner UX so first-run state is legible.
-- **PR-risk verification** — risk prompt emits a copy-pasteable code block to make follow-up commands one step.
+- **Delegation-policy verdicts** — dispatch actions are annotated with a per-tool background-safety policy verdict; the policy itself is codified instead of inferred per call.
+- **Reactive-execute default** — auto-dispatch defaults to reactive-execute when ≥3 ready tasks are queued, replacing the always-sequential fallback.
+- **Proactive rate limiting (#2996)** — `min_request_interval_ms` preference paces auto-mode requests; the interval is stamped at dispatch.
+- **Manifest-driven skill surfacing** — `auto-prompts` surfaces manifest skills via recommendations + auto-match; planning-dispatch mode added to the unit manifest for slice plan/complete; runtime tools-policy enforced for planning units (#4934).
+- **Subagent telemetry** — dispatch telemetry, stronger prompt guidelines, and model-override threading (`??` consistently used for `modelOverride`).
 
-### Reliability & Safety
+### MCP, Models & Cross-Platform
 
-- **Major git-safety pass** — clarified TOCTOU ancestry guard, atomic sync-lock acquire with PID-verified stale override, `.git/index.lock` force-removal gated by 5-min age, `GIT_DIR`/`GIT_WORK_TREE`/`GIT_INDEX_FILE` stripped from env overlays, rebase/cherry-pick/revert state detected and aborted in recovery, working tree stashed before `reset --hard` in self-heal/rollback, worktree create guarded against unborn branches, and user hooks + `commit.gpgsign` honored on auto-commits.
-- **Atomic `.gsd/` state writes** — file-locks now actually lock and throw on contention; appends are lock-wrapped to prevent interleaved writes.
-- **Compaction correctness (#4665)** — fixed chunker/truncation mismatch and silent chunk-drops that produced degenerate or empty summaries.
-- **Write-gate (#4950)** — fail-closed depth confirmation, EXDEV-safe snapshot rename, opt-out persistence default, off-by-one max-attempts fix, exception capture in `gate.execute`, and audit/DB rows for unknown gate ids.
-- **Auto state machine** — deterministic policy errors classified non-retriable (#4973), depth-verification bypass for non-interactive sessions, baseline restored between units (#4961), `restoreToolBaseline` gated by `isAutoMode` (#4966).
-- **Slice + crash recovery** — slice orchestrator state persists across crashes; ancestry-guarded force-reset, detached-HEAD refusal, and stash-by-ref recovery.
-- **Empty-turn recovery** — Claude Code CLI tool-block shape canonicalized so empty-turn recovery matches real provider output.
+- **Global MCP config** — `mcp-client` reads `~/.gsd/mcp.json` for user-level MCP server config.
+- **`ask_user_questions` over MCP** — host elicitation tried before remote channel; multi-select array shape preserved; explicit cancellation handled; remote answers normalized into `structuredContent`.
+- **Model routing overhaul** — cross-provider tier resolution, provider-agnostic profile-tier defaults, disabled-provider routing denylist, resolved tier model IDs normalized, and `findModelForTier` with behavioral tests.
+- **Ollama** — configurable probe/request timeouts via env vars (clamped); cloud / long-variant context windows reported correctly.
+- **Windows fixes** — home directory resolved correctly (#5015), `Path` env lookup repaired, Windows-safe env CLI shims, DEP0190 avoided in Claude CLI binary probes, tool-bootstrap skipped when tools are on PATH.
+- **Anthropic prompt-cache preserved (#5019)** — `pi-coding-agent` and `gsd` no longer thrash the cache on dispatch.
 
-See the full [Changelog](./CHANGELOG.md) for details on every release.
+### Git, GitHub Sync & Reliability
+
+- **Integration-branch self-merge guard (#5024)** — milestone refuses to self-merge when the integration branch equals the milestone branch; self-merge ref guard normalized.
+- **Slice-cadence safety** — integration branch used for slice cadence, dirty worktree state preserved on merge, checked-out slice worktrees advance safely, slice PRs deferred until completion, slice-PR sync stays retryable on failure.
+- **Milestone-ID reservation** — DB rows included in reservation; ghost IDs reused in `nextMilestoneId` to close gaps; `ensurePreconditions` guarded against phantom IDs (#4996); orphan milestone-dir doctor check (#4996); milestone-dir creation deferred until first artifact write.
+- **Auto-commit hygiene** — task commits scoped to reported files, generated commit subjects sanitized, user hooks run on automated commits, milestone-tagged commits bound when `.gsd/` is gitignored (#5033), startup blocked on `git index.lock`.
+- **GitHub sync** — issues no longer closed before delivery, failed task closure / slice PR sync stay retryable, config cache scoped by project, safe git environment used.
+
+### Safety, Recovery & Hardening
+
+- **Policy-block pause through dispatch errors** — pause state is preserved when dispatch errors out mid-policy-block.
+- **Skip-validation persistence** — skip-validation state persists and gate rows are cleared on recover.
+- **Cancelled-gate hard block** — redirected to `ask_user_questions`; false plain-text claim dropped from the message.
+- **Write-gate basePath required** — `process.cwd()` defaults removed; basePath threaded through pre-existing tests.
+- **Atomic metrics writes** — parallel-mode `metrics.json` writes merge atomically; ledger cache invalidated after prune; `saveLedger` aborts when lock not acquired; stale-lock detection adds PID stamp + async yield.
+- **Auto-worktree teardown** — `activeWorkspace` guaranteed cleared on teardown failure; teardown try/finally broadened to cover `chdir`; cleanup steps mirrored on the abort path; warning emitted on resume when persisted worktree is missing.
+- **Empty-turn nudge** — no longer auto-replies to user questions; deferred on mid-line approval prompts.
+- **Refuses project writes from `$HOME`** — and surfaces real SQL errors from `capture_thought` instead of swallowing them.
+
+### VS Code & TUI
+
+- **Checkpoint tree view** — registered in the VS Code extension; checkpoint file existence restored; RPC file-mutation events tracked; agent diff scoped to tracked files.
+- **TUI image paste** — pasted images preserved on regular submit.
+- **Bundled `/gsd` slash command protected** — core handler refuses to overwrite the bundled command.
+
+See the full [Changelog](./CHANGELOG.md) for the complete v2.79 entry and prior releases.
+
+<details>
+<summary>v2.78 highlights</summary>
+
+- **Slice-cadence worktree collapse (#4765)** — `git.collapse_cadence: "milestone" | "slice"` shrinks the orphan window per-slice; pair with `git.milestone_resquash: true` to collapse to one milestone commit
+- **Worktree telemetry (#4764)** — journal events + `summarizeWorktreeTelemetry`; `/gsd forensics` worktree section with `worktree-orphan` and `worktree-unmerged-exit` anomalies
+- **Worktree-aware canonical milestone root (#4761)** — `resolveCanonicalMilestoneRoot` routes validators through the live worktree
+- **Bootstrap orphan audit (#4762)** — in-progress milestones with commits ahead of main are no longer skipped
+- **Unified component system** — skills, agents, pipelines, and marketplace as one component model wired through runtime, dispatch, and telemetry
+- **UnitContextManifest v2 (#4924, #4934)** — typed manifest with declarative tools-policy and typed computed artifacts; CI-guarded
+- **Composer migration phase 3 (#4782)** — `complete-slice`, `research-milestone`, `run-uat`, `reassess-roadmap` build context through the manifest composer
+- **Milestone scope classifier + pipeline variants (#4781)** — auto picks a pipeline variant from milestone shape
+- **Per-unit-type skill manifest resolver (#4779)** — skills wire into specific unit types instead of being globally on
+- **Single-writer-v3 control plane** — durable-state writer gaps closed
+- **Extensions framework** — `gsd extensions install / update / uninstall / list / info / validate`; topological load order; cmux↔gsd decoupling via `cmux-events`; extracted `@gsd-extensions/google-search`
+- **GPT-5.5 Codex support** + `xhigh` thinking level; auth mode in `/model`; permission granularity picker; headless auto default → `bypassPermissions` (#4657)
+- **Major git-safety pass** — TOCTOU ancestry guard, atomic sync-lock with PID-verified stale override, `.git/index.lock` 5-min gate, env overlay strip, rebase/cherry-pick/revert detection, working-tree stash before `reset --hard`, unborn-branch worktree guard, user hooks + `commit.gpgsign` on auto-commits
+- **Atomic `.gsd/` state writes**; **compaction correctness fix (#4665)**; **write-gate hardening (#4950)**; **auto state-machine** non-retriable policy errors (#4973), baseline restoration (#4961, #4966); slice + crash recovery; empty-turn recovery shape canonicalized
+
+</details>
 
 <details>
 <summary>v2.77 highlights</summary>
@@ -320,25 +361,27 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
 
-3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.
+3. **Context Mode** — Context Mode is enabled by default and gives every auto-mode unit guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; full stdout/stderr is saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads `.gsd/last-snapshot.md` after compaction or resume. Opt out with `context_mode.enabled: false`; tune sandbox timeout/output caps with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, and `context_mode.exec_digest_chars`.
+
+4. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.
 
-4. **Crash recovery** — Auto mode persists worker state, unit-dispatch state, and paused-session metadata in the project-root SQLite database. If the session dies, the next `/gsd auto` reconstructs the interrupted unit from DB-backed runtime state, reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator IPC still lives under `.gsd/parallel/`, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
+5. **Crash recovery** — Auto mode persists worker state, unit-dispatch state, and paused-session metadata in the project-root SQLite database. If the session dies, the next `/gsd auto` reconstructs the interrupted unit from DB-backed runtime state, reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator IPC still lives under `.gsd/parallel/`, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
 
-5. **Provider error recovery** — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.
+6. **Provider error recovery** — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.
 
-6. **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.
+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.
 
-7. **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 pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
 
-8. **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.
+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.
 
-9. **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.
+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.
 
-10. **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. 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. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
+12. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
 
-12. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
+13. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
 
 ### `/gsd` and `/gsd next` — Step Mode
 
@@ -616,6 +659,10 @@ auto_report: true
 | `unique_milestone_ids`            | Uses unique milestone names to avoid clashes when working in teams of people                          |
 | `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |
 | `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |
+| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable `gsd_exec`, exec history guidance, and resume snapshots |
+| `context_mode.exec_timeout_ms`    | Timeout for sandboxed `gsd_exec` runs (default: 30000)                                                |
+| `context_mode.exec_stdout_cap_bytes` | Persisted stdout cap for `gsd_exec` output (default: 1048576)                                      |
+| `context_mode.exec_digest_chars`  | Trailing stdout characters returned to the agent context (default: 300)                              |
 | `verification_commands`           | Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
 | `verification_auto_fix`           | Auto-retry on verification failures (default: true)                                                   |
 | `verification_max_retries`        | Max retries for verification failures (default: 2)                                                    |

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

@@ -1 +1 @@
-36cc9805e706289c
+63159c1114dd0d48

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,146 @@
+function now() {
+    return Date.now();
+}
+export class AutoOrchestrator {
+    status = {
+        phase: "idle",
+        transitionCount: 0,
+    };
+    deps;
+    lastAdvanceKey = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async start(_sessionContext) {
+        this.lastAdvanceKey = null;
+        this.status.phase = "running";
+        this.bumpTransition();
+        await this.deps.runtime.journalTransition({ name: "start" });
+        await this.deps.notifications.notifyLifecycle({ name: "start" });
+        return this.advance();
+    }
+    async advance() {
+        try {
+            await this.deps.runtime.ensureLockOwnership();
+            const gate = await this.deps.health.preAdvanceGate();
+            if (!gate.allow) {
+                const blocked = { kind: "blocked", reason: gate.reason ?? "health gate blocked" };
+                await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
+                await this.deps.health.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            const decision = await this.deps.dispatch.decideNextUnit();
+            if (!decision) {
+                const stopped = { kind: "stopped", reason: "no remaining units" };
+                this.status.phase = "stopped";
+                this.status.activeUnit = undefined;
+                this.lastAdvanceKey = null;
+                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" };
+                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;
+            }
+            this.status.activeUnit = { unitType: decision.unitType, unitId: decision.unitId };
+            this.status.phase = "running";
+            this.lastAdvanceKey = nextKey;
+            this.bumpTransition();
+            await this.deps.runtime.journalTransition({
+                name: "advance",
+                reason: decision.reason,
+                unitType: decision.unitType,
+                unitId: decision.unitId,
+            });
+            await this.deps.worktree.prepareForUnit(decision.unitType, decision.unitId);
+            await this.deps.worktree.syncAfterUnit(decision.unitType, decision.unitId);
+            const advanced = { kind: "advanced" };
+            await this.deps.health.postAdvanceRecord(advanced);
+            return advanced;
+        }
+        catch (error) {
+            const recovery = await this.deps.recovery.classifyAndRecover({
+                error,
+                unitType: this.status.activeUnit?.unitType,
+                unitId: this.status.activeUnit?.unitId,
+            });
+            const result = recovery.action === "retry"
+                ? { kind: "paused", reason: recovery.reason }
+                : recovery.action === "escalate"
+                    ? { kind: "error", reason: recovery.reason }
+                    : { kind: "stopped", reason: recovery.reason };
+            if (result.kind === "paused") {
+                this.status.phase = "paused";
+            }
+            else if (result.kind === "stopped") {
+                this.status.phase = "stopped";
+            }
+            else {
+                this.status.phase = "error";
+            }
+            if (result.kind === "stopped") {
+                this.lastAdvanceKey = null;
+                this.status.activeUnit = undefined;
+            }
+            this.bumpTransition();
+            const journalName = result.kind === "paused"
+                ? "advance-paused"
+                : result.kind === "stopped"
+                    ? "advance-stopped"
+                    : "advance-error";
+            await this.deps.runtime.journalTransition({ name: journalName, reason: recovery.reason });
+            if (result.kind === "paused") {
+                await this.deps.notifications.notifyLifecycle({ name: "pause", detail: recovery.reason });
+            }
+            else if (result.kind === "stopped") {
+                await this.deps.notifications.notifyLifecycle({ name: "stopped", detail: recovery.reason });
+            }
+            else if (result.kind === "error") {
+                await this.deps.notifications.notifyLifecycle({ name: "error", detail: recovery.reason });
+            }
+            await this.deps.health.postAdvanceRecord(result);
+            return result;
+        }
+    }
+    async resume() {
+        this.lastAdvanceKey = null;
+        this.status.phase = "running";
+        this.bumpTransition();
+        await this.deps.runtime.journalTransition({ name: "resume" });
+        await this.deps.notifications.notifyLifecycle({ name: "resume" });
+        return this.advance();
+    }
+    async stop(reason) {
+        if (this.status.phase === "stopped") {
+            return { kind: "stopped", reason };
+        }
+        await this.deps.worktree.cleanupOnStop(reason);
+        this.status.phase = "stopped";
+        this.status.activeUnit = undefined;
+        this.lastAdvanceKey = null;
+        this.bumpTransition();
+        await this.deps.runtime.journalTransition({ name: "stop", reason });
+        await this.deps.notifications.notifyLifecycle({ name: "stop", detail: reason });
+        return { kind: "stopped", reason };
+    }
+    getStatus() {
+        return { ...this.status, activeUnit: this.status.activeUnit ? { ...this.status.activeUnit } : undefined };
+    }
+    bumpTransition() {
+        this.status.transitionCount += 1;
+        this.status.lastTransitionAt = now();
+    }
+}
+export function createAutoOrchestrator(deps) {
+    return new AutoOrchestrator(deps);
+}

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

@@ -28,7 +28,7 @@ import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
-import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, refreshOpenDatabaseFromDisk } from "../gsd-db.js";
 import { ensurePlanV2Graph, isEmptyPlanV2GraphResult, isMissingFinalizedContextResult } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
@@ -42,6 +42,13 @@ import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit,
 function isSamePathLocal(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
+function refreshPlanSliceRecoveryDbIfNeeded(unitType) {
+    if (unitType !== "plan-slice")
+        return true;
+    if (!isDbAvailable())
+        return true;
+    return refreshOpenDatabaseFromDisk();
+}
 // ─── Session timeout auto-resume state ────────────────────────────────────────
 let consecutiveSessionTimeouts = 0;
 const MAX_SESSION_TIMEOUT_AUTO_RESUMES = 3;
@@ -145,6 +152,22 @@ async function emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, errorCon
         causedBy: { flowId: ic.flowId, seq: unitStartSeq },
     });
 }
+export function _buildCancelledUnitStopReason(unitType, unitId, errorContext) {
+    const cancellationMessage = errorContext?.message ?? "unknown";
+    const isSessionCreationFailure = errorContext?.category === "session-failed";
+    if (isSessionCreationFailure) {
+        return {
+            notifyMessage: `Session creation failed for ${unitType} ${unitId}: ${cancellationMessage}. Stopping auto-mode.`,
+            stopReason: `Session creation failed: ${cancellationMessage}`,
+            loopReason: "session-failed",
+        };
+    }
+    return {
+        notifyMessage: `Unit ${unitType} ${unitId} aborted after dispatch: ${cancellationMessage}. Stopping auto-mode.`,
+        stopReason: `Unit aborted: ${cancellationMessage}`,
+        loopReason: "unit-aborted",
+    };
+}
 async function failClosedOnFinalizeTimeout(ic, iterData, loopState, stage, startedAt) {
     const { ctx, pi, s, deps } = ic;
     const now = Date.now();
@@ -710,7 +733,10 @@ export async function runDispatch(ic, preData, loopState) {
         // See: https://github.com/gsd-build/gsd-2/issues/2474
         if (dispatchResult.level === "warning") {
             ctx.ui.notify(dispatchResult.reason, "warning");
-            await deps.pauseAuto(ctx, pi);
+            await deps.pauseAuto(ctx, pi, {
+                message: dispatchResult.reason,
+                category: "unknown",
+            });
         }
         else {
             await closeoutAndStop(ctx, pi, s, deps, dispatchResult.reason);
@@ -770,7 +796,13 @@ export async function runDispatch(ic, preData, loopState) {
                         action: "artifact-found",
                     });
                     ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
+                    if (!refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+                        ctx.ui.notify(`Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Keeping stuck state for retry.`, "warning");
+                        return { action: "continue" };
+                    }
                     deps.invalidateAllCaches();
+                    loopState.recentUnits.length = 0;
+                    loopState.stuckRecoveryAttempts = 0;
                     return { action: "continue" };
                 }
                 ctx.ui.notify(`Stuck on ${unitType} ${unitId} (${stuckSignal.reason}). Invalidating caches and retrying.`, "warning");
@@ -778,6 +810,22 @@ export async function runDispatch(ic, preData, loopState) {
             }
             else {
                 // Level 2: hard stop — genuinely stuck
+                deps.invalidateAllCaches();
+                const artifactExists = verifyExpectedArtifact(unitType, unitId, s.basePath);
+                if (artifactExists && unitType !== "complete-milestone") {
+                    debugLog("autoLoop", {
+                        phase: "stuck-recovery",
+                        level: 2,
+                        action: "artifact-found",
+                    });
+                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`, "info");
+                    if (refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+                        loopState.recentUnits.length = 0;
+                        loopState.stuckRecoveryAttempts = 0;
+                        return { action: "continue" };
+                    }
+                    ctx.ui.notify(`Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Stopping for manual recovery.`, "warning");
+                }
                 debugLog("autoLoop", {
                     phase: "stuck-detected",
                     unitType,
@@ -1089,7 +1137,12 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     s.lastGitActionFailure = null;
     s.lastGitActionStatus = null;
     s.lastUnitAgentEndMessages = null;
-    setCurrentPhase(unitType);
+    setCurrentPhase(unitType, {
+        basePath: s.basePath,
+        traceId: ic.flowId,
+        turnId: `iter-${ic.iteration}`,
+        causedBy: "unit-start",
+    });
     s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
     const unitStartSeq = ic.nextSeq();
     deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
@@ -1379,10 +1432,11 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         }
         await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
         await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
-        ctx.ui.notify(`Session creation failed for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Stopping auto-mode.`, "warning");
-        await deps.stopAuto(ctx, pi, `Session creation failed: ${unitResult.errorContext?.message ?? "unknown"}`);
-        debugLog("autoLoop", { phase: "exit", reason: "session-failed" });
-        return { action: "break", reason: "session-failed" };
+        const cancelledStop = _buildCancelledUnitStopReason(unitType, unitId, unitResult.errorContext);
+        ctx.ui.notify(cancelledStop.notifyMessage, "warning");
+        await deps.stopAuto(ctx, pi, cancelledStop.stopReason);
+        debugLog("autoLoop", { phase: "exit", reason: cancelledStop.loopReason });
+        return { action: "break", reason: cancelledStop.loopReason };
     }
     // ── Immediate unit closeout (metrics, activity log, memory) ────────
     // Run right after runUnit() returns so telemetry is never lost to a

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

@@ -148,6 +148,8 @@ export class AutoSession {
     // ── Remote command polling ───────────────────────────────────────────────
     /** Cleanup function returned by startCommandPolling(); null when not running. */
     commandPollingCleanup = null;
+    // ── Orchestration seam ───────────────────────────────────────────────────
+    orchestration = null;
     // ── Loop promise state ──────────────────────────────────────────────────
     // Per-unit resolve function and session-switch guard live at module level
     // in auto-loop.ts (_currentResolve, _sessionSwitchInFlight).
@@ -268,9 +270,12 @@ export class AutoSession {
         this.sigtermHandler = null;
         // Remote command polling — cleanup must be called before reset (auto.ts stopAuto)
         this.commandPollingCleanup = null;
+        // Orchestration seam
+        this.orchestration = null;
         // Loop promise state lives in auto-loop.ts module scope
     }
     toJSON() {
+        const orchestrationStatus = this.orchestration?.getStatus();
         return {
             active: this.active,
             paused: this.paused,
@@ -280,6 +285,9 @@ export class AutoSession {
             activeRunDir: this.activeRunDir,
             currentMilestoneId: this.currentMilestoneId,
             currentUnit: this.currentUnit,
+            orchestrationPhase: orchestrationStatus?.phase,
+            orchestrationTransitionCount: orchestrationStatus?.transitionCount,
+            orchestrationLastTransitionAt: orchestrationStatus?.lastTransitionAt,
             unitDispatchCount: Object.fromEntries(this.unitDispatchCount),
         };
     }

package/dist/resources/extensions/gsd/auto-artifact-paths.js

@@ -128,9 +128,9 @@ export function diagnoseExpectedArtifact(unitType, unitId, base) {
             }
             return `${relSliceFile(base, mid, sid, "RESEARCH")} (slice research)`;
         case "plan-slice":
-            return `${relSliceFile(base, mid, sid, "PLAN")} (slice plan)`;
+            return `${relSliceFile(base, mid, sid, "PLAN")} plus tasks/T##-PLAN.md files (slice plan and task plans)`;
         case "refine-slice":
-            return `${relSliceFile(base, mid, sid, "PLAN")} (refined slice plan from sketch)`;
+            return `${relSliceFile(base, mid, sid, "PLAN")} plus tasks/T##-PLAN.md files (refined slice plan and task plans)`;
         case "execute-task": {
             return `Task ${tid} marked [x] in ${relSliceFile(base, mid, sid, "PLAN")} + summary written`;
         }

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

@@ -559,6 +559,8 @@ export const DISPATCH_RULES = [
             const hasContext = !!(contextFile && (await loadFile(contextFile)));
             if (hasContext)
                 return null; // fall through to next rule
+            if (prefs?.planning_depth === "deep")
+                return null;
             // H6 fix (#4973): keep the non-deep auto-mode bypass, but do not
             // pre-verify deep planning's user-facing milestone approval gate.
             if (shouldBypassMilestoneDepthGateInAuto(prefs)) {