gsd-pi 2.81.0-dev.72a81bdf3 → 2.82.0-dev.20138ae42

package/src/resources/extensions/gsd/prompts/rewrite-docs.md

@@ -23,7 +23,7 @@ An override was issued by the user that changes a fundamental decision or approa
    - For DECISIONS.md: append a new decision entry documenting the override and why. Do NOT delete prior decisions — mark them as superseded with a note.
    - For slice plans (S##-PLAN.md): update Goal, Demo, and Verification sections if affected. Update Files Likely Touched if the override changes scope. Do NOT modify completed task entries.
    - For REQUIREMENTS.md: update requirement descriptions if the override changes what "done" means, but do not remove requirements.
-   - For PROJECT.md: update if the override changes project-level facts.
+   - For PROJECT.md: do not edit the projection directly. If the override changes project-level facts, persist the revised Project content through `gsd_summary_save` with `artifact_type: "PROJECT"` so the DB remains authoritative.
    - Milestone context files are reference only — do not modify them.
 4. Mark all active overrides as resolved: change `**Scope:** active` to `**Scope:** resolved` in `{{overridesPath}}`
 5. Do not commit manually — the system auto-commits your changes after this unit completes.

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/smart-entry-routing.ts

@@ -0,0 +1,77 @@
+// GSD-2 — Smart entry routing decisions.
+// Pure route selection for /gsd guided wizard choices.
+
+export type SmartEntryIsolationMode = "worktree" | "branch" | "none";
+
+export type ActiveTaskChoice =
+  | "execute"
+  | "auto"
+  | "status"
+  | "milestone_actions";
+
+export type ActiveTaskRoute =
+  | {
+      kind: "auto-bootstrap";
+      verboseMode: false;
+      options?: {
+        step?: true;
+        milestoneLock?: string;
+      };
+    }
+  | {
+      kind: "guided-dispatch";
+      unitType: "execute-task";
+    }
+  | {
+      kind: "status";
+    }
+  | {
+      kind: "milestone-actions";
+    };
+
+export function resolveGuidedExecuteLaunchMode(
+  isolationMode: SmartEntryIsolationMode,
+): "auto-step" | "guided-dispatch" {
+  return isolationMode === "worktree" ? "auto-step" : "guided-dispatch";
+}
+
+export function resolveActiveTaskChoiceRoute(input: {
+  choice: ActiveTaskChoice;
+  isolationMode: SmartEntryIsolationMode;
+  milestoneId: string;
+}): ActiveTaskRoute {
+  if (input.choice === "auto") {
+    return {
+      kind: "auto-bootstrap",
+      verboseMode: false,
+    };
+  }
+
+  if (input.choice === "execute") {
+    if (resolveGuidedExecuteLaunchMode(input.isolationMode) === "auto-step") {
+      return {
+        kind: "auto-bootstrap",
+        verboseMode: false,
+        options: {
+          step: true,
+          milestoneLock: input.milestoneId,
+        },
+      };
+    }
+
+    return {
+      kind: "guided-dispatch",
+      unitType: "execute-task",
+    };
+  }
+
+  if (input.choice === "status") {
+    return { kind: "status" };
+  }
+
+  if (input.choice === "milestone_actions") {
+    return { kind: "milestone-actions" };
+  }
+
+  throw new Error(`Invalid ActiveTaskChoice: ${input.choice}`);
+}

package/src/resources/extensions/gsd/state-reconciliation/drift/merge-state.ts

@@ -23,6 +23,7 @@ import {
 } from "../../native-git-bridge.js";
 import type { GSDState } from "../../types.js";
 import { logError, logWarning } from "../../workflow-logger.js";
+import { isGsdWorktreePath } from "../../worktree-root.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
 export type MergeReconcileResult = "clean" | "reconciled" | "blocked";
@@ -46,7 +47,13 @@ function resolveGitDir(basePath: string): string {
       return isAbsolute(gitDir) ? gitDir : resolve(basePath, gitDir);
     }
   } catch (err) {
-    logWarning("recovery", `gitdir resolution failed: ${getErrorMessage(err)}`);
+    const message = getErrorMessage(err);
+    logWarning("recovery", `gitdir resolution failed: ${message}`);
+    if (isGsdWorktreePath(basePath)) {
+      throw new Error(
+        `Worktree integrity failure: ${basePath} is not a valid git worktree (git rev-parse failed: ${message.split("\n")[0]}). Repair or recreate the worktree before retrying.`,
+      );
+    }
   }
 
   return join(basePath, ".git");

