@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/dist/resources/extensions/gsd/compat/compat-marker.js

@@ -0,0 +1,172 @@
+// Project/App: gsd-pi
+// File Purpose: gsd-core ↔ gsd-pi compatibility marker (`.gsd/.compat.json`).
+//
+// Records per-projection content hashes so the ADR-017 reconcile pipeline can
+// distinguish gsd-pi's own writes (expected) from external edits made by gsd-core
+// (drift to import). gsd-core is oblivious to this file and ignores it.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Current marker schema version. Bump on breaking format changes + migrate. */
+export const COMPAT_MARKER_SCHEMA = 2;
+/** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
+export const EMPTY_MARKER = {
+    schema: COMPAT_MARKER_SCHEMA,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: false, layout: null, projections: {}, passthrough: {} },
+    piVersion: "",
+};
+export function compatMarkerPath(basePath) {
+    return join(basePath, ".gsd", ".compat.json");
+}
+/**
+ * Normalize markdown content before hashing so cosmetic differences (trailing
+ * whitespace, CRLF) don't produce false-positive drift. Conservative: only
+ * transforms that are provably round-trippable through gsd-pi's projection.
+ */
+export function normalizeForHash(content) {
+    return content.replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n");
+}
+export function computeProjectionSha(content) {
+    return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
+}
+/**
+ * Read & validate the marker. A missing marker → EMPTY_MARKER (treat every
+ * projection as external on next reconcile). A malformed marker is quarantined
+ * to `.compat.json.bad-<ts>` (never overwrite without backup) then returns
+ * EMPTY_MARKER. A schema-mismatch returns EMPTY_MARKER (forward-compat: refuse
+ * to act on a future format we don't understand).
+ */
+export function readCompatMarker(basePath) {
+    const path = compatMarkerPath(basePath);
+    if (!existsSync(path))
+        return emptyMarker();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        return emptyMarker();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        quarantine(basePath, raw);
+        return emptyMarker();
+    }
+    if (!isValidMarker(parsed)) {
+        quarantine(basePath, raw);
+        return emptyMarker();
+    }
+    // Promote older markers by defaulting absent fields. Schema 1 → 2 only adds
+    // the optional `planning` field; treat its absence as planning-inactive so
+    // existing PR #802 users upgrade transparently. (A future schema 3 would
+    // need an explicit migration here; for now anything that passes isValidMarker
+    // is safe to read.)
+    if (!parsed.planning) {
+        parsed.planning = { active: false, layout: null, projections: {}, passthrough: {} };
+    }
+    return parsed;
+}
+/**
+ * Fresh deep copy of EMPTY_MARKER. Callers mutate the returned `projections`
+ * object (e.g. repair refreshes an entry), so a shallow copy would share the
+ * reference and pollute the module constant across calls. Always deep-copy.
+ */
+function emptyMarker() {
+    return {
+        schema: EMPTY_MARKER.schema,
+        lastWriter: EMPTY_MARKER.lastWriter,
+        lastProjectedAt: EMPTY_MARKER.lastProjectedAt,
+        projections: {},
+        planning: { active: false, layout: null, projections: {}, passthrough: {} },
+        piVersion: EMPTY_MARKER.piVersion,
+    };
+}
+/**
+ * Write the marker atomically (write-temp then rename) so a crash mid-write
+ * can't leave a half-written file that next startup would quarantine.
+ */
+export function writeCompatMarker(basePath, marker) {
+    const path = compatMarkerPath(basePath);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+    renameSync(tmp, path);
+}
+function quarantine(basePath, raw) {
+    const path = compatMarkerPath(basePath);
+    const badPath = `${path}.bad-${Date.now()}`;
+    try {
+        mkdirSync(dirname(badPath), { recursive: true });
+        try {
+            renameSync(path, badPath);
+        }
+        catch {
+            writeFileSync(badPath, raw, "utf-8");
+            unlinkSync(path);
+        }
+    }
+    catch {
+        // Best-effort: if we can't quarantine, leave the original in place — next
+        // read will quarantine. Never throw out of marker I/O.
+    }
+}
+function isValidProjectionEntry(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const e = x;
+    if (typeof e.sha !== "string")
+        return false;
+    if (!Array.isArray(e.entities) || !e.entities.every((s) => typeof s === "string"))
+        return false;
+    return true;
+}
+function isValidProjectionMap(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    for (const v of Object.values(x)) {
+        if (!isValidProjectionEntry(v))
+            return false;
+    }
+    return true;
+}
+function isValidPlanningMarker(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const p = x;
+    if (typeof p.active !== "boolean")
+        return false;
+    if (p.layout !== null &&
+        !["flat-phases", "multi-milestone", "legacy-milestone-dir"].includes(p.layout)) {
+        return false;
+    }
+    if (!isValidProjectionMap(p.projections))
+        return false;
+    if (!isValidProjectionMap(p.passthrough))
+        return false;
+    return true;
+}
+function isValidMarker(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const m = x;
+    if (m.lastWriter !== "gsd-pi")
+        return false;
+    if (typeof m.schema !== "number")
+        return false;
+    if (typeof m.lastProjectedAt !== "string")
+        return false;
+    if (typeof m.piVersion !== "string")
+        return false;
+    if (!isValidProjectionMap(m.projections))
+        return false;
+    // planning is optional; when present, must validate.
+    if (m.planning !== undefined && !isValidPlanningMarker(m.planning))
+        return false;
+    return true;
+}

