gsd-pi 2.71.0-dev.06b86c6 → 2.71.0-dev.4c35d99

package/src/resources/extensions/gsd/notification-store.ts

@@ -35,6 +35,7 @@ let _basePath: string | null = null;
 let _lineCount = 0;  // Hint for rotation — not authoritative for public API
 let _suppressCount = 0;
 let _recentMessageTimestamps = new Map<string, number>();
+const _changeListeners = new Set<() => void>();
 
 // ─── Public API ─────────────────────────────────────────────────────────
 
@@ -93,6 +94,7 @@ export function appendNotification(
     if (_lineCount > MAX_ENTRIES) {
       _rotate();
     }
+    _emitChange();
   } catch {
     // Non-fatal — never let persistence break the caller
   }
@@ -121,6 +123,7 @@ export function markAllRead(basePath?: string): void {
   const hasUnread = entries.some((e) => !e.read);
   if (!hasUnread) return;
 
+  let changed = false;
   try {
     _withLock(bp, () => {
       // Re-read inside lock to get freshest state
@@ -128,10 +131,12 @@ export function markAllRead(basePath?: string): void {
       if (fresh.length === 0 || !fresh.some((e) => !e.read)) return;
       const lines = fresh.map((e) => JSON.stringify({ ...e, read: true }));
       _atomicWrite(bp, lines.join("\n") + "\n");
+      changed = true;
     });
   } catch {
     // Non-fatal
   }
+  if (changed) _emitChange();
 }
 
 /**
@@ -145,6 +150,8 @@ export function clearNotifications(basePath?: string): void {
     _withLock(bp, () => {
       _atomicWrite(bp, "");
     });
+    _lineCount = 0;
+    _emitChange();
   } catch {
     // Non-fatal
   }
@@ -189,6 +196,17 @@ export function unsuppressPersistence(): void {
   _suppressCount = Math.max(0, _suppressCount - 1);
 }
 
+/**
+ * Subscribe to notification-store mutations (append, mark-read, clear).
+ * Returns an unsubscribe function.
+ */
+export function onNotificationStoreChange(listener: () => void): () => void {
+  _changeListeners.add(listener);
+  return () => {
+    _changeListeners.delete(listener);
+  };
+}
+
 // ─── Test Helpers ───────────────────────────────────────────────────────
 
 /**
@@ -199,6 +217,7 @@ export function _resetNotificationStore(): void {
   _lineCount = 0;
   _suppressCount = 0;
   _recentMessageTimestamps = new Map();
+  _changeListeners.clear();
 }
 
 // ─── Internal ───────────────────────────────────────────────────────────
@@ -234,12 +253,23 @@ function _rotate(): void {
       const trimmed = entries.slice(entries.length - MAX_ENTRIES);
       const lines = trimmed.map((e) => JSON.stringify(e));
       _atomicWrite(_basePath!, lines.join("\n") + "\n");
+      _lineCount = trimmed.length;
     });
   } catch {
     // Non-fatal
   }
 }
 
+function _emitChange(): void {
+  for (const listener of _changeListeners) {
+    try {
+      listener();
+    } catch {
+      // Non-fatal
+    }
+  }
+}
+
 /**
  * Atomic file rewrite via temp-file + rename. Prevents partial reads
  * by other processes (web API subprocess, parallel workers).
@@ -293,10 +323,11 @@ function _withLock<T>(basePath: string, fn: () => T): T {
     }
   }
 
-  // Only run the mutation if we actually own the lock
-  const ownsLock = fd !== null;
+  // Best-effort: mutation runs regardless of lock status (idempotent overwrites).
+  // createdLock gates cleanup only — never skip fn() on lock failure.
+  const createdLock = fd !== null;
   try {
-    if (ownsLock && fd !== null) {
+    if (createdLock && fd !== null) {
       // Write our PID timestamp into the lock for stale detection
       writeFileSync(lockPath, String(Date.now()), "utf-8");
       closeSync(fd);
@@ -304,7 +335,7 @@ function _withLock<T>(basePath: string, fn: () => T): T {
     return fn();
   } finally {
     // Only delete the lock if we created it — never remove another process's lock
-    if (ownsLock) {
+    if (createdLock) {
       try { unlinkSync(lockPath); } catch { /* best-effort cleanup */ }
     }
   }

