gsd-pi 2.76.0-dev.82e249f7b → 2.76.0-dev.fe143342a

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -204,6 +204,41 @@ export function registerHooks(pi, ecosystemHandlers) {
             nextAction: `Resume task ${state.activeTask.id}: ${state.activeTask.title}.`,
         }));
     });
+    // Context-mode snapshot: write .gsd/last-snapshot.md before compaction so
+    // agents can call gsd_resume (or Read the file) to re-orient. Opt-in via
+    // preferences.context_mode.enabled. Runs after the auto-cancel handler
+    // above — if that one returned cancel:true, pi still fires us but the
+    // compaction won't actually happen; the snapshot is still useful then,
+    // since auto may pause and resume later.
+    pi.on("session_before_compact", async () => {
+        try {
+            const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+            const { isContextModeEnabled } = await import("../preferences-types.js");
+            const prefs = loadEffectiveGSDPreferences();
+            if (!isContextModeEnabled(prefs?.preferences))
+                return;
+            const { writeCompactionSnapshot } = await import("../compaction-snapshot.js");
+            const { ensureDbOpen } = await import("./dynamic-tools.js");
+            await ensureDbOpen();
+            const basePath = process.cwd();
+            let activeContext = null;
+            try {
+                const state = await deriveState(basePath);
+                if (state.activeMilestone && state.activeSlice && state.activeTask) {
+                    activeContext =
+                        `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
+                            (state.activeTask.title ? ` — ${state.activeTask.title}` : "");
+                }
+            }
+            catch {
+                /* non-fatal */
+            }
+            writeCompactionSnapshot(basePath, { activeContext });
+        }
+        catch (err) {
+            safetyLogWarning("context-mode", `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
     pi.on("session_shutdown", async (_event, ctx) => {
         if (isParallelActive()) {
             try {

package/dist/resources/extensions/gsd/compaction-snapshot.js

@@ -0,0 +1,121 @@
+// GSD Compaction Snapshot — writes a ≤2 KB markdown digest of durable
+// project state before the session context is compacted. On resume, an
+// agent can `gsd_resume` (or Read .gsd/last-snapshot.md) to re-orient
+// without re-deriving the same memories.
+//
+// Inspired by mksglu/context-mode. Independent implementation.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getActiveMemoriesRanked } from "./memory-store.js";
+import { listExecHistory } from "./exec-history.js";
+export const DEFAULT_SNAPSHOT_BYTES = 2048;
+export const SNAPSHOT_FILENAME = "last-snapshot.md";
+/**
+ * Build a priority-tiered markdown snapshot. Pure — no I/O. Tiers:
+ *   1. Active context (if any)
+ *   2. Top memories by rank
+ *   3. Recent exec runs (failures highlighted)
+ * The result is guaranteed to be <= opts.maxBytes (truncated with an
+ * ellipsis marker if necessary).
+ */
+export function buildSnapshot(sources, opts = {}) {
+    const maxBytes = opts.maxBytes ?? DEFAULT_SNAPSHOT_BYTES;
+    const maxMemories = opts.maxMemories ?? 6;
+    const maxExec = opts.maxExec ?? 5;
+    const lines = [];
+    lines.push(`# GSD context snapshot (${sources.generatedAt.toISOString()})`);
+    lines.push("");
+    if (sources.activeContext && sources.activeContext.trim().length > 0) {
+        lines.push("## Active context");
+        lines.push(sources.activeContext.trim());
+        lines.push("");
+    }
+    const memories = sources.memories.slice(0, maxMemories);
+    if (memories.length > 0) {
+        lines.push("## Top project memories");
+        for (const memory of memories) {
+            lines.push(`- [${memory.id}] (${memory.category}) ${memory.content.trim()}`);
+        }
+        lines.push("");
+    }
+    const exec = sources.execHistory.slice(0, maxExec);
+    if (exec.length > 0) {
+        lines.push("## Recent gsd_exec runs");
+        for (const entry of exec) {
+            const status = entry.timed_out
+                ? "timeout"
+                : entry.exit_code === null
+                    ? "exit:null"
+                    : `exit:${entry.exit_code}`;
+            const purpose = entry.purpose ? ` — ${entry.purpose}` : "";
+            lines.push(`- [${entry.id}] ${entry.runtime} ${status}${purpose}`);
+        }
+        lines.push("");
+    }
+    if (memories.length === 0 && exec.length === 0 && !sources.activeContext) {
+        lines.push("_No durable memories, active context, or exec history to surface._");
+    }
+    return enforceByteCap(lines.join("\n").trimEnd(), maxBytes);
+}
+function enforceByteCap(input, maxBytes) {
+    if (Buffer.byteLength(input, "utf-8") <= maxBytes)
+        return input;
+    const marker = "\n…[truncated]";
+    const markerBytes = Buffer.byteLength(marker, "utf-8");
+    const budget = Math.max(0, maxBytes - markerBytes);
+    // Walk backwards until the trimmed string fits. utf-8 is variable-width;
+    // naive char slicing is safe for ASCII but may split a multi-byte char.
+    // Guard by decoding the trimmed Buffer and relying on the replacement-char
+    // fallback in TextDecoder (implicit via toString).
+    const buf = Buffer.from(input, "utf-8").subarray(0, budget);
+    return `${buf.toString("utf-8")}${marker}`;
+}
+export function writeCompactionSnapshot(baseDir, opts = {}) {
+    const memories = safeGetMemories();
+    const execHistory = safeListExec(baseDir);
+    const content = buildSnapshot({
+        memories,
+        execHistory,
+        generatedAt: (opts.now ?? (() => new Date()))(),
+        activeContext: opts.activeContext ?? null,
+    }, opts);
+    const gsdDir = resolve(baseDir, ".gsd");
+    if (!existsSync(gsdDir))
+        mkdirSync(gsdDir, { recursive: true });
+    const path = resolve(gsdDir, SNAPSHOT_FILENAME);
+    const finalContent = `${content}\n`;
+    writeFileSync(path, finalContent, "utf-8");
+    return {
+        path,
+        bytes: Buffer.byteLength(finalContent, "utf-8"),
+        memories: memories.length,
+        execRuns: execHistory.length,
+    };
+}
+export function readCompactionSnapshot(baseDir) {
+    const path = resolve(baseDir, ".gsd", SNAPSHOT_FILENAME);
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function safeGetMemories() {
+    try {
+        return getActiveMemoriesRanked(12);
+    }
+    catch {
+        return [];
+    }
+}
+function safeListExec(baseDir) {
+    try {
+        return listExecHistory(baseDir);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/resources/extensions/gsd/error-classifier.js

@@ -22,12 +22,19 @@ const PERMANENT_RE = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|bill
 // Include provider-specific quota-window phrasing like:
 // - "You've hit your limit"
 // - "usage limit" / "quota reached"
-const RATE_LIMIT_RE = /rate.?limit|too many requests|429|hit your limit|usage limit|quota (?:reached|hit)|limit.*resets?/i;
+// - "out of extra usage"
+const RATE_LIMIT_RE = /rate.?limit|too many requests|429|hit your limit|usage limit|out of extra usage|quota (?:reached|hit)|limit.*resets?/i;
 // OpenRouter affordability-style quota errors should be treated as transient
 // so core retry logic can lower maxTokens and continue in-session.
 const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient credits|not enough credits|fewer max_tokens/i;
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns|unexpected eof/i;
-const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
+// "Stream idle timeout" and "partial response received" are emitted by the SDK/harness
+// for mid-stream disconnects. Both indicate a transient network-level interruption.
+// See: https://github.com/gsd-build/gsd-2/issues/4558
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received/i;
+// Context overflow errors (context window/length exceeded) should be treated as server-class
+// transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
+// See: https://github.com/gsd-build/gsd-2/issues/4528
+const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
 const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".

package/dist/resources/extensions/gsd/exec-history.js

@@ -0,0 +1,120 @@
+// GSD Exec History — read-side helpers for the exec sandbox.
+//
+// Pure I/O: scans `.gsd/exec/*.meta.json` under a base directory and
+// returns lightweight records. Used by the gsd_exec_search tool and
+// any future compaction-snapshot enrichment.
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+function listMetaFiles(baseDir) {
+    const dir = resolve(baseDir, ".gsd", "exec");
+    try {
+        return readdirSync(dir)
+            .filter((name) => name.endsWith(".meta.json"))
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+function safeReadMeta(path) {
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.id !== "string" || typeof parsed.runtime !== "string")
+            return null;
+        return {
+            id: parsed.id,
+            runtime: parsed.runtime,
+            purpose: typeof parsed.purpose === "string" ? parsed.purpose : null,
+            started_at: typeof parsed.started_at === "string" ? parsed.started_at : "",
+            finished_at: typeof parsed.finished_at === "string" ? parsed.finished_at : "",
+            duration_ms: typeof parsed.duration_ms === "number" ? parsed.duration_ms : 0,
+            exit_code: typeof parsed.exit_code === "number" ? parsed.exit_code : null,
+            signal: typeof parsed.signal === "string" ? parsed.signal : null,
+            timed_out: parsed.timed_out === true,
+            stdout_bytes: typeof parsed.stdout_bytes === "number" ? parsed.stdout_bytes : 0,
+            stderr_bytes: typeof parsed.stderr_bytes === "number" ? parsed.stderr_bytes : 0,
+            stdout_truncated: parsed.stdout_truncated === true,
+            stderr_truncated: parsed.stderr_truncated === true,
+            stdout_path: path.replace(/\.meta\.json$/, ".stdout"),
+            stderr_path: path.replace(/\.meta\.json$/, ".stderr"),
+            meta_path: path,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function listExecHistory(baseDir) {
+    const metas = listMetaFiles(baseDir)
+        .map((path) => {
+        let mtime = 0;
+        try {
+            mtime = statSync(path).mtimeMs;
+        }
+        catch {
+            /* ignore */
+        }
+        const entry = safeReadMeta(path);
+        return entry ? { entry, mtime } : null;
+    })
+        .filter((value) => value !== null);
+    metas.sort((a, b) => b.mtime - a.mtime);
+    return metas.map((m) => m.entry);
+}
+function matchesFilters(entry, opts) {
+    if (opts.runtime && entry.runtime !== opts.runtime)
+        return false;
+    if (opts.failing_only) {
+        const failed = entry.timed_out || (entry.exit_code !== 0 && entry.exit_code !== null);
+        if (!failed)
+            return false;
+    }
+    const query = (opts.query ?? "").trim().toLowerCase();
+    if (!query)
+        return true;
+    const haystack = `${entry.id} ${entry.purpose ?? ""}`.toLowerCase();
+    return haystack.includes(query);
+}
+function readDigestPreview(entry, maxChars) {
+    if (!entry.stdout_path || maxChars <= 0)
+        return undefined;
+    try {
+        const size = statSync(entry.stdout_path).size;
+        if (size === 0)
+            return undefined;
+        const readBytes = Math.min(size, maxChars * 4); // 4 bytes/char upper bound for UTF-8
+        const buf = Buffer.allocUnsafe(readBytes);
+        const fd = openSync(entry.stdout_path, "r");
+        try {
+            const bytesRead = readSync(fd, buf, 0, readBytes, Math.max(0, size - readBytes));
+            const text = buf.subarray(0, bytesRead).toString("utf-8");
+            const trimmed = text.trimEnd();
+            return trimmed.length <= maxChars ? trimmed : trimmed.slice(trimmed.length - maxChars);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export function searchExecHistory(baseDir, opts = {}) {
+    const limit = clampLimit(opts.limit, 20, 200);
+    const entries = listExecHistory(baseDir);
+    const filtered = entries.filter((entry) => matchesFilters(entry, opts));
+    return filtered.slice(0, limit).map((entry) => ({
+        entry,
+        digest_preview: readDigestPreview(entry, 300),
+    }));
+}
+function clampLimit(value, fallback, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    if (value < 1)
+        return 1;
+    if (value > max)
+        return max;
+    return Math.floor(value);
+}

package/dist/resources/extensions/gsd/exec-sandbox.js

@@ -0,0 +1,258 @@
+// GSD Exec Sandbox — tool-output sandboxing for sub-sessions.
+//
+// Runs a script in a subprocess and persists stdout/stderr to
+// `.gsd/exec/<id>.{stdout,stderr,meta.json}`. Only a short digest is
+// returned to the calling agent's context, keeping large outputs
+// (e.g. Playwright snapshots, issue dumps) out of the window.
+//
+// Inspired by mksglu/context-mode (Elastic License 2.0). Independent
+// implementation — no upstream code incorporated.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+const ALWAYS_FORWARD_ENV = ["PATH", "HOME"];
+export const EXEC_DEFAULTS = {
+    clampTimeoutMs: 600_000,
+    defaultTimeoutMs: 30_000,
+    stdoutCapBytes: 1_048_576,
+    stderrCapBytes: 262_144,
+    digestChars: 300,
+    envAllowlist: [
+        "LANG",
+        "LC_ALL",
+        "TERM",
+        "TZ",
+        "SHELL",
+        "USER",
+        "LOGNAME",
+        "TMPDIR",
+        "NODE_OPTIONS",
+        "PYTHONPATH",
+        "PYTHONIOENCODING",
+    ],
+};
+function buildChildEnv(opts) {
+    const source = opts.env ?? process.env;
+    const out = {};
+    const allowed = new Set([...ALWAYS_FORWARD_ENV, ...opts.env_allowlist]);
+    for (const key of allowed) {
+        const value = source[key];
+        if (typeof value === "string")
+            out[key] = value;
+    }
+    return out;
+}
+function clampTimeout(request, opts) {
+    const requested = typeof request.timeout_ms === "number" && Number.isFinite(request.timeout_ms)
+        ? Math.floor(request.timeout_ms)
+        : opts.default_timeout_ms;
+    if (requested < 1)
+        return 1;
+    if (requested > opts.clamp_timeout_ms)
+        return opts.clamp_timeout_ms;
+    return requested;
+}
+function resolveCommand(runtime) {
+    switch (runtime) {
+        case "bash":
+            return { cmd: "bash", args: ["-c"] };
+        case "node":
+            return { cmd: process.execPath, args: ["-e"] };
+        case "python":
+            return { cmd: "python3", args: ["-c"] };
+    }
+}
+function tail(buf, chars) {
+    if (chars <= 0)
+        return "";
+    const text = buf.toString("utf-8");
+    return text.length <= chars ? text : text.slice(text.length - chars);
+}
+/**
+ * Run a script in a subprocess, capture stdout/stderr to files under
+ * `.gsd/exec/<id>.{stdout,stderr,meta.json}`, and return an `ExecSandboxResult`
+ * containing the digest plus metadata.
+ *
+ * Errors from spawn failures resolve (not reject) with `exit_code=null`.
+ * The function is pure with respect to its inputs — no global state beyond
+ * filesystem writes under `baseDir`.
+ */
+export function runExecSandbox(request, opts) {
+    return new Promise((resolveP) => {
+        const id = (opts.generateId ?? defaultGenerateId)();
+        const now = (opts.now ?? (() => new Date()))();
+        const execDir = resolve(opts.baseDir, ".gsd", "exec");
+        if (!existsSync(execDir))
+            mkdirSync(execDir, { recursive: true });
+        const stdoutPath = resolve(execDir, `${id}.stdout`);
+        const stderrPath = resolve(execDir, `${id}.stderr`);
+        const metaPath = resolve(execDir, `${id}.meta.json`);
+        const timeoutMs = clampTimeout(request, opts);
+        const { cmd, args } = resolveCommand(request.runtime);
+        const env = buildChildEnv(opts);
+        const useProcessGroup = process.platform !== "win32";
+        const started = Date.now();
+        let child;
+        try {
+            child = spawn(cmd, [...args, request.script], {
+                cwd: opts.baseDir,
+                env,
+                stdio: ["ignore", "pipe", "pipe"],
+                ...(useProcessGroup ? { detached: true } : {}),
+            });
+        }
+        catch (err) {
+            const duration = Date.now() - started;
+            const message = err instanceof Error ? err.message : String(err);
+            writeFileSync(stdoutPath, "");
+            writeFileSync(stderrPath, `spawn error: ${message}\n`);
+            const result = {
+                id,
+                runtime: request.runtime,
+                exit_code: null,
+                signal: null,
+                timed_out: false,
+                duration_ms: duration,
+                stdout_bytes: 0,
+                stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
+                stdout_truncated: false,
+                stderr_truncated: false,
+                stdout_path: stdoutPath,
+                stderr_path: stderrPath,
+                meta_path: metaPath,
+                digest: `[spawn error: ${message}]`,
+            };
+            writeMeta(metaPath, result, request, now);
+            resolveP(result);
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        child.stdout?.on("data", (chunk) => {
+            const remaining = opts.stdout_cap_bytes - stdoutBytes;
+            if (remaining <= 0) {
+                stdoutTruncated = true;
+                return;
+            }
+            if (chunk.length <= remaining) {
+                stdoutChunks.push(chunk);
+                stdoutBytes += chunk.length;
+            }
+            else {
+                stdoutChunks.push(chunk.subarray(0, remaining));
+                stdoutBytes += remaining;
+                stdoutTruncated = true;
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            const remaining = opts.stderr_cap_bytes - stderrBytes;
+            if (remaining <= 0) {
+                stderrTruncated = true;
+                return;
+            }
+            if (chunk.length <= remaining) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            }
+            else {
+                stderrChunks.push(chunk.subarray(0, remaining));
+                stderrBytes += remaining;
+                stderrTruncated = true;
+            }
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (useProcessGroup && child.pid != null) {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch {
+                    child.kill("SIGKILL");
+                }
+            }
+            else {
+                child.kill("SIGKILL");
+            }
+        }, timeoutMs);
+        timer.unref?.();
+        const finalize = (exitCode, signal) => {
+            clearTimeout(timer);
+            const duration = Date.now() - started;
+            const stdoutBuf = Buffer.concat(stdoutChunks);
+            const stderrBuf = Buffer.concat(stderrChunks);
+            const stdoutSuffix = stdoutTruncated ? "\n[truncated: stdout cap reached]\n" : "";
+            const stderrSuffix = stderrTruncated ? "\n[truncated: stderr cap reached]\n" : "";
+            writeFileSync(stdoutPath, Buffer.concat([stdoutBuf, Buffer.from(stdoutSuffix, "utf-8")]));
+            writeFileSync(stderrPath, Buffer.concat([stderrBuf, Buffer.from(stderrSuffix, "utf-8")]));
+            const digestBody = tail(stdoutBuf, opts.digest_chars);
+            const digest = digestBody.length > 0
+                ? digestBody
+                : timedOut
+                    ? "[no stdout — timed out]"
+                    : stderrBuf.length > 0
+                        ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
+                        : "[no output]";
+            const result = {
+                id,
+                runtime: request.runtime,
+                exit_code: exitCode,
+                signal,
+                timed_out: timedOut,
+                duration_ms: duration,
+                stdout_bytes: stdoutBytes,
+                stderr_bytes: stderrBytes,
+                stdout_truncated: stdoutTruncated,
+                stderr_truncated: stderrTruncated,
+                stdout_path: stdoutPath,
+                stderr_path: stderrPath,
+                meta_path: metaPath,
+                digest,
+            };
+            writeMeta(metaPath, result, request, now);
+            resolveP(result);
+        };
+        child.on("error", (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            const line = `child error: ${message}\n`;
+            const remaining = opts.stderr_cap_bytes - stderrBytes;
+            if (remaining > 0) {
+                const chunk = Buffer.from(line, "utf-8").subarray(0, remaining);
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+                if (chunk.length < Buffer.byteLength(line, "utf-8"))
+                    stderrTruncated = true;
+            }
+        });
+        child.on("close", (code, signal) => finalize(code, signal));
+    });
+}
+function defaultGenerateId() {
+    return randomUUID();
+}
+function writeMeta(path, result, request, now) {
+    const meta = {
+        id: result.id,
+        runtime: result.runtime,
+        purpose: request.purpose ?? null,
+        script_chars: request.script.length,
+        started_at: now.toISOString(),
+        finished_at: new Date(now.getTime() + result.duration_ms).toISOString(),
+        exit_code: result.exit_code,
+        signal: result.signal,
+        timed_out: result.timed_out,
+        duration_ms: result.duration_ms,
+        stdout_bytes: result.stdout_bytes,
+        stderr_bytes: result.stderr_bytes,
+        stdout_truncated: result.stdout_truncated,
+        stderr_truncated: result.stderr_truncated,
+        stdout_path: result.stdout_path,
+        stderr_path: result.stderr_path,
+    };
+    writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
+}

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

@@ -495,7 +495,9 @@ function initSchema(db, fileBacked) {
         // that fresh installs already have. Add only columns needed by bootstrap
         // indexes so old DBs can open far enough for the normal migration chain.
         ensureBootstrapIndexColumns(db);
-        db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
+        if (columnExists(db, "memories", "scope")) {
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
+        }
         db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
         db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
         db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
@@ -1097,6 +1099,8 @@ let currentPath = null;
 let currentPid = 0;
 let _exitHandlerRegistered = false;
 let _dbOpenAttempted = false;
+let _lastDbError = null;
+let _lastDbPhase = null;
 export function getDbProvider() {
     loadProvider();
     return providerName;
@@ -1113,13 +1117,54 @@ export function isDbAvailable() {
 export function wasDbOpenAttempted() {
     return _dbOpenAttempted;
 }
+export function getDbStatus() {
+    loadProvider();
+    return {
+        available: currentDb !== null,
+        provider: providerName,
+        attempted: _dbOpenAttempted,
+        lastError: _lastDbError,
+        lastPhase: _lastDbPhase,
+    };
+}
 export function openDatabase(path) {
     _dbOpenAttempted = true;
     if (currentDb && currentPath !== path)
         closeDatabase();
     if (currentDb && currentPath === path)
         return true;
-    const rawDb = openRawDb(path);
+    // Reset error state only when a new open attempt is actually going to run.
+    _lastDbError = null;
+    _lastDbPhase = null;
+    let rawDb;
+    let fallbackProvider = null;
+    let fallbackModule = null;
+    try {
+        rawDb = openRawDb(path);
+    }
+    catch (primaryErr) {
+        _lastDbPhase = "open";
+        _lastDbError = primaryErr instanceof Error ? primaryErr : new Error(String(primaryErr));
+        // node:sqlite loaded but failed to open this file — try better-sqlite3 as fallback.
+        if (providerName === "node:sqlite") {
+            try {
+                const mod = _require("better-sqlite3");
+                const Db = (mod && mod.default) ? mod.default : mod;
+                if (typeof Db === "function") {
+                    rawDb = new Db(path);
+                    fallbackProvider = "better-sqlite3";
+                    fallbackModule = Db;
+                    _lastDbError = null;
+                    _lastDbPhase = null;
+                }
+            }
+            catch {
+                // fallback unavailable; surface original error
+            }
+        }
+        if (!rawDb)
+            throw primaryErr;
+    }
     if (!rawDb)
         return false;
     const adapter = createAdapter(rawDb);
@@ -1137,6 +1182,8 @@ export function openDatabase(path) {
                 process.stderr.write("gsd-db: recovered corrupt database via VACUUM\n");
             }
             catch (retryErr) {
+                _lastDbPhase = "vacuum-recovery";
+                _lastDbError = retryErr instanceof Error ? retryErr : new Error(String(retryErr));
                 try {
                     adapter.close();
                 }
@@ -1147,15 +1194,22 @@ export function openDatabase(path) {
             }
         }
         else {
+            _lastDbPhase = "initSchema";
+            _lastDbError = err instanceof Error ? err : new Error(String(err));
             try {
                 adapter.close();
             }
             catch (e) {
-                logWarning("db", `close after VACUUM failed: ${e.message}`);
+                logWarning("db", `close after initSchema failed: ${e.message}`);
             }
             throw err;
         }
     }
+    // Commit fallback provider switch only after open + schema both succeeded.
+    if (fallbackProvider) {
+        providerName = fallbackProvider;
+        providerModule = fallbackModule;
+    }
     currentDb = adapter;
     currentPath = path;
     currentPid = process.pid;
@@ -1194,8 +1248,12 @@ export function closeDatabase() {
         currentDb = null;
         currentPath = null;
         currentPid = 0;
-        _dbOpenAttempted = false;
     }
+    // Reset session-scoped state unconditionally so stale error info from a
+    // failed open doesn't persist into the next open attempt or status check.
+    _dbOpenAttempted = false;
+    _lastDbError = null;
+    _lastDbPhase = null;
 }
 /** Run a full VACUUM — call sparingly (e.g. after milestone completion). */
 export function vacuumDatabase() {