package/dist/resources/extensions/gsd/compat/index.js

@@ -0,0 +1,3 @@
+// Project/App: gsd-pi
+// File Purpose: Public exports for the gsd-core compat module.
+export { COMPAT_MARKER_SCHEMA, EMPTY_MARKER, compatMarkerPath, computeProjectionSha, normalizeForHash, readCompatMarker, writeCompatMarker, } from "./compat-marker.js";

package/dist/resources/extensions/gsd/compat/planning-compat.js

@@ -0,0 +1,142 @@
+// 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, } from "./compat-marker.js";
+import { logWarning } from "../workflow-logger.js";
+export function isPlanningPassthroughRelPath(relPath) {
+    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) {
+    const gsdDir = join(basePath, ".gsd");
+    return (existsSync(gsdDir) &&
+        readdirSync(gsdDir).some((name) => !name.startsWith(".") && !KNOWN_NON_CONTENT_FILES.has(name)));
+}
+export function walkPlanningRelPaths(planningDir, prefix = "") {
+    const paths = [];
+    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, writes) {
+    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);
+}
+/**
+ * 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, options) {
+    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 = 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.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/dist/resources/extensions/gsd/config-overlay.js

@@ -15,7 +15,7 @@ function collectConfigSections(options) {
     const globalPrefs = loadGlobalGSDPreferences();
     const projectPrefs = loadProjectGSDPreferences(options?.basePath);
     const loadOpts = options?.availableModelIds
-        ? { availableModelIds: options.availableModelIds }
+        ? { availableModelIds: options.availableModelIds, preferredModelId: options.preferredModelId }
         : undefined;
     const effective = loadEffectiveGSDPreferences(options?.basePath, loadOpts);
     const prefs = effective?.preferences;
@@ -46,7 +46,7 @@ function collectConfigSections(options) {
     ];
     const modelRows = [];
     for (const [label, unitType] of unitTypes) {
-        const resolved = resolveModelWithFallbacksForUnit(unitType, options?.basePath, options?.availableModelIds);
+        const resolved = resolveModelWithFallbacksForUnit(unitType, options?.basePath, options?.availableModelIds, options?.preferredModelId);
         if (resolved) {
             let val = resolved.primary;
             if (resolved.fallbacks.length > 0) {

package/dist/resources/extensions/gsd/consent-question.js

@@ -170,6 +170,9 @@ export function classifyQuestion(input) {
 /**
  * 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;
@@ -181,6 +184,8 @@ export function classifyQuestion(input) {
  */
 export function evaluateAnswer(options) {
     const { question, details } = options;
+    if (details.timed_out)
+        return "timeout";
     if (details.cancelled)
         return "cancelled";
     const { kind } = classifyQuestion({ id: question.id, options: question.options });
@@ -203,6 +208,7 @@ export function evaluateAnswer(options) {
 }
 const OUTCOME_PRECEDENCE = [
     "cancelled",
+    "timeout",
     "waiting",
     "declined",
     "verified",
@@ -217,6 +223,12 @@ const OUTCOME_PRECEDENCE = [
  * a no-op, so it reports "answered" here.
  */
 export function evaluateAskUserQuestionsRound(questions, details) {
+    // 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 = "answered";

package/dist/resources/extensions/gsd/consent-verdict.js

@@ -44,13 +44,23 @@ export function hasNotesValue(notes) {
 /**
  * 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, details) {
+    if (details.timed_out)
+        return "timeout";
     if (details.cancelled)
         return "cancelled";
     const questionId = typeof question.id === "string" ? question.id : "";

package/dist/resources/extensions/gsd/dashboard-overlay.js

@@ -12,14 +12,16 @@ import { loadFile } from "./files.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getAutoDashboardData } from "./auto.js";
+import { getAutoRuntimeSnapshot } from "./auto-runtime-state.js";
 import { getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice, aggregateByModel, aggregateCacheHitRate, formatCost, formatTokenCount, formatCostProjection, getPromptSizeStats, } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { countPendingCaptures } from "./captures.js";
 import { getActiveWorktreeName } from "./worktree-session-state.js";
 import { getWorkerBatches, hasActiveWorkers } from "../subagent/worker-registry.js";
 import { formatDuration, padRight, joinColumns, centerLine, fitColumns, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
 import { estimateTimeRemaining } from "./auto-dashboard.js";
 import { computeProgressScore } from "./progress-score.js";
-import { runEnvironmentChecks } from "./doctor-environment.js";
+import { runEnvironmentChecksAsync } from "./doctor-environment.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { renderDialogFrame, renderKeyHints } from "./tui/render-kit.js";
 export function unitLabel(type) {
@@ -60,6 +62,9 @@ export class GSDDashboardOverlay {
     loading = true;
     loadedDashboardIdentity;
     refreshInFlight = null;
+    envRefreshInFlight = null;
+    cachedEnvBasePath;
+    cachedEnvIssues = [];
     disposed = false;
     resizeHandler = null;
     cachedMetrics = null;
@@ -102,28 +107,89 @@ export class GSDDashboardOverlay {
             currentUnit,
         ].join("|");
     }
+    refreshVolatileDashboardData(snapshot = getAutoRuntimeSnapshot()) {
+        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,
+        };
+    }
     async refreshDashboard(initial = false) {
         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) {
             this.loading = false;
         }
+        this.scheduleEnvironmentRefresh(this.dashData.basePath || process.cwd());
         if (identityChanged) {
             this.invalidate();
         }
         this.tui.requestRender();
     }
+    scheduleEnvironmentRefresh(basePath) {
+        if (this.cachedEnvBasePath !== basePath) {
+            this.cachedEnvBasePath = basePath;
+            this.cachedEnvIssues = [];
+            this.invalidate();
+        }
+        if (this.envRefreshInFlight || this.disposed)
+            return;
+        this.envRefreshInFlight = this.refreshEnvironmentHealth(basePath)
+            .finally(() => {
+            this.envRefreshInFlight = null;
+        });
+    }
+    async refreshEnvironmentHealth(basePath) {
+        try {
+            const envResults = await runEnvironmentChecksAsync(basePath);
+            if (this.disposed || this.cachedEnvBasePath !== basePath)
+                return;
+            this.cachedEnvIssues = envResults.filter(r => r.status !== "ok");
+            this.invalidate();
+            this.tui.requestRender();
+        }
+        catch {
+            // Non-fatal — keep last known environment issues
+        }
+    }
     async loadData() {
         const base = this.dashData.basePath || process.cwd();
         try {
@@ -504,8 +570,7 @@ export class GSDDashboardOverlay {
             }
         }
         // Environment health section (#1221) — only show issues
-        const envResults = runEnvironmentChecks(this.dashData.basePath || process.cwd());
-        const envIssues = envResults.filter(r => r.status !== "ok");
+        const envIssues = this.cachedEnvIssues;
         if (envIssues.length > 0) {
             lines.push(blank());
             lines.push(hr());

package/dist/resources/extensions/gsd/db/engine.js

@@ -19,7 +19,7 @@ import { createCoordinationTablesV24 } from "../db-coordination-schema.js";
 import { createDbConnectionCache } from "../db-connection-cache.js";
 import { backupDatabaseBeforeMigration, isMigrationBackupError } from "../db-migration-backup.js";
 import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, applyMigrationV29RepositoryTargets, } from "../db-migration-steps.js";
-import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "../db-memory-fts-schema.js";
+import { isMemoriesFtsAvailableSchema, rebuildMemoriesFtsSchemaOnce, tryCreateMemoriesFtsSchema, } from "../db-memory-fts-schema.js";
 import { createDbOpenState } from "../db-open-state.js";
 import { createRuntimeKvTableV25 } from "../db-runtime-kv-schema.js";
 import { getCurrentSchemaVersion, recordSchemaVersion } from "../db-schema-metadata.js";
@@ -101,6 +101,9 @@ function initSchema(db, fileBacked, dbPath) {
         throw err;
     }
     migrateSchema(db, dbPath);
+    rebuildMemoriesFtsSchemaOnce(db, {
+        onRebuildFailed: (message) => logWarning("db", message),
+    });
 }
 export function _isLikelyWslDrvFsPathForTest(dbPath) {
     if (!dbPath || process.platform !== "linux")
@@ -615,6 +618,33 @@ export function closeDatabase() {
     // failed open doesn't persist into the next open attempt or status check.
     _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) {
+    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.
  *