package/src/resources/extensions/gsd/notification-widget.ts

@@ -5,8 +5,8 @@
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 
-import { getUnreadCount, readNotifications } from "./notification-store.js";
-import { formatShortcut } from "./files.js";
+import { getUnreadCount, onNotificationStoreChange } from "./notification-store.js";
+import { formattedShortcutPair } from "./shortcut-defs.js";
 
 // ─── Pure rendering ──���────────────────────────���─────────────────────────
 
@@ -14,18 +14,7 @@ export function buildNotificationWidgetLines(): string[] {
   const unread = getUnreadCount();
   if (unread === 0) return [];
 
-  const entries = readNotifications();
-  const latest = entries[0]; // newest-first
-  if (!latest) return [];
-
-  const icon = latest.severity === "error" ? "✗" : latest.severity === "warning" ? "⚠" : "●";
-  const badge = `${unread} unread`;
-  const msgMax = 80;
-  const truncated = latest.message.length > msgMax
-    ? latest.message.slice(0, msgMax - 1) + "…"
-    : latest.message;
-
-  return [`  ${icon} [${badge}]  ${truncated}  (${formatShortcut("Ctrl+Alt+N")} or /gsd notifications)`];
+  return [`  🔔 Notifications: ${unread} unread  (${formattedShortcutPair("notifications")})`];
 }
 
 // ─── Widget init ────────────────────────────────────────────────────────
@@ -51,6 +40,7 @@ export function initNotificationWidget(ctx: ExtensionContext): void {
       _tui.requestRender();
     };
 
+    const unsubscribe = onNotificationStoreChange(refresh);
     const refreshTimer = setInterval(refresh, REFRESH_INTERVAL_MS);
 
     return {
@@ -62,6 +52,7 @@ export function initNotificationWidget(ctx: ExtensionContext): void {
         cachedLines = undefined;
       },
       dispose(): void {
+        unsubscribe();
         clearInterval(refreshTimer);
       },
     };

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

@@ -2,7 +2,8 @@
  * GSD Parallel Monitor Overlay
  *
  * Full-screen TUI overlay showing real-time parallel worker progress.
- * Opened via `/gsd parallel watch` or Ctrl+Alt+P (⌃⌥P on macOS).
+ * 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.
  */
