gsd-pi 2.81.0 → 2.82.0-dev.2841a1e44

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -8,9 +8,13 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
-import { loadFile } from "./files.js";
-import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
-import { mergeMilestoneToMain } from "./auto-worktree.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { getAutoWorktreePath } from "./auto-worktree.js";
+import { buildWorktreeLifecycleDeps } from "./auto.js";
+import {
+  mergeMilestoneStandalone,
+  type MergeStandaloneResult,
+} from "./worktree-lifecycle.js";
 import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
 import type { WorkerInfo } from "./parallel-orchestrator.js";
@@ -136,44 +140,46 @@ export function determineMergeOrder(
 
 /**
  * Attempt to merge a single milestone's worktree back to main.
- * Wraps mergeMilestoneToMain with error handling for parallel context.
+ *
+ * Routes through `WorktreeLifecycle.mergeMilestoneStandalone` so parallel
+ * callers get the same projection-finalize / roadmap-fallback / secondary-
+ * teardown invariants as the single-loop path. Closes the parallel-merge
+ * bypass that ADR-016 names (issue #5618).
  */
 export async function mergeCompletedMilestone(
   basePath: string,
   milestoneId: string,
 ): Promise<MergeResult> {
-  try {
-    // Load the roadmap content (needed by mergeMilestoneToMain)
-    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    if (!roadmapPath) {
-      return {
-        milestoneId,
-        success: false,
-        error: `No roadmap found for ${milestoneId}`,
-      };
-    }
-
-    const roadmapContent = await loadFile(roadmapPath);
-    if (!roadmapContent) {
-      return {
-        milestoneId,
-        success: false,
-        error: `Could not read roadmap for ${milestoneId}`,
-      };
-    }
+  // Resolve the worktree path explicitly; parallel-merge has no AutoSession
+  // to read it from. Only use the worktree path when git actually knows
+  // about it (`getAutoWorktreePath` returns non-null). When the directory
+  // exists on disk but isn't a registered git worktree (e.g. a stale
+  // session-status marker dir), fall back to the project root and let the
+  // standalone's mode detection pick branch-mode or skipped — using the
+  // un-registered dir as `worktreeBasePath` would cause `getCurrentBranch`
+  // to fail with a "Worktree HEAD diverged" error.
+  const registeredWtPath = getAutoWorktreePath(basePath, milestoneId);
+  const worktreeBasePath = registeredWtPath ?? basePath;
 
-    // Attempt the merge
-    const result = mergeMilestoneToMain(basePath, milestoneId, roadmapContent);
-
-    // Clean up parallel session status
-    removeSessionStatus(basePath, milestoneId);
-
-    return {
+  let result: MergeStandaloneResult;
+  try {
+    result = mergeMilestoneStandalone(buildWorktreeLifecycleDeps(), {
+      originalBasePath: basePath,
+      worktreeBasePath,
       milestoneId,
-      success: true,
-      commitMessage: result.commitMessage,
-      pushed: result.pushed,
-    };
+      // Parallel context never runs with degraded isolation — workers only
+      // exist when isolation succeeded. Pass `false` explicitly so the
+      // standalone's degraded-skip branch is not reached.
+      isolationDegraded: false,
+      notify: (msg, level) => {
+        // Surface user-visible messages from the standalone through the
+        // workflow logger so the parallel merge's progress is visible in
+        // the same channel as the rest of the parallel orchestration.
+        if (level === "error" || level === "warning") {
+          logWarning("parallel", `${milestoneId}: ${msg}`);
+        }
+      },
+    });
   } catch (err) {
     if (err instanceof MergeConflictError) {
       return {
@@ -189,6 +195,27 @@ export async function mergeCompletedMilestone(
       error: getErrorMessage(err),
     };
   }
+
+  if (!result.merged) {
+    return {
+      milestoneId,
+      success: false,
+      error:
+        result.mode === "skipped"
+          ? `Merge skipped for ${milestoneId} (mode=none or isolation degraded).`
+          : `No roadmap for ${milestoneId} — milestone branch preserved for manual merge.`,
+    };
+  }
+
+  // Clean up parallel session status — only on a real merge.
+  removeSessionStatus(basePath, milestoneId);
+
+  return {
+    milestoneId,
+    success: true,
+    commitMessage: result.commitMessage,
+    pushed: result.pushed,
+  };
 }
 
 /**

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -1,23 +1,23 @@
-/**
- * GSD Parallel Monitor Overlay
- *
- * Full-screen TUI overlay showing real-time parallel worker progress.
- * Opened via `/gsd parallel watch`, Ctrl+Alt+P (⌃⌥P on macOS),
- * or Ctrl+Shift+P fallback.
- * Reads the same data sources as `scripts/parallel-monitor.mjs` but
- * renders as a native pi-tui overlay with theme integration.
- */
+// Project/App: GSD-2
+// File Purpose: Parallel worker monitor overlay with width-safe operations-console rendering.
 
 import { existsSync, statSync, readFileSync, openSync, readSync, closeSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 
 import type { Theme } from "@gsd/pi-coding-agent";
-import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
+import { matchesKey, Key } from "@gsd/pi-tui";
 
-import { formatDuration, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
+import { formatDuration } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
+import {
+  renderBar,
+  renderKeyHints,
+  renderProgressBar,
+  safeLine,
+  statusGlyph,
+} from "./tui/render-kit.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -277,17 +277,6 @@ function unitTypeLabel(unitType: string | null): string {
   return labels[unitType || ""] || (unitType || "---").toUpperCase().slice(0, 5);
 }
 
-function progressBar(done: number, total: number, width: number): string {
-  if (total === 0) return "░".repeat(width);
-  const filled = Math.round((done / total) * width);
-  return "█".repeat(filled) + "░".repeat(width - filled);
-}
-
-function healthGlyph(alive: boolean, heartbeatAge: number): string {
-  if (!alive) return "○";
-  return "●";
-}
-
 // ─── Overlay Class ────────────────────────────────────────────────────────
 
 export class ParallelMonitorOverlay {
@@ -299,6 +288,7 @@ export class ParallelMonitorOverlay {
   private workers: WorkerView[] = [];
   private events: string[] = [];
   private cachedLines?: string[];
+  private cachedWidth?: number;
   private scrollOffset = 0;
   private disposed = false;
   private resizeHandler: (() => void) | null = null;
@@ -339,6 +329,7 @@ export class ParallelMonitorOverlay {
     this.events = this.events.slice(-10);
 
     this.cachedLines = undefined;
+    this.cachedWidth = undefined;
     this.tui.requestRender();
   }
 
@@ -378,14 +369,15 @@ export class ParallelMonitorOverlay {
 
   invalidate(): void {
     this.cachedLines = undefined;
+    this.cachedWidth = undefined;
   }
 
   render(width: number): string[] {
-    if (this.cachedLines) return this.cachedLines;
+    if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
 
     const t = this.theme;
     const lines: string[] = [];
-    const w = Math.max(width, 60);
+    const w = Math.max(1, width);
 
     // Header
     const totalCost = this.workers.reduce((s, wk) => s + wk.cost, 0);
@@ -398,7 +390,7 @@ export class ParallelMonitorOverlay {
       t.bold(`$${totalCost.toFixed(2)}`) +
       t.fg("muted", "  │  5s refresh"),
     );
-    lines.push(t.fg("muted", "─".repeat(w)));
+    lines.push(renderBar(t, w));
 
     if (this.workers.length === 0) {
       lines.push("");
@@ -410,7 +402,7 @@ export class ParallelMonitorOverlay {
 
         // Health + ID + state
         const healthColor = wk.alive ? "success" : "error";
-        const glyph = healthGlyph(wk.alive, wk.heartbeatAge);
+        const glyph = statusGlyph(t, wk.alive ? "active" : "idle");
         const stateText = wk.alive
           ? t.fg("success", "RUNNING")
           : t.fg("error", t.bold("DEAD"));
@@ -452,25 +444,29 @@ export class ParallelMonitorOverlay {
           lines.push(`     ${t.fg("muted", "slices")}  ${chips.join("  ")}`);
 
           // Task progress bar
-          const bar = progressBar(wk.doneTasks, wk.totalTasks, 25);
+          const barWidth = Math.max(6, Math.min(25, w - 32));
+          const bar = renderProgressBar(t, wk.doneTasks, wk.totalTasks, barWidth, {
+            filledChar: "█",
+            emptyChar: "░",
+            emptyColor: "dim",
+          });
           const pct = wk.totalTasks > 0 ? Math.round((wk.doneTasks / wk.totalTasks) * 100) : 0;
           lines.push(
-            `     ${t.fg("muted", "tasks")}   ${t.fg("success", bar)}  ${wk.doneTasks}/${wk.totalTasks} ` +
+            `     ${t.fg("muted", "tasks")}   ${bar}  ${wk.doneTasks}/${wk.totalTasks} ` +
             t.fg("muted", `(${pct}%)  │  slices done ${wk.doneSlices}/${wk.totalSlices}`),
           );
         }
 
         // Errors
         for (const err of wk.errors.slice(-2)) {
-          const truncated = err.length > w - 10 ? err.slice(0, w - 11) + "…" : err;
-          lines.push(`     ${t.fg("error", "⚠ " + truncated)}`);
+          lines.push(`     ${t.fg("error", "! " + err)}`);
         }
       }
     }
 
     // Event feed
     lines.push("");
-    lines.push(t.fg("muted", "─".repeat(w)));
+    lines.push(renderBar(t, w));
     lines.push(`  ${t.bold("Recent Events")}`);
 
     if (this.events.length === 0) {
@@ -478,8 +474,7 @@ export class ParallelMonitorOverlay {
     } else {
       for (const evt of this.events.slice(-8)) {
         const mid = evt.match(/^✓ (M\d+)\//)?.[1] || "";
-        const truncated = evt.length > w - 10 ? evt.slice(0, w - 11) + "…" : evt;
-        lines.push(`  ${t.fg("muted", "│")} ${t.fg("accent", mid)} ${truncated.replace(/^✓ M\d+\//, "")}`);
+        lines.push(`  ${t.fg("muted", "│")} ${t.fg("accent", mid)} ${evt.replace(/^✓ M\d+\//, "")}`);
       }
     }
 
@@ -496,14 +491,17 @@ export class ParallelMonitorOverlay {
       }
       lines.push(`  ${t.bold("Total: $" + this.workers.reduce((s, wk) => s + wk.cost, 0).toFixed(2))}`);
     }
-    lines.push(t.fg("muted", `  ESC/q/${formattedShortcutPair("parallel")} close  │  ↑↓ scroll`));
+    lines.push(renderKeyHints(t, [`ESC/q/${formattedShortcutPair("parallel")} close`, "↑↓ scroll"], w));
 
     // Apply scroll — use terminal rows as height estimate
     const termHeight = process.stdout.rows || 40;
     const maxScroll = Math.max(0, lines.length - termHeight);
     this.scrollOffset = Math.min(Math.max(this.scrollOffset, 0), maxScroll);
-    const visible = lines.slice(this.scrollOffset, this.scrollOffset + termHeight);
+    const visible = lines
+      .slice(this.scrollOffset, this.scrollOffset + termHeight)
+      .map((line) => safeLine(line, w));
     this.cachedLines = visible;
+    this.cachedWidth = width;
     return visible;
   }
 }

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -22,22 +22,24 @@ Use `subagent` only for fresh-context review when useful: reviewer for cross-cut
 
 1. Use the inlined Slice Summary and UAT templates.
 2. {{skillActivation}}
-3. Run all slice-level verification checks from the slice plan. Fix failures before marking done; refresh current state if needed.
-4. Task summaries use a flat file layout under `tasks/` such as `T01-SUMMARY.md`, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. Never use `tasks/*/SUMMARY.md`.
-5. If observability/diagnostics were planned, verify them unless the slice is simple.
-6. Address every gate in Gates to Close. Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, monitoring gaps. Empty sections are recorded as omitted.
-7. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
-8. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
-9. Draft concrete UAT with preconditions, numbered steps, expected outcomes, edge cases, UAT Type, and Not Proven By This UAT.
-10. Review the inlined task-summary excerpts for DECISIONS.md and KNOWLEDGE.md-worthy decisions, patterns, and gotchas. Read full `*-SUMMARY.md` files only when an excerpt is absent, truncated, or lacks the specific evidence needed for the slice narrative. Capture significant items with `capture_thought`; do not append knowledge files directly.
-11. Call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes; the tool renders files and updates projections.
-12. Do not run git commands.
-13. Update `.gsd/PROJECT.md` with a full `write` only if the current project state needs refresh.
+3. Run all slice-level verification checks from the slice plan through the closeout-safe verification surface (`gsd_exec` / Context Mode verification evidence); refresh current state if needed. Do not use direct `bash` for verification commands.
+4. Complete the slice only when every required verification check passes. If verification fails or the fix requires source changes, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
+5. For task-specific failures, call `gsd_task_reopen` with the failing completed task and a concrete reason so execution can redo the work. For plan-invalidating failures, call `gsd_replan_slice` with the blocker and updated execution tasks. Then stop with: "Slice {{sliceId}} needs execution follow-up."
+6. Task summaries use a flat file layout under `tasks/` such as `T01-SUMMARY.md`, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. Never use `tasks/*/SUMMARY.md`.
+7. If observability/diagnostics were planned, verify them unless the slice is simple.
+8. Address every gate in Gates to Close. Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, monitoring gaps. Empty sections are recorded as omitted.
+9. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
+10. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
+11. Draft concrete UAT with preconditions, numbered steps, expected outcomes, edge cases, UAT Type, and Not Proven By This UAT.
+12. Review the inlined task-summary excerpts for DECISIONS.md and KNOWLEDGE.md-worthy decisions, patterns, and gotchas. Read full `*-SUMMARY.md` files only when an excerpt is absent, truncated, or lacks the specific evidence needed for the slice narrative. Capture significant items with `capture_thought`; do not append knowledge files directly.
+13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes; the tool renders files and updates projections.
+14. Do not run git commands.
+15. Update `.gsd/PROJECT.md` with a full `write` only if the current project state needs refresh.
 
 **Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
 
 **File system safety:** if re-reading task summaries, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` or `ls .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks/*-SUMMARY.md`. Never pass `{{slicePath}}` or any directory path directly to the `read` tool.
 
-**You MUST call `gsd_slice_complete` with summary and UAT content before finishing.**
+**You MUST call `gsd_slice_complete` with summary and UAT content before finishing only after verification passes.**
 
 When done, say: "Slice {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/discuss-headless.md

@@ -129,7 +129,16 @@ If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missin
 
 Do not announce the ready phrase as something you are "about to" do. The ready phrase is a post-write signal, not an intent signal.
 
-After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+After completing steps 1–7 above, end with this concise user-facing handoff:
+
+```
+Milestone {{milestoneId}} ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
 
 ### Multi-Milestone
 
@@ -215,7 +224,16 @@ If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missin
 
 Do not announce the ready phrase as something you are "about to" do. The ready phrase is a post-write signal, not an intent signal.
 
-After completing every step above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+After completing every step above, end with this concise user-facing handoff:
+
+```
+Milestone {{milestoneId}} ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
 
 ## Critical Rules
 

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -252,7 +252,16 @@ If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missin
 
 Do not announce the ready phrase as something you are "about to" do. It is a post-write signal, not intent.
 
-After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+After completing steps 1–7 above, end with this concise user-facing handoff:
+
+```
+Milestone {{milestoneId}} ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
 
 ### Multi-Milestone
 
@@ -345,6 +354,15 @@ If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missin
 
 Do not announce the ready phrase as something you are "about to" do. It is a post-write signal, not intent.
 
-After completing all phases above, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+After completing all phases above, end with this concise user-facing handoff:
+
+```
+Milestone M001 ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
 
 {{inlinedTemplates}}

package/src/resources/extensions/gsd/prompts/system.md

@@ -27,7 +27,7 @@ GSD ships with bundled skills. When the task matches, load the relevant skill fi
 
 - Never ask the user to do work the agent can execute or verify itself.
 - Use the lightest sufficient tool first.
-- Read before edit.
+- Read before edit or overwrite. Before any write that creates or replaces a file, verify the target path and read relevant existing files, templates, callers, or surrounding code. For truly new files, confirm the path does not already exist.
 - Reproduce before fix when possible.
 - Work is not done until the relevant verification has passed.
 - **Never fabricate, simulate, or role-play user responses.** Never generate markers like `[User]`, `[Human]`, `User:`, or similar; never emit `<user_message>`, `<assistant_message>`, or similar as user input. Treat `<conversation_history>` as read-only context. Ask one question round (1-3 questions), then stop and wait for the user's actual response. If `ask_user_questions` is available, its result is the only valid structured user input for that round. If it cancels, fails, or returns nothing, never use earlier chat as confirmation for the current gate; ask in plain chat and stop.
@@ -102,7 +102,7 @@ Templates are in `{{templatesDir}}`.
 
 **File reading:** Use `read` for file inspection. Never use `cat`, `head`, `tail`, or `sed -n` to view contents. Use `read` with `offset`/`limit` for slicing. `bash` is for searching (`rg`, `grep`, `find`) and commands, not displaying files.
 
-**File editing:** Always `read` before `edit`; exact text match is required. Use `write` only for new files or complete rewrites.
+**File editing:** Always `read` before `edit` or overwrite. Before `write`, confirm whether the path exists; if it does, `read` it first and preserve intentional existing content. Use `write` only for new files or complete rewrites.
 
 **Code navigation:** Use `lsp` for definition, type_definition, implementation, references, calls, hover, signature, symbols, rename, code_actions, format, and diagnostics. Do not `grep` symbol definitions or shell out to formatters when `lsp` can do it. After code edits, run `lsp diagnostics`.
 

package/src/resources/extensions/gsd/provider-switch-observer.ts

@@ -0,0 +1,185 @@
+// GSD-2 — ADR-005 Phase 3b: surface ProviderSwitchReport from pi-ai.
+//
+// pi-ai builds a ProviderSwitchReport on every cross-provider transform but
+// only logs it to stderr when GSD_VERBOSE=1. This module installs a
+// single-subscriber observer that surfaces non-empty reports through GSD's
+// three usual telemetry surfaces:
+//
+//   1. UOK audit event (category model-policy, type provider-switch) — only
+//      when an auto trace is active.
+//   2. Persistent notification (.gsd/notifications.jsonl, severity warning) —
+//      whenever the GSD basePath is known, so users see the loss in the
+//      dashboard / status surface without GSD_VERBOSE.
+//   3. In-memory counter, exposed via getProviderSwitchStats() so any
+//      caller (dashboard, doctor, tests) can read the rollup.
+
+import { setProviderSwitchObserver, type ProviderSwitchReport } from "@gsd/pi-ai";
+
+import { autoSession } from "./auto-runtime-state.js";
+import { appendNotification } from "./notification-store.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+
+/** Rollup of cross-provider context transformations, grouped by trace. */
+export interface ProviderSwitchStats {
+  /** Total non-empty reports observed since process start (or last reset). */
+  totalSwitches: number;
+  /** Sum of every counted transformation across all reports. */
+  totals: {
+    thinkingBlocksDropped: number;
+    thinkingBlocksDowngraded: number;
+    toolCallIdsRemapped: number;
+    syntheticToolResultsInserted: number;
+    thoughtSignaturesDropped: number;
+  };
+  /** Per-trace breakdown. Key "interactive" covers reports outside auto-mode. */
+  byTrace: Record<string, TraceSwitchStats>;
+  /** The most recent non-empty report, if any. */
+  lastReport: ProviderSwitchReport | null;
+  /** ISO timestamp of the most recent non-empty report, if any. */
+  lastAt: string | null;
+}
+
+export interface TraceSwitchStats {
+  switches: number;
+  lastReport: ProviderSwitchReport;
+  lastAt: string;
+}
+
+const INTERACTIVE_TRACE_KEY = "interactive";
+
+interface MutableTraceStats {
+  switches: number;
+  lastReport: ProviderSwitchReport;
+  lastAt: string;
+}
+
+let installed = false;
+let totalSwitches = 0;
+const totals = {
+  thinkingBlocksDropped: 0,
+  thinkingBlocksDowngraded: 0,
+  toolCallIdsRemapped: 0,
+  syntheticToolResultsInserted: 0,
+  thoughtSignaturesDropped: 0,
+};
+const byTrace = new Map<string, MutableTraceStats>();
+let lastReport: ProviderSwitchReport | null = null;
+let lastAt: string | null = null;
+
+/** Format a one-line summary suitable for a notification message. */
+function summarize(report: ProviderSwitchReport): string {
+  const parts: string[] = [];
+  if (report.thinkingBlocksDropped > 0) parts.push(`${report.thinkingBlocksDropped} thinking dropped`);
+  if (report.thinkingBlocksDowngraded > 0) parts.push(`${report.thinkingBlocksDowngraded} thinking downgraded`);
+  if (report.toolCallIdsRemapped > 0) parts.push(`${report.toolCallIdsRemapped} tool ids remapped`);
+  if (report.syntheticToolResultsInserted > 0) parts.push(`${report.syntheticToolResultsInserted} synthetic tool results`);
+  if (report.thoughtSignaturesDropped > 0) parts.push(`${report.thoughtSignaturesDropped} thought signatures dropped`);
+  return `Provider switch ${report.fromApi} → ${report.toApi}: ${parts.join(", ")}`;
+}
+
+function recordReport(report: ProviderSwitchReport): void {
+  const now = new Date().toISOString();
+  totalSwitches += 1;
+  totals.thinkingBlocksDropped += report.thinkingBlocksDropped;
+  totals.thinkingBlocksDowngraded += report.thinkingBlocksDowngraded;
+  totals.toolCallIdsRemapped += report.toolCallIdsRemapped;
+  totals.syntheticToolResultsInserted += report.syntheticToolResultsInserted;
+  totals.thoughtSignaturesDropped += report.thoughtSignaturesDropped;
+  lastReport = report;
+  lastAt = now;
+
+  const traceKey = autoSession.currentTraceId ?? INTERACTIVE_TRACE_KEY;
+  const existing = byTrace.get(traceKey);
+  if (existing) {
+    existing.switches += 1;
+    existing.lastReport = report;
+    existing.lastAt = now;
+  } else {
+    byTrace.set(traceKey, { switches: 1, lastReport: report, lastAt: now });
+  }
+}
+
+function emitAudit(report: ProviderSwitchReport): void {
+  const traceId = autoSession.currentTraceId;
+  const basePath = autoSession.basePath;
+  if (!traceId || !basePath) return;
+  try {
+    emitUokAuditEvent(
+      basePath,
+      buildAuditEnvelope({
+        traceId,
+        category: "model-policy",
+        type: "provider-switch",
+        payload: {
+          fromApi: report.fromApi,
+          toApi: report.toApi,
+          thinkingBlocksDropped: report.thinkingBlocksDropped,
+          thinkingBlocksDowngraded: report.thinkingBlocksDowngraded,
+          toolCallIdsRemapped: report.toolCallIdsRemapped,
+          syntheticToolResultsInserted: report.syntheticToolResultsInserted,
+          thoughtSignaturesDropped: report.thoughtSignaturesDropped,
+        },
+      }),
+    );
+  } catch {
+    // Audit emission is best-effort. Counter + notification still fire.
+  }
+}
+
+function emitNotification(report: ProviderSwitchReport): void {
+  try {
+    appendNotification(summarize(report), "warning", "workflow-logger");
+  } catch {
+    // Notification persistence is best-effort.
+  }
+}
+
+function handleReport(report: ProviderSwitchReport): void {
+  recordReport(report);
+  emitAudit(report);
+  emitNotification(report);
+}
+
+/**
+ * Install the pi-ai observer. Idempotent — calling more than once is a no-op
+ * after the first install.
+ */
+export function installProviderSwitchObserver(): void {
+  if (installed) return;
+  setProviderSwitchObserver(handleReport);
+  installed = true;
+}
+
+/** Uninstall the observer. Intended for tests. */
+export function uninstallProviderSwitchObserver(): void {
+  setProviderSwitchObserver(undefined);
+  installed = false;
+}
+
+/** Read-only snapshot of the in-memory rollup. */
+export function getProviderSwitchStats(): ProviderSwitchStats {
+  const trace: Record<string, TraceSwitchStats> = {};
+  for (const [key, value] of byTrace) {
+    trace[key] = { switches: value.switches, lastReport: { ...value.lastReport }, lastAt: value.lastAt };
+  }
+  return {
+    totalSwitches,
+    totals: { ...totals },
+    byTrace: trace,
+    lastReport: lastReport ? { ...lastReport } : null,
+    lastAt,
+  };
+}
+
+/** Reset the in-memory rollup. Intended for tests. */
+export function _resetProviderSwitchStats(): void {
+  totalSwitches = 0;
+  totals.thinkingBlocksDropped = 0;
+  totals.thinkingBlocksDowngraded = 0;
+  totals.toolCallIdsRemapped = 0;
+  totals.syntheticToolResultsInserted = 0;
+  totals.thoughtSignaturesDropped = 0;
+  byTrace.clear();
+  lastReport = null;
+  lastAt = null;
+}

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -2,6 +2,7 @@
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
 
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
+import { ReconciliationFailedError } from "./state-reconciliation.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
@@ -9,6 +10,7 @@ export type RecoveryFailureKind =
   | "stale-worker"
   | "worktree-invalid"
   | "verification-drift"
+  | "reconciliation-drift"
   | "provider"
   | "runtime-unknown";
 
@@ -33,7 +35,13 @@ export interface RecoveryClassification {
 
 export function classifyFailure(input: RecoveryClassificationInput): RecoveryClassification {
   const message = errorMessage(input.error);
-  const failureKind = input.failureKind ?? inferFailureKind(message);
+  // ADR-017: ReconciliationFailedError is a typed throw from the State
+  // Reconciliation Module. Recognize it by class regardless of caller-supplied
+  // failureKind so the taxonomy stays consistent.
+  const failureKind =
+    input.error instanceof ReconciliationFailedError
+      ? "reconciliation-drift"
+      : input.failureKind ?? inferFailureKind(message);
 
   switch (failureKind) {
     case "tool-schema":
@@ -76,6 +84,15 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
         exitReason: "verification-drift",
         remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
       };
+    case "reconciliation-drift":
+      return {
+        failureKind,
+        action: "escalate",
+        reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
+        exitReason: "reconciliation-drift",
+        remediation:
+          "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
+      };
     case "provider": {
       const providerClass = classifyError(message, input.retryAfterMs);
       return {