@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/src/resources/extensions/gsd/compat/planning-compat.ts

@@ -0,0 +1,168 @@
+// Project/App: gsd-pi
+// File Purpose: `.planning/` compat helpers — layout capture and projection sha
+// recording. Parallel to the .gsd/ write-time flush in markdown-renderer.ts.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  computeProjectionSha,
+  readCompatMarker,
+  writeCompatMarker,
+  type PlanningLayout,
+} from "./compat-marker.js";
+import { logWarning } from "../workflow-logger.js";
+
+export interface PlanningProjectionWrite {
+  relPath: string;
+  entities: string[];
+  passthrough?: boolean;
+}
+
+export function isPlanningPassthroughRelPath(relPath: string): boolean {
+  if (relPath.startsWith("codebase/") || relPath.startsWith("research/")) return true;
+  if (relPath === "config.json") return true;
+  const name = relPath.split("/").pop() ?? relPath;
+  if (name === "PATTERNS.md" || name === "REVIEWS.md") return true;
+  if (name.endsWith("-DISCUSSION-LOG.md")) return true;
+  if (name.endsWith("-RESEARCH.md") && !name.endsWith("-PLAN.md")) return true;
+  return false;
+}
+
+// Files that gsd-pi creates in .gsd/ at startup and that do not constitute
+// markdown content written by gsd-core. Excluded from the content check so a
+// .planning/-only project that already has a gsd.db (but no milestone markdown)
+// is not mistakenly treated as a coexistence project.
+const KNOWN_NON_CONTENT_FILES = new Set([
+  "gsd.db",
+  "gsd.db-wal",
+  "gsd.db-shm",
+  "completed-units.json",
+]);
+
+export function gsdTreeHasContent(basePath: string): boolean {
+  const gsdDir = join(basePath, ".gsd");
+  return (
+    existsSync(gsdDir) &&
+    readdirSync(gsdDir).some(
+      (name) => !name.startsWith(".") && !KNOWN_NON_CONTENT_FILES.has(name),
+    )
+  );
+}
+
+export function walkPlanningRelPaths(planningDir: string, prefix = ""): string[] {
+  const paths: string[] = [];
+  let entries;
+  try {
+    entries = readdirSync(join(planningDir, prefix), { withFileTypes: true });
+  } catch {
+    return paths;
+  }
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (entry.name === "workstreams") continue;
+      paths.push(...walkPlanningRelPaths(planningDir, rel));
+    } else {
+      paths.push(rel);
+    }
+  }
+  return paths;
+}
+
+/**
+ * Record freshly written `.planning/` projection files in the compat marker.
+ */
+export function applyPlanningProjectionWrites(
+  basePath: string,
+  writes: PlanningProjectionWrite[],
+): void {
+  if (writes.length === 0) return;
+  const marker = readCompatMarker(basePath);
+  if (!marker.planning) {
+    marker.planning = { active: true, layout: null, projections: {}, passthrough: {} };
+  }
+  marker.planning.active = true;
+  for (const write of writes) {
+    const abs = join(basePath, ".planning", write.relPath);
+    if (!existsSync(abs)) continue;
+    const entry = {
+      sha: computeProjectionSha(readFileSync(abs, "utf-8")),
+      entities: write.entities,
+    };
+    const map = write.passthrough ? marker.planning.passthrough : marker.planning.projections;
+    map[write.relPath] = entry;
+  }
+  marker.lastWriter = "gsd-pi";
+  marker.lastProjectedAt = new Date().toISOString();
+  writeCompatMarker(basePath, marker);
+}
+
+export interface CapturePlanningCompatOptions {
+  dryRun?: boolean;
+}
+
+/**
+ * Capture-on-first-read: infer `.planning/` layout from disk, import content
+ * into the DB so gsd-pi's projection reflects gsd-core's tree instead of
+ * overwriting it, then activate the compat marker. Projection shas are seeded
+ * by drift repair / write-time hooks — not from raw disk here.
+ *
+ * Must only be called when !dryRun — it writes both the DB and the marker.
+ */
+export async function capturePlanningCompatIfNeeded(
+  basePath: string,
+  options?: CapturePlanningCompatOptions,
+): Promise<void> {
+  if (options?.dryRun) return;
+
+  const planningDir = join(basePath, ".planning");
+  if (!existsSync(planningDir)) return;
+
+  const marker = readCompatMarker(basePath);
+  if (marker.planning?.active && marker.planning.layout) return;
+
+  // First encounter: parse layout, import content into the DB, then activate the
+  // marker. When `.gsd/` already exists (coexistence), import from disk via
+  // migrateHierarchyToDb and do not call writeGSDDirectory — reconcile runs
+  // external-markdown-edit before external-planning-edit and must not destroy
+  // gsd-core `.gsd/` edits before that pipeline can see them. Planning-only
+  // projects materialize `.gsd/` from the parsed tree first, then import.
+  const { parsePlanningDirectory } = await import("../migrate/parser.js");
+  const { detectPlanningLayout } = await import("../migrate/layout-detect.js");
+  const parsed = await parsePlanningDirectory(planningDir);
+  const layout: PlanningLayout | null = detectPlanningLayout(parsed);
+  if (!layout) return;
+
+  // Import into the DB. Dynamic imports break the module-init cycle
+  // (planning-compat ← reconcile ← state ← md-importer). Matches the import
+  // pattern in repairExternalPlanningEdit.
+  try {
+    const { migrateHierarchyToDb } = await import("../md-importer.js");
+    const { invalidateStateCache } = await import("../state.js");
+    if (!gsdTreeHasContent(basePath)) {
+      const { transformToGSD } = await import("../migrate/transformer.js");
+      const { writeGSDDirectory } = await import("../migrate/writer.js");
+      const gsdProject = transformToGSD(parsed);
+      await writeGSDDirectory(gsdProject, basePath);
+    }
+    migrateHierarchyToDb(basePath);
+    invalidateStateCache();
+  } catch (e) {
+    logWarning(
+      "reconcile",
+      `planning DB import failed on initial capture — reconcile may overwrite gsd-core content: ${(e as Error).message}`,
+    );
+  }
+
+  // Activate the marker. Leave projections/passthrough empty: the next
+  // writePlanningDirectory → applyPlanningProjectionWrites call will seed
+  // accurate SHAs from the normalized output rather than the raw gsd-core files.
+  const freshMarker = readCompatMarker(basePath);
+  if (!freshMarker.planning) {
+    freshMarker.planning = { active: false, layout: null, projections: {}, passthrough: {} };
+  }
+  freshMarker.planning.active = true;
+  freshMarker.planning.layout = layout;
+  writeCompatMarker(basePath, freshMarker);
+}