@@ -15,6 +16,7 @@ import type { Theme } from "@gsd/pi-coding-agent";
 import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 
 import { formatDuration, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
+import { formattedShortcutPair } from "./shortcut-defs.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -347,7 +349,12 @@ export class ParallelMonitorOverlay {
   }
 
   handleInput(data: string): void {
-    if (matchesKey(data, Key.escape) || data === "q") {
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrlAlt("p")) ||
+      matchesKey(data, Key.ctrlShift("p")) ||
+      data === "q"
+    ) {
       this.dispose();
       this.onClose();
       return;
@@ -486,7 +493,7 @@ 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 to close  │  ↑↓ scroll"));
+    lines.push(t.fg("muted", `  ESC/q/${formattedShortcutPair("parallel")} close  │  ↑↓ scroll`));
 
     // Apply scroll — use terminal rows as height estimate
     const termHeight = process.stdout.rows || 40;

package/src/resources/extensions/gsd/prompt-validation.ts

@@ -0,0 +1,157 @@
+/**
+ * GSD Prompt Validation — Validates enhanced context and turn output
+ * artifacts before writing.
+ *
+ * Implements R109 validation requirement: CONTEXT.md must have required
+ * sections before being written to disk. Additionally, per-turn validators
+ * check that artifacts produced by gate-owning turns contain the gate
+ * sections declared in gate-registry.ts, so a malformed summary/validation
+ * markdown file cannot silently drop a quality gate.
+ */
+
+import { getGatesForTurn, type OwnerTurn } from "./gate-registry.js";
+
+/**
+ * Result of validating enhanced context output.
+ */
+export interface ValidationResult {
+  /** Whether all required sections are present. */
+  valid: boolean;
+  /** List of missing required sections. */
+  missing: string[];
+}
+
+/**
+ * Validate that enhanced context content has all required sections.
+ *
+ * Required sections per R109:
+ * - Scope section (## Scope, ## Milestone Scope, or ## Why This Milestone)
+ * - Architectural Decisions section (## Architectural Decisions)
+ * - Acceptance Criteria section (## Acceptance Criteria or ## Final Integrated Acceptance)
+ *
+ * Additionally validates that the Architectural Decisions section contains
+ * at least one decision entry (### heading or **Decision marker).
+ *
+ * @param content - The enhanced context markdown content
+ * @returns ValidationResult with valid flag and list of missing sections
+ */
+export function validateEnhancedContext(content: string): ValidationResult {
+  const missing: string[] = [];
+
+  // Required section 1: Scope (multiple acceptable header variants)
+  const hasScopeSection =
+    /^## Scope\b/m.test(content) ||
+    /^## Milestone Scope\b/m.test(content) ||
+    /^## Why This Milestone\b/m.test(content);
+
+  if (!hasScopeSection) {
+    missing.push("Milestone Scope or Why This Milestone");
+  }
+
+  // Required section 2: Architectural Decisions
+  const hasArchitecturalDecisions = /^## Architectural Decisions\b/m.test(content);
+  if (!hasArchitecturalDecisions) {
+    missing.push("Architectural Decisions");
+  }
+
+  // Required section 3: Acceptance Criteria (multiple acceptable header variants)
+  const hasAcceptanceCriteria =
+    /^## Acceptance Criteria\b/m.test(content) ||
+    /^## Final Integrated Acceptance\b/m.test(content);
+
+  if (!hasAcceptanceCriteria) {
+    missing.push("Acceptance Criteria");
+  }
+
+  // Additional validation: Architectural Decisions must have at least one entry
+  if (hasArchitecturalDecisions) {
+    // Extract the section content between ## Architectural Decisions and the next ## heading.
+    // Uses indexOf-based extraction instead of regex with \z (which is invalid in JavaScript
+    // regex — it's PCRE/Ruby syntax and JS treats it as literal 'z').
+    const sectionStart = content.indexOf("## Architectural Decisions");
+    if (sectionStart === -1) {
+      missing.push("Architectural Decisions");
+    } else {
+      const afterHeading = content.slice(sectionStart + "## Architectural Decisions".length);
+      const nextSection = afterHeading.search(/^## /m);
+      const sectionContent = nextSection === -1 ? afterHeading : afterHeading.slice(0, nextSection);
+
+      // Check for actual decision entries:
+      // - ### heading (subsection per decision)
+      // - **Decision marker (inline decision format)
+      const hasDecisionEntry = /^### /m.test(sectionContent) || /^\*\*Decision/m.test(sectionContent);
+
+      if (!hasDecisionEntry) {
+        missing.push("At least one architectural decision entry");
+      }
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}
+
+// ─── Per-Turn Gate Section Validators ─────────────────────────────────────
+//
+// Each validator checks that the artifact written by a turn contains a
+// heading for every gate owned by that turn. The registry is the source
+// of truth for which sections must exist; adding a new gate automatically
+// flows through via `getGatesForTurn(turn)`.
+
+/**
+ * Escape a string so it can be embedded safely inside a regular expression.
+ */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Validate that an artifact contains an `## H2` heading for every gate the
+ * named turn owns. Returns the list of missing gate section headers.
+ *
+ * Soft rule: a section counts as "present" if it is declared (H2 heading
+ * exists) — empty-body sections are allowed and handled by the tool
+ * handler, which will record such gates as `omitted`.
+ */
+export function validateGateSections(
+  content: string,
+  turn: OwnerTurn,
+): ValidationResult {
+  const missing: string[] = [];
+  for (const def of getGatesForTurn(turn)) {
+    const pattern = new RegExp(`^##\\s+${escapeRegExp(def.promptSection)}\\b`, "m");
+    if (!pattern.test(content)) {
+      missing.push(`${def.id} (## ${def.promptSection})`);
+    }
+  }
+  return { valid: missing.length === 0, missing };
+}
+
+/**
+ * Validate a SUMMARY.md produced by the complete-slice turn. Requires
+ * an H2 heading for every gate owned by complete-slice (e.g. Q8 →
+ * "## Operational Readiness"). Intended for use in the tool handler's
+ * pre-write checks or in the post-unit validation sweep.
+ */
+export function validateSliceSummaryOutput(content: string): ValidationResult {
+  return validateGateSections(content, "complete-slice");
+}
+
+/**
+ * Validate a task SUMMARY.md produced by the execute-task turn. Only
+ * flags gates that are still pending for the task; skips the check
+ * when no rows are seeded (simple task).
+ */
+export function validateTaskSummaryOutput(content: string): ValidationResult {
+  return validateGateSections(content, "execute-task");
+}
+
+/**
+ * Validate a VALIDATION.md produced by the validate-milestone turn.
+ * Requires an H2 heading for every MV gate declared in the registry.
+ */
+export function validateMilestoneValidationOutput(content: string): ValidationResult {
+  return validateGateSections(content, "validate-milestone");
+}

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

@@ -16,6 +16,8 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 {{inlinedContext}}
 
+{{gatesToClose}}
+
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
 Then:
@@ -23,7 +25,7 @@ Then:
 2. {{skillActivation}}
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first. Task artifacts use a **flat file layout** directly inside `tasks/` (for example `T01-SUMMARY.md`, `T02-SUMMARY.md`) rather than per-task subdirectories. If you need to count or re-read task summaries during verification, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` or `ls .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks/*-SUMMARY.md`. Never use `tasks/*/SUMMARY.md` — that glob expects subdirectories that do not exist.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
-5. If the slice involved runtime behavior, fill the **Operational Readiness** section (Q8) in the slice summary: health signal, failure signal, recovery procedure, and monitoring gaps. Omit entirely for simple slices with no runtime concerns.
+5. Address every gate listed in the **Gates to Close** section above — each gate maps to a specific slice-summary section the handler inspects (for example, Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, and monitoring gaps). Leaving a section empty records the gate as `omitted`.
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
 7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
 8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -22,6 +22,8 @@ A researcher explored the codebase and a planner decomposed the work — you are
 
 {{slicePlanExcerpt}}
 
+{{gatesToClose}}
+
 ## Backing Source Artifacts
 - Slice plan: `{{planPath}}`
 - Task plan source: `{{taskPlanPath}}`

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -18,6 +18,8 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 {{inlinedContext}}
 
+{{gatesToEvaluate}}
+
 ## Execution Protocol
 
 ### Step 1 — Dispatch Parallel Reviewers

package/src/resources/extensions/gsd/session-model-override.ts

@@ -0,0 +1,36 @@
+export interface SessionModelOverride {
+  provider: string;
+  id: string;
+}
+
+const sessionOverrides = new Map<string, SessionModelOverride>();
+
+function normalizeSessionId(sessionId: string): string {
+  return typeof sessionId === "string" ? sessionId.trim() : "";
+}
+
+export function setSessionModelOverride(
+  sessionId: string,
+  override: SessionModelOverride,
+): void {
+  const key = normalizeSessionId(sessionId);
+  if (!key) return;
+  sessionOverrides.set(key, {
+    provider: override.provider,
+    id: override.id,
+  });
+}
+
+export function getSessionModelOverride(
+  sessionId: string,
+): SessionModelOverride | undefined {
+  const key = normalizeSessionId(sessionId);
+  if (!key) return undefined;
+  return sessionOverrides.get(key);
+}
+
+export function clearSessionModelOverride(sessionId: string): void {
+  const key = normalizeSessionId(sessionId);
+  if (!key) return;
+  sessionOverrides.delete(key);
+}

package/src/resources/extensions/gsd/shortcut-defs.ts

@@ -0,0 +1,56 @@
+// Canonical GSD shortcut definitions used by registration, help text, and overlays.
+
+import { formatShortcut } from "./files.js";
+
+export type GSDShortcutId = "dashboard" | "notifications" | "parallel";
+
+type GSDShortcutDef = {
+  key: "g" | "n" | "p";
+  action: string;
+  command: string;
+  /** Whether the Ctrl+Shift fallback is registered (false when it conflicts with an app keybinding). */
+  hasFallback: boolean;
+};
+
+export const GSD_SHORTCUTS: Record<GSDShortcutId, GSDShortcutDef> = {
+  dashboard: {
+    key: "g",
+    action: "Open GSD dashboard",
+    command: "/gsd status",
+    hasFallback: true,
+  },
+  notifications: {
+    key: "n",
+    action: "Open notification history",
+    command: "/gsd notifications",
+    hasFallback: true,
+  },
+  parallel: {
+    key: "p",
+    action: "Open parallel worker monitor",
+    command: "/gsd parallel watch",
+    hasFallback: false, // Ctrl+Shift+P conflicts with cycleModelBackward
+  },
+};
+
+function combo(prefix: "Ctrl+Alt+" | "Ctrl+Shift+", key: string): string {
+  return `${prefix}${key.toUpperCase()}`;
+}
+
+export function primaryShortcutCombo(id: GSDShortcutId): string {
+  return combo("Ctrl+Alt+", GSD_SHORTCUTS[id].key);
+}
+
+export function fallbackShortcutCombo(id: GSDShortcutId): string {
+  return combo("Ctrl+Shift+", GSD_SHORTCUTS[id].key);
+}
+
+export function shortcutPair(id: GSDShortcutId, formatter: (combo: string) => string = (combo) => combo): string {
+  const primary = formatter(primaryShortcutCombo(id));
+  if (!GSD_SHORTCUTS[id].hasFallback) return primary;
+  return `${primary} / ${formatter(fallbackShortcutCombo(id))}`;
+}
+
+export function formattedShortcutPair(id: GSDShortcutId): string {
+  return shortcutPair(id, formatShortcut);
+}

package/src/resources/extensions/gsd/state.ts

@@ -58,7 +58,7 @@ import {
   insertSlice,
   insertTask,
   updateTaskStatus,
-  getPendingSliceGateCount,
+  getPendingGateCountForTurn,
   type MilestoneRow,
   type SliceRow,
   type TaskRow,
@@ -864,7 +864,18 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
     }
   }
 
-  const pendingGateCount = getPendingSliceGateCount(activeMilestone.id, activeSlice.id);
+  // ── Quality gate evaluation check ──────────────────────────────────
+  // Pause before execution only when gates owned by the `gate-evaluate`
+  // turn (Q3/Q4) are still pending. Q8 is also `scope:"slice"` but is
+  // owned by `complete-slice`, so it must NOT block the evaluating-gates
+  // phase — otherwise auto-loop stalls forever waiting for a gate that
+  // this turn never evaluates. See gate-registry.ts for the ownership map.
+  // Slices with zero gate rows (pre-feature or simple) skip straight through.
+  const pendingGateCount = getPendingGateCountForTurn(
+    activeMilestone.id,
+    activeSlice.id,
+    "gate-evaluate",
+  );
   if (pendingGateCount > 0) {
     return {
       activeMilestone, activeSlice, activeTask: null,

package/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts

@@ -7,9 +7,8 @@ const sourcePath = join(import.meta.dirname, "..", "auto-start.ts");
 const source = readFileSync(sourcePath, "utf-8");
 
 test("bootstrapAutoSession snapshots ctx.model before guided-flow entry (#2829)", () => {
-  // #3517 changed the snapshot to prefer GSD preferences, but the ordering
-  // guarantee still holds: the snapshot must be built before guided-flow.
-  const snapshotIdx = source.indexOf("const startModelSnapshot = preferredModel");
+  // The snapshot ordering guarantee still holds: build snapshot before guided-flow.
+  const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
   assert.ok(snapshotIdx > -1, "auto-start.ts should snapshot model at bootstrap start");
 
   const firstDiscussIdx = source.indexOf('await showSmartEntry(ctx, pi, base, { step: requestedStepMode });');
@@ -29,8 +28,11 @@ test("bootstrapAutoSession restores autoModeStartModel from the early snapshot (
   assert.ok(snapshotRefIdx > -1, "autoModeStartModel should be restored from startModelSnapshot");
 });
 
-test("bootstrapAutoSession prefers GSD PREFERENCES.md over settings.json for start model (#3517)", () => {
-  // resolveDefaultSessionModel() should be called before the snapshot is built
+test("bootstrapAutoSession checks manual session override before preferences", () => {
+  const manualIdx = source.indexOf("const manualSessionOverride = getSessionModelOverride(");
+  assert.ok(manualIdx > -1, "auto-start.ts should read session model override first");
+
+  // resolveDefaultSessionModel() should still be called for fallback behavior
   const preferredIdx = source.indexOf("const preferredModel = resolveDefaultSessionModel(");
   assert.ok(preferredIdx > -1, "auto-start.ts should call resolveDefaultSessionModel()");
 
@@ -38,11 +40,25 @@ test("bootstrapAutoSession prefers GSD PREFERENCES.md over settings.json for sta
   const withProviderIdx = source.indexOf("resolveDefaultSessionModel(ctx.model?.provider)");
   assert.ok(withProviderIdx > -1, "auto-start.ts should pass ctx.model?.provider for bare ID resolution");
 
-  const snapshotIdx = source.indexOf("const startModelSnapshot = preferredModel");
-  assert.ok(snapshotIdx > -1, "startModelSnapshot should use preferredModel when available");
+  const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
+  assert.ok(snapshotIdx > -1, "startModelSnapshot should prefer manual session override");
 
   assert.ok(
-    preferredIdx < snapshotIdx,
-    "resolveDefaultSessionModel() must be called before building startModelSnapshot",
+    manualIdx < snapshotIdx && preferredIdx < snapshotIdx,
+    "manual override and preference fallback must be resolved before building startModelSnapshot",
   );
 });
+
+test("bootstrapAutoSession validates preferred model against live registry auth (#unconfigured-models)", () => {
+  // The raw PREFERENCES.md value must be validated against getAvailable()
+  // before being captured as the snapshot, so an unconfigured provider
+  // (no API key / OAuth) can't become autoModeStartModel.
+  const validationIdx = source.indexOf("ctx.modelRegistry.getAvailable()");
+  assert.ok(validationIdx > -1, "auto-start.ts should validate preferred model against getAvailable()");
+
+  const resolveModelIdIdx = source.indexOf("resolveModelId");
+  assert.ok(resolveModelIdIdx > -1, "auto-start.ts should resolve preferred model against the registry");
+
+  const warningIdx = source.indexOf("is not configured; falling back to session default");
+  assert.ok(warningIdx > -1, "auto-start.ts should warn when preferred model is unconfigured");
+});