package/src/resources/extensions/gsd/state-reconciliation/drift/project-md.ts

@@ -1,14 +1,13 @@
 // Project/App: GSD-2
 // File Purpose: ADR-017 unregistered-milestone drift handler. Detects
 // milestones whose on-disk directory has meaningful content (ROADMAP/
-// CONTEXT/SUMMARY) but no DB row, then runs the markdown importer to
-// reconcile. PROJECT.md is the human-facing index — the importer's source
-// of truth is the .gsd/milestones/ directory tree.
+// CONTEXT/SUMMARY) but no DB row, then fails closed with an explicit recovery
+// instruction. Markdown hierarchy import is reserved for operator-controlled
+// migration/recovery commands, not automatic runtime reconciliation.
 
 import { existsSync } from "node:fs";
 
 import { getMilestone, isDbAvailable } from "../../gsd-db.js";
-import { migrateHierarchyToDb } from "../../md-importer.js";
 import { findMilestoneIds } from "../../milestone-ids.js";
 import { resolveMilestoneFile } from "../../paths.js";
 import type { GSDState } from "../../types.js";
@@ -46,20 +45,18 @@ export function detectUnregisteredMilestoneDrift(
 }
 
 /**
- * Repair: invoke the markdown importer. migrateHierarchyToDb walks the same
- * findMilestoneIds list the detector uses and INSERTs OR IGNOREs every
- * missing milestone (and its slices/tasks) — idempotent under cap=2 retry.
- *
- * Note: even though we receive one record at a time, the importer is a
- * project-wide operation. Repeated invocation across multiple drift records
- * in the same pass is wasteful but safe; a future optimization could
- * coalesce by checking whether the importer has already run this pass.
+ * Repair intentionally fails closed. The project-root DB is authoritative at
+ * runtime; markdown-only milestones must be imported through an explicit
+ * migration/recovery command so operators opt into changing canonical state.
  */
 export function repairUnregisteredMilestone(
-  _record: UnregisteredMilestoneDrift,
-  ctx: DriftContext,
+  record: UnregisteredMilestoneDrift,
+  _ctx: DriftContext,
 ): void {
-  migrateHierarchyToDb(ctx.basePath);
+  throw new Error(
+    `Milestone ${record.milestoneId} exists only as markdown projection. ` +
+      "Runtime reconciliation will not import markdown into the authoritative DB; run explicit GSD recovery/migration if this markdown should repopulate the database.",
+  );
 }
 
 export const unregisteredMilestoneHandler: DriftHandler<UnregisteredMilestoneDrift> = {

package/src/resources/extensions/gsd/state-reconciliation/drift/roadmap.ts

@@ -1,8 +1,8 @@
 // Project/App: GSD-2
 // File Purpose: ADR-017 roadmap-divergence drift handler. Detects mismatches
-// between ROADMAP.md (parsed slice sequence + depends declarations) and the
-// DB slice rows for that milestone, then reconciles via the markdown
-// importer plus an explicit junction-table sync.
+// between ROADMAP.md (parsed slice sequence, depends declarations, and
+// checkboxes) and the DB slice rows for that milestone, then re-renders the
+// ROADMAP projection from the authoritative DB rows.
 
 import { existsSync, readFileSync } from "node:fs";
 
@@ -10,12 +10,12 @@ import {
   getMilestone,
   getMilestoneSlices,
   isDbAvailable,
-  syncSliceDependencies,
 } from "../../gsd-db.js";
-import { migrateHierarchyToDb } from "../../md-importer.js";
+import { renderRoadmapFromDb } from "../../markdown-renderer.js";
 import { findMilestoneIds } from "../../milestone-ids.js";
 import { parseRoadmap } from "../../parsers-legacy.js";
 import { resolveMilestoneFile } from "../../paths.js";
+import { isClosedStatus } from "../../status-guards.js";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
@@ -46,14 +46,20 @@ function milestoneHasDivergence(
 
   const dbSlices = getMilestoneSlices(milestoneId);
   const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+  const roadmapSliceIds = new Set<string>();
 
   for (let i = 0; i < roadmap.slices.length; i++) {
     const roadmapSlice = roadmap.slices[i]!;
+    roadmapSliceIds.add(roadmapSlice.id);
     const expectedSequence = i + 1;
     const dbSlice = dbSliceMap.get(roadmapSlice.id);
     if (!dbSlice) return true; // Roadmap has a slice the DB doesn't.
     if (dbSlice.sequence !== expectedSequence) return true;
     if (!arraysEqual(dbSlice.depends, roadmapSlice.depends)) return true;
+    if (isClosedStatus(dbSlice.status) !== roadmapSlice.done) return true;
+  }
+  for (const dbSlice of dbSlices) {
+    if (!roadmapSliceIds.has(dbSlice.id)) return true;
   }
   return false;
 }
@@ -77,29 +83,15 @@ export function detectRoadmapDivergenceDrift(
 }
 
 /**
- * Repair a milestone's roadmap divergence:
- *   1. migrateHierarchyToDb upserts slice rows (sequence + depends JSON
- *      update via ON CONFLICT DO UPDATE).
- *   2. syncSliceDependencies updates the junction table per slice — the
- *      importer only writes the JSON column, not the relational view.
+ * Repair a milestone's roadmap divergence by regenerating the projection from
+ * DB rows. ROADMAP.md is a projection; runtime reconciliation must not import
+ * slice presence, sequence, dependencies, or checkbox state from markdown.
  */
-export function repairRoadmapDivergence(
+export async function repairRoadmapDivergence(
   record: RoadmapDivergenceDrift,
   ctx: DriftContext,
-): void {
-  migrateHierarchyToDb(ctx.basePath);
-
-  const roadmapPath = resolveMilestoneFile(ctx.basePath, record.milestoneId, "ROADMAP");
-  if (!roadmapPath || !existsSync(roadmapPath)) return;
-
-  try {
-    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-    for (const slice of roadmap.slices) {
-      syncSliceDependencies(record.milestoneId, slice.id, slice.depends);
-    }
-  } catch {
-    /* parse failure: detector will fire again next pass */
-  }
+): Promise<void> {
+  await renderRoadmapFromDb(ctx.basePath, record.milestoneId);
 }
 
 export const roadmapDivergenceHandler: DriftHandler<RoadmapDivergenceDrift> = {

package/src/resources/extensions/gsd/status-guards.ts

@@ -25,3 +25,8 @@ export function isDeferredStatus(status: string): boolean {
 export function isInactiveStatus(status: string): boolean {
   return isClosedStatus(status) || isDeferredStatus(status);
 }
+
+/** Returns true when a prior milestone should not block dispatch ordering. */
+export function isSkippedForDispatch(status: string): boolean {
+  return isClosedStatus(status) || status === "parked" || isDeferredStatus(status);
+}

package/src/resources/extensions/gsd/templates/knowledge.md

@@ -1,7 +1,7 @@
 # Project Knowledge
 
-Append-only register of project-specific rules, patterns, and lessons learned.
-Agents read this before every unit. Add entries when you discover something worth remembering.
+Project-specific rules plus projected patterns and lessons learned.
+Rules are maintained in this file. Patterns and lessons are persisted to the memories table and rendered here on the next session-start projection.
 
 ## Rules
 

package/src/resources/extensions/gsd/templates/plan.md

@@ -99,11 +99,11 @@
   - "Improve UI"
 
   Each task should usually include:
-  - Why: why this task exists / what part of the slice it closes
-  - Files: the main files likely touched
-  - Do: concrete implementation steps and important constraints
-  - Verify: the command, test, or runtime check that proves it worked
-  - Done when: a measurable acceptance condition
+  - description: why this task exists, concrete steps, and done-when acceptance
+  - files: JSON array of likely touched paths
+  - verify: the command, test, or runtime check that proves it worked
+  - inputs: JSON array of existing paths or prior task outputs this task consumes
+  - expectedOutput: JSON array of paths this task creates or overwrites
 
   Keep the checkbox line format exactly:
   - [ ] **T01: Title** `est:30m`
@@ -131,10 +131,13 @@
 
   Verify field rules:
   - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
+  - MUST NOT use shell pipes, redirects, semicolons, backticks, command substitution, or output trimming
   - For content/document tasks: verify file existence, section count, YAML validity, or word count
     NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
   - If no command can verify the output, write: "Manual review — file exists and is non-empty"
+  - BAD: `python3 -m pytest tests/ -q --tb=short 2>&1 | tail -5`
   - BAD: "Sections 3.1 and 3.2 exist with exact formulas. Zero TBD/TODO."
+  - GOOD: `python3 -m pytest tests/ -q --tb=short`
   - GOOD: `grep -c "^## " doc.md` returns >= 4 (4+ sections), `! grep -q "TBD\|TODO" doc.md`
 
   Integration closure rule:

package/src/resources/extensions/gsd/templates/task-plan.md

@@ -72,7 +72,8 @@ skills_used:
 <!-- Every input MUST be a backtick-wrapped file path. These paths are machine-parsed to
      derive task dependencies — vague descriptions without paths break dependency detection.
      For the first task in a slice with no prior task outputs, list the existing source files
-     this task reads or modifies. -->
+     this task reads or modifies.
+     Tool field: inputs must be an array of strings, e.g. ["src/index.ts"], never a single string. -->
 
 - `{{filePath}}` — {{whatThisTaskNeedsFromPriorWork}}
 
@@ -82,6 +83,7 @@ skills_used:
      or modifies. These paths are machine-parsed to derive task dependencies.
      This task should produce a real increment toward making the slice goal/demo true. A full
      slice plan should not be able to mark every task complete while the claimed slice behavior
-     still does not work at the stated proof level. -->
+     still does not work at the stated proof level.
+     Tool field: expectedOutput must be an array of strings, e.g. ["src/index.ts"], never a single string. -->
 
 - `{{filePath}}` — {{whatThisTaskCreatesOrModifies}}

package/src/resources/extensions/gsd/tests/auto-dashboard.test.ts

@@ -13,6 +13,7 @@ import {
   formatWidgetTokens,
   estimateTimeRemaining,
   extractUatSliceId,
+  buildPhaseHandoffOutcome,
   updateProgressWidget,
   setAutoOutcomeWidget,
   getRoadmapSlicesSync,
@@ -255,6 +256,76 @@ test("setAutoOutcomeWidget renders a durable next-action handoff", () => {
   assert.match(output, /\/gsd auto/);
 });
 
+test("buildPhaseHandoffOutcome summarizes the last phase result", () => {
+  const snapshot = buildPhaseHandoffOutcome({
+    unitType: "plan-slice",
+    unitId: "M005/S01",
+    agentEndMessages: [
+      { message: { role: "assistant", content: "Planned S01 with category-aware filtering and validation steps." } },
+    ],
+  });
+
+  assert.equal(snapshot.status, "complete");
+  assert.equal(snapshot.title, "PLAN complete");
+  assert.match(snapshot.detail ?? "", /category-aware filtering/);
+  assert.equal(snapshot.unitLabel, "planning M005/S01");
+  assert.match(snapshot.nextAction, /next phase/);
+});
+
+test("buildPhaseHandoffOutcome ignores non-assistant trailing messages", () => {
+  const snapshot = buildPhaseHandoffOutcome({
+    unitType: "plan-slice",
+    unitId: "M005/S01",
+    agentEndMessages: [
+      { message: { role: "assistant", content: "Assistant summary to hand off." } },
+      { role: "tool", content: "Tool output should not be shown." },
+      { role: "user", content: "User follow-up should not be shown." },
+    ],
+  });
+
+  assert.match(snapshot.detail ?? "", /Assistant summary/);
+  assert.doesNotMatch(snapshot.detail ?? "", /Tool output/);
+  assert.doesNotMatch(snapshot.detail ?? "", /User follow-up/);
+});
+
+test("updateProgressWidget preserves the phase handoff during session switching", () => {
+  const calls: Array<[string, unknown]> = [];
+  updateProgressWidget(
+    {
+      hasUI: true,
+      ui: {
+        setWidget(key: string, factory: unknown) {
+          calls.push([key, factory]);
+        },
+        setHeader() {},
+        setStatus() {},
+      },
+    } as any,
+    "execute-task",
+    "M005/S01/T01",
+    {
+      phase: "executing",
+      activeSlice: { id: "S01", title: "Filter chip bar" },
+      activeTask: { id: "T01", title: "Add category filter" },
+    } as any,
+    {
+      getAutoStartTime: () => Date.now(),
+      isStepMode: () => false,
+      getCmdCtx: () => null,
+      getBasePath: () => "",
+      isVerbose: () => false,
+      isSessionSwitching: () => true,
+      getCurrentDispatchedModelId: () => null,
+    },
+  );
+
+  assert.ok(calls.some(([key]) => key === "gsd-progress"));
+  assert.ok(
+    !calls.some(([key, value]) => key === "gsd-outcome" && value === undefined),
+    "handoff widget should stay visible until the next progress frame renders",
+  );
+});
+
 test("shouldRenderRoadmapProgress hides pre-roadmap zero-slice progress", () => {
   assert.equal(shouldRenderRoadmapProgress(null), false);
   assert.equal(shouldRenderRoadmapProgress({ done: 0, total: 0, activeSliceTasks: null } as any), false);