package/src/resources/extensions/gsd/config-overlay.ts

@@ -25,19 +25,28 @@ import {
 
 const DEFAULT_WIDGET_MODE = "small";
 
-// ─── Data Collection ──────────────────────────────────────────────────────
-
 interface ConfigSection {
   title: string;
   rows: Array<{ label: string; value: string; accent?: boolean }>;
 }
 
-function collectConfigSections(): ConfigSection[] {
+// ─── Data Collection ──────────────────────────────────────────────────────
+
+export interface CollectConfigOptions {
+  basePath?: string;
+  availableModelIds?: string[];
+  preferredModelId?: string;
+}
+
+function collectConfigSections(options?: CollectConfigOptions): ConfigSection[] {
   const sections: ConfigSection[] = [];
 
   const globalPrefs = loadGlobalGSDPreferences();
-  const projectPrefs = loadProjectGSDPreferences();
-  const effective = loadEffectiveGSDPreferences();
+  const projectPrefs = loadProjectGSDPreferences(options?.basePath);
+  const loadOpts = options?.availableModelIds
+    ? { availableModelIds: options.availableModelIds, preferredModelId: options.preferredModelId }
+    : undefined;
+  const effective = loadEffectiveGSDPreferences(options?.basePath, loadOpts);
   const prefs = effective?.preferences;
 
   // ─── Sources ─────────────────────────────────────────────────────────
@@ -69,7 +78,12 @@ function collectConfigSections(): ConfigSection[] {
 
   const modelRows: ConfigSection["rows"] = [];
   for (const [label, unitType] of unitTypes) {
-    const resolved = resolveModelWithFallbacksForUnit(unitType);
+    const resolved = resolveModelWithFallbacksForUnit(
+      unitType,
+      options?.basePath,
+      options?.availableModelIds,
+      options?.preferredModelId,
+    );
     if (resolved) {
       let val = resolved.primary;
       if (resolved.fallbacks.length > 0) {
@@ -204,8 +218,8 @@ function collectConfigSections(): ConfigSection[] {
 
 // ─── Plain Text Formatter (headless/RPC fallback) ─────────────────────────
 
-export function formatConfigText(): string {
-  const sections = collectConfigSections();
+export function formatConfigText(options?: CollectConfigOptions): string {
+  const sections = collectConfigSections(options);
   const lines: string[] = ["GSD Configuration\n"];
 
   let maxLabel = 0;
@@ -243,11 +257,12 @@ export class GSDConfigOverlay {
     tui: { requestRender: () => void },
     theme: Theme,
     onClose: () => void,
+    options?: CollectConfigOptions,
   ) {
     this.tui = tui;
     this.theme = theme;
     this.onClose = onClose;
-    this.sections = collectConfigSections();
+    this.sections = collectConfigSections(options);
   }
 
   invalidate(): void {

package/src/resources/extensions/gsd/consent-question.ts

@@ -44,7 +44,7 @@ export type GateSubKind = "depth-verification" | "approval" | "destructive-confi
 
 export type FailPolicy = "closed" | "open";
 
-export type AnswerOutcome = "waiting" | "answered" | "verified" | "declined" | "cancelled";
+export type AnswerOutcome = "waiting" | "answered" | "verified" | "declined" | "cancelled" | "timeout";
 
 export interface ClassifiedQuestion {
   kind: QuestionKind;
@@ -234,6 +234,9 @@ export type ConsentAnswerDetails = VerdictAnswerDetails;
 /**
  * THE single policy point for whether a question's answer counts as answered.
  *
+ * - timed_out rounds → "timeout" for every kind (host elicitation expired
+ *   before the user answered; fail-closed, but the caller pauses-and-waits
+ *   instead of re-asking into the same timeout loop, #852).
  * - cancelled rounds → "cancelled" for every kind.
  * - gate: delegates to evaluateGateAnswer in the consent-verdict leaf — the
  *   same verdict engine write-gate's applyAskUserQuestionsGateResult consumes;
@@ -248,6 +251,7 @@ export function evaluateAnswer(options: {
   details: ConsentAnswerDetails;
 }): AnswerOutcome {
   const { question, details } = options;
+  if (details.timed_out) return "timeout";
   if (details.cancelled) return "cancelled";
 
   const { kind } = classifyQuestion({ id: question.id, options: question.options });
@@ -271,6 +275,7 @@ export function evaluateAnswer(options: {
 
 const OUTCOME_PRECEDENCE: AnswerOutcome[] = [
   "cancelled",
+  "timeout",
   "waiting",
   "declined",
   "verified",
@@ -289,6 +294,11 @@ export function evaluateAskUserQuestionsRound(
   questions: ConsentQuestionShape[],
   details: ConsentAnswerDetails,
 ): AnswerOutcome {
+  // timed_out is checked before cancelled: a host elicitation timeout is a
+  // more specific signal than the deliberate-dismissal cancelled it is also
+  // marked with, and callers must pause-and-wait instead of treating it as a
+  // re-ask-able cancel (#852).
+  if (details.timed_out) return "timeout";
   if (details.cancelled) return "cancelled";
   let worst: AnswerOutcome = "answered";
   for (const question of questions) {

package/src/resources/extensions/gsd/consent-verdict.ts

@@ -9,7 +9,20 @@
  * cycle. It must not import from either module (ADR-039).
  */
 
-export type GateAnswerVerdict = "waiting" | "verified" | "declined" | "cancelled";
+/**
+ * Per-question verdict for a gate answer.
+ *
+ *   - "verified" — the confirmation option was selected (depth unlocked).
+ *   - "declined" — a real but non-confirming selection (gate stays pending,
+ *     model should not treat as approval).
+ *   - "cancelled" — the round was cancelled by the user (deliberate dismissal).
+ *   - "waiting" — no answer (fail-closed; not an answer).
+ *   - "timeout" — the host elicitation timed out before the user answered.
+ *     Distinct from "waiting" so callers can pause-and-wait instead of letting
+ *     the model re-ask into the same timeout loop (#852). Still fail-closed:
+ *     the gate stays pending — a timeout is never approval.
+ */
+export type GateAnswerVerdict = "waiting" | "verified" | "declined" | "cancelled" | "timeout";
 
 export interface VerdictQuestionShape {
   id?: unknown;
@@ -19,6 +32,13 @@ export interface VerdictQuestionShape {
 export interface VerdictAnswerDetails {
   cancelled?: boolean;
   interrupted?: boolean;
+  /**
+   * True when the host elicitation channel timed out before the user answered.
+   * Distinct from `cancelled` (deliberate dismissal): a timeout must not be
+   * laundered into a re-ask loop. Gate verdicts map this to "timeout" so the
+   * caller pauses-and-waits instead of looping on the blocked call (#852).
+   */
+  timed_out?: boolean;
   response?: {
     answers?: Record<string, { selected?: unknown; notes?: unknown } | undefined>;
   } | null;
@@ -67,16 +87,25 @@ export function hasNotesValue(notes: unknown): boolean {
 /**
  * THE per-question verdict for gate questions (fail-closed):
  *
+ * - timed_out rounds → "timeout" (host elicitation expired before the user
+ *   answered; fail-closed — the gate stays pending — but the caller pauses
+ *   instead of re-asking into the same timeout loop, #852).
  * - cancelled rounds → "cancelled".
  * - the confirmation option (structural match) → "verified".
  * - any other real selection → "declined".
  * - empty/missing selection → "waiting" — an empty answer is NEVER an answer,
  *   so notes can never satisfy a gate either.
+ *
+ * `timed_out` is checked first: the handler marks a timed-out round with both
+ * `cancelled: true` and `timed_out: true` (see
+ * `askUserQuestionsHandler`), so the timeout must win to avoid the cancelled
+ * branch's re-ask semantics.
  */
 export function evaluateGateAnswer(
   question: VerdictQuestionShape,
   details: VerdictAnswerDetails,
 ): GateAnswerVerdict {
+  if (details.timed_out) return "timeout";
   if (details.cancelled) return "cancelled";
   const questionId = typeof question.id === "string" ? question.id : "";
   const answer = details.response?.answers?.[questionId];

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -15,6 +15,7 @@ import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { getAutoDashboardData } from "./auto.js";
 import type { AutoDashboardData } from "./auto-dashboard.js";
+import { getAutoRuntimeSnapshot } from "./auto-runtime-state.js";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
   aggregateByModel, aggregateCacheHitRate, formatCost, formatTokenCount, formatCostProjection,
@@ -22,6 +23,7 @@ import {
   type UnitMetrics,
 } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { countPendingCaptures } from "./captures.js";
 import { getActiveWorktreeName } from "./worktree-session-state.js";
 import { getWorkerBatches, hasActiveWorkers, type WorkerEntry } from "../subagent/worker-registry.js";
 import { formatDuration, padRight, joinColumns, centerLine, fitColumns, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
@@ -113,7 +115,9 @@ export class GSDDashboardOverlay {
       });
   }
 
-  private computeDashboardIdentity(dashData: AutoDashboardData): string {
+  private computeDashboardIdentity(
+    dashData: Pick<AutoDashboardData, "active" | "paused" | "currentUnit" | "basePath">,
+  ): string {
     const base = dashData.basePath || process.cwd();
     const currentUnit = dashData.currentUnit
       ? `${dashData.currentUnit.type}:${dashData.currentUnit.id}:${dashData.currentUnit.startedAt}`
@@ -126,18 +130,51 @@ export class GSDDashboardOverlay {
     ].join("|");
   }
 
+  private refreshVolatileDashboardData(snapshot = getAutoRuntimeSnapshot()): void {
+    let pendingCaptureCount = this.dashData.pendingCaptureCount;
+    try {
+      if (snapshot.basePath) {
+        pendingCaptureCount = countPendingCaptures(snapshot.basePath);
+      }
+    } catch {
+      // Non-fatal — keep last known value
+    }
+    this.dashData = {
+      ...this.dashData,
+      active: snapshot.active,
+      paused: snapshot.paused,
+      currentUnit: snapshot.currentUnit
+        ? {
+            type: snapshot.currentUnit.type,
+            id: snapshot.currentUnit.id,
+            startedAt: snapshot.currentUnit.startedAt,
+          }
+        : null,
+      basePath: snapshot.basePath,
+      elapsed: snapshot.active || snapshot.paused
+        ? (this.dashData.startTime > 0 ? Date.now() - this.dashData.startTime : 0)
+        : 0,
+      toolSurface: snapshot.toolSurface,
+      pendingCaptureCount,
+    };
+  }
+
   private async refreshDashboard(initial = false): Promise<void> {
     if (this.disposed) return;
-    this.dashData = getAutoDashboardData();
-    const nextIdentity = this.computeDashboardIdentity(this.dashData);
+    const runtimeSnapshot = getAutoRuntimeSnapshot();
+    const nextIdentity = this.computeDashboardIdentity(runtimeSnapshot);
 
     const identityChanged = initial || nextIdentity !== this.loadedDashboardIdentity;
     if (identityChanged) {
+      this.dashData = getAutoDashboardData();
+      const loadedIdentity = this.computeDashboardIdentity(this.dashData);
       const loaded = await this.loadData();
       if (this.disposed) return;
       if (loaded) {
-        this.loadedDashboardIdentity = nextIdentity;
+        this.loadedDashboardIdentity = loadedIdentity;
       }
+    } else {
+      this.refreshVolatileDashboardData(runtimeSnapshot);
     }
 
     if (initial) {

package/src/resources/extensions/gsd/db/engine.ts

@@ -671,6 +671,32 @@ export function closeDatabase(): void {
   _dbOpenState.reset();
 }
 
+/**
+ * Open an isolated database connection that does NOT touch the process-wide
+ * `currentDb` singleton. Intended for background observers (e.g. the parallel
+ * monitor overlay) that must read a database without displacing an active
+ * workflow session connection.
+ *
+ * The caller MUST call `adapter.close()` when done. Schema migrations are NOT
+ * run — the database must already exist and be fully migrated by the primary
+ * connection. Returns null if the connection cannot be opened.
+ */
+export function openIsolatedDatabase(path: string): DbAdapter | null {
+  try {
+    const rawDb = providerLoader.openRaw(path);
+    if (!rawDb) return null;
+    const adapter = createDbAdapter(rawDb);
+    // Minimal pragmas for a short-lived read-only observer connection.
+    // WAL mode is already set file-wide by the primary connection; repeating
+    // it here is a no-op on an existing WAL file and safe to issue.
+    adapter.exec("PRAGMA journal_mode=WAL");
+    adapter.exec("PRAGMA busy_timeout = 5000");
+    return adapter;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Re-open the active database connection from disk.
  *

package/src/resources/extensions/gsd/db/queries.ts

@@ -270,6 +270,66 @@ export function getMilestoneSlices(milestoneId: string): SliceRow[] {
   return rows.map(rowToSlice);
 }
 
+export interface ParallelMonitorSliceProgress {
+  id: string;
+  status: string;
+  total: number;
+  done: number;
+}
+
+export function getParallelMonitorSliceProgress(milestoneId: string): ParallelMonitorSliceProgress[] {
+  const db = getDbOrNull();
+  if (!db) return [];
+  const rows = db.prepare(
+    `SELECT
+       s.id AS id,
+       s.status AS status,
+       COUNT(t.id) AS total,
+       COALESCE(SUM(CASE WHEN t.status='complete' THEN 1 ELSE 0 END), 0) AS done
+     FROM slices s
+     LEFT JOIN tasks t ON s.milestone_id=t.milestone_id AND s.id=t.slice_id
+     WHERE s.milestone_id=:mid
+     GROUP BY s.id
+     ORDER BY s.id`,
+  ).all({ ":mid": milestoneId });
+  return rows.map((row) => ({
+    id: String(row["id"] ?? ""),
+    status: String(row["status"] ?? ""),
+    total: Number(row["total"] ?? 0),
+    done: Number(row["done"] ?? 0),
+  }));
+}
+
+export interface ParallelMonitorCompletion {
+  taskId: string;
+  sliceId: string;
+  oneLiner: string;
+}
+
+export function getParallelMonitorRecentCompletions(
+  milestoneId: string,
+  limit: number = 5,
+): ParallelMonitorCompletion[] {
+  const db = getDbOrNull();
+  if (!db) return [];
+  const numericLimit = Number.isFinite(limit) ? Math.floor(limit) : 5;
+  const safeLimit = Math.max(1, Math.min(50, numericLimit));
+  const rows = db.prepare(
+    `SELECT id, slice_id, one_liner
+     FROM tasks
+     WHERE milestone_id=:mid
+       AND status='complete'
+       AND completed_at IS NOT NULL
+     ORDER BY completed_at DESC
+     LIMIT ${safeLimit}`,
+  ).all({ ":mid": milestoneId });
+  return rows.map((row) => ({
+    taskId: String(row["id"] ?? ""),
+    sliceId: String(row["slice_id"] ?? ""),
+    oneLiner: String(row["one_liner"] ?? ""),
+  }));
+}
+
 /**
  * Load slices for many milestones in a single query. Returns a Map keyed by
  * milestone_id, preserving `ORDER BY sequence, id` within each bucket.
@@ -342,6 +402,24 @@ export function getArtifact(path: string): ArtifactRow | null {
   return rowToArtifact(row);
 }
 
+/** Milestone-level artifacts (CONTEXT, RESEARCH, VALIDATION, etc.) from the artifacts table. */
+export function getMilestoneScopedArtifacts(milestoneId: string): ArtifactRow[] {
+  if (!getDbOrNull()!) return [];
+  const rows = getDbOrNull()!.prepare(
+    "SELECT * FROM artifacts WHERE milestone_id = :mid AND slice_id IS NULL AND task_id IS NULL ORDER BY path",
+  ).all({ ":mid": milestoneId });
+  return rows.map(rowToArtifact);
+}
+
+/** Slice-level artifacts (CONTEXT, RESEARCH, CONTINUE, etc.) from the artifacts table. */
+export function getSliceScopedArtifacts(milestoneId: string, sliceId: string): ArtifactRow[] {
+  if (!getDbOrNull()!) return [];
+  const rows = getDbOrNull()!.prepare(
+    "SELECT * FROM artifacts WHERE milestone_id = :mid AND slice_id = :sid AND task_id IS NULL ORDER BY path",
+  ).all({ ":mid": milestoneId, ":sid": sliceId });
+  return rows.map(rowToArtifact);
+}
+
 /** Fast milestone status check — avoids deserializing JSON planning fields. */
 export function getActiveMilestoneIdFromDb(): IdStatusSummary | null {
   if (!getDbOrNull()!) return null;

package/src/resources/extensions/gsd/db/unit-dispatches.ts

@@ -520,9 +520,33 @@ export function getRecentUnitKeysForWorker(
 export function getRecentUnitKeysForProjectRoot(
   projectRootRealpath: string,
   limit = 20,
+  traceId?: string,
 ): Array<{ key: string }> {
   if (!isDbAvailable()) return [];
   const db = _getAdapter()!;
+  // When a trace_id is provided, scope the window to the current session so
+  // stale finalize-retry entries from PREVIOUS sessions don't fire detectStuck
+  // Rule 1 on the first iteration of a new session — killing auto-mode before
+  // any new dispatch runs. Without this, a project that had two consecutive
+  // finalize-retry failures in a prior session is permanently stuck: every
+  // fresh session loads those stale errors and immediately declares stuck.
+  if (traceId) {
+    const rows = db.prepare(
+      `SELECT ud.unit_type, ud.unit_id
+       FROM unit_dispatches ud
+       INNER JOIN workers w ON w.worker_id = ud.worker_id
+       WHERE w.project_root_realpath = :project_root_realpath
+         AND w.status != 'crashed'
+         AND ud.trace_id = :trace_id
+       ORDER BY ud.started_at DESC, ud.id DESC
+       LIMIT :limit`,
+    ).all({
+      ":project_root_realpath": projectRootRealpath,
+      ":trace_id": traceId,
+      ":limit": limit,
+    }) as Array<{ unit_type: string; unit_id: string }>;
+    return rows.reverse().map((r) => ({ key: `${r.unit_type}/${r.unit_id}` }));
+  }
   const rows = db.prepare(
     `SELECT ud.unit_type, ud.unit_id
      FROM unit_dispatches ud

package/src/resources/extensions/gsd/db/writers/reconcile.ts

@@ -11,6 +11,29 @@ import { logError, logWarning } from "../../workflow-logger.js";
 import { getDbOrNull, openDatabase } from "../engine.js";
 import { TERMINAL_STATUS_SQL } from "../sql-constants.js";
 
+/**
+ * Optional override for the project-root DB open inside reconcileWorktreeDb.
+ * Production leaves this null so the real engine.openDatabase runs; tests
+ * inject a function returning false to deterministically exercise the
+ * cannot-open-main-DB branch (reconcile.ts:82), which is otherwise unreachable
+ * without a contrived provider/OS fault (openDatabase rethrows on real failures
+ * rather than returning false across providers).
+ * @internal
+ */
+let _mainDbOpenerFn: ((mainDbPath: string) => boolean) | null = null;
+
+export function _setMainDbOpenerFnForTests(
+  fn: ((mainDbPath: string) => boolean) | null,
+): () => void {
+  const previous = _mainDbOpenerFn;
+  _mainDbOpenerFn = fn;
+  return () => { _mainDbOpenerFn = previous; };
+}
+
+function openMainDb(mainDbPath: string): boolean {
+  return _mainDbOpenerFn ? _mainDbOpenerFn(mainDbPath) : openDatabase(mainDbPath);
+}
+
 export function copyWorktreeDb(srcDbPath: string, destDbPath: string): boolean {
   try {
     if (!existsSync(srcDbPath)) return false;
@@ -77,7 +100,7 @@ export function reconcileWorktreeDb(
     return zero;
   }
   if (!getDbOrNull()!) {
-    const opened = openDatabase(mainDbPath);
+    const opened = openMainDb(mainDbPath);
     if (!opened) {
       logError("db", "worktree DB reconciliation failed: cannot open main DB");
       return zero;

package/src/resources/extensions/gsd/db-workspace.ts

@@ -5,6 +5,7 @@ import { existsSync } from "node:fs";
 import { dirname } from "node:path";
 
 import type { GsdWorkspace, MilestoneScope } from "./workspace.js";
+import type { DbAdapter } from "./db-adapter.js";
 import {
   backupDatabaseSnapshot,
   checkpointDatabase,
@@ -18,6 +19,7 @@ import {
   openDatabase,
   openDatabaseByScope,
   openDatabaseByWorkspace,
+  openIsolatedDatabase,
   refreshOpenDatabaseFromDisk,
   vacuumDatabase,
   wasDbOpenAttempted,
@@ -113,6 +115,19 @@ export function openWorkflowDatabasePath(path: string): boolean {
   return openDatabase(path);
 }
 
+/**
+ * Open an isolated database connection for read-only observation without
+ * displacing the active workflow session's global DB handle. The caller is
+ * responsible for calling `adapter.close()` when done.
+ *
+ * Use this for background observers (e.g. the parallel monitor overlay) that
+ * need to query a database on a 5s tick without interfering with the primary
+ * connection. Returns null if the connection cannot be opened.
+ */
+export function openWorkflowDatabaseIsolated(path: string): DbAdapter | null {
+  return openIsolatedDatabase(path);
+}
+
 export function openWorkflowDatabaseByWorkspace(workspace: GsdWorkspace): boolean {
   return openDatabaseByWorkspace(workspace);
 }