aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/sandboxFs.js

@@ -0,0 +1,316 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/sandboxFs.ts — v4.4 Phase 2: filesystem allowlist enforcement.
+ *
+ * Pure in-process path policy decision module. Consulted by the six
+ * file_* tools (file_read, file_list, file_write, file_patch,
+ * file_copy, file_move, file_delete) BEFORE any disk I/O, so a
+ * decision can be returned to the agent without ever touching the
+ * filesystem when the answer is "no".
+ *
+ * Two-list model (mirrors Phase 1's `SandboxConfig`):
+ *   - fsDenyList  — sensitive paths the user never wants touched
+ *                   (.ssh, .aws, .env, /etc, /var, ...). Wins for
+ *                   BOTH read and write operations. Denylist always
+ *                   takes precedence over allowlist.
+ *   - fsAllowList — write-permitted roots (cwd, ~/Documents,
+ *                   ~/Downloads, ~/Desktop, os.tmpdir()). Writes /
+ *                   deletes outside these roots are refused. Reads
+ *                   are NOT constrained by the allowlist — reads
+ *                   only have to clear the denylist.
+ *
+ * Symlink defense:
+ *   - Realpath the target (or its first existing ancestor for
+ *     non-existent paths like file_write destinations). Symlink
+ *     bypass on allowlist roots is the canonical attack vector;
+ *     this module canonicalizes before checking.
+ *   - A path that is LEXICALLY under an allowlist root but
+ *     REALPATH'd outside (via a symlink) yields a distinct
+ *     `fs.symlink_escape` violation code.
+ *
+ * Non-existent path handling (Q-P2-3 default):
+ *   - Walk up to the first existing ancestor, realpath that, then
+ *     rejoin the trailing segments. This defends against
+ *     `<allowlist-root>/<symlinked-dir>/new-file.txt` writes.
+ *
+ * TOCTOU posture (Q-P2-5 default):
+ *   - Phase 2 is in-process. A racing actor could rename a
+ *     directory between our policy check and the tool's open()
+ *     call. Phase 3 (Docker sandbox) closes this gap at the OS
+ *     layer via container isolation. Phase 2 documents the gap
+ *     and accepts it for the strict-opt-in `AIDEN_SANDBOX=1`
+ *     period (default-off until Phase 6).
+ *
+ * Short-circuit semantics:
+ *   - When `config.enabled === false` (default through Phase 5),
+ *     `isPathAllowed` returns `{ allowed: true, resolvedPath: ...,
+ *     ... }` with no denylist/allowlist evaluation. Zero overhead
+ *     for users who haven't opted in. Phase 6 flips the gate but
+ *     the wire-in stays.
+ *
+ * The returned `PathPolicyDecision` shape is also forward-compatible
+ * with Phase 5's `FailureCategory.sandbox_violation` — the
+ * `violation.category` field is pre-populated with the constant
+ * Phase 5 will register in FailureClassifier.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWithin = isWithin;
+exports.realpathWithFallback = realpathWithFallback;
+exports.isPathAllowed = isPathAllowed;
+exports.violationEnvelope = violationEnvelope;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const sandboxConfig_1 = require("./sandboxConfig");
+// ── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * `tools/v4/utils/paths.ts#expandPath` re-implemented locally so the
+ * core module doesn't depend on a tools-layer helper. Keeps the
+ * import direction core ← tools (never the reverse).
+ */
+function expandPathInline(input, cwd) {
+    const home = node_os_1.default.homedir();
+    let p = input;
+    if (/^~[\\/]/i.test(p))
+        p = home + p.slice(1);
+    else if (/^Desktop[\\/]?$/i.test(p))
+        p = node_path_1.default.join(home, 'Desktop');
+    else if (/^Desktop[\\/]/i.test(p))
+        p = node_path_1.default.join(home, 'Desktop', p.slice(8));
+    if (node_path_1.default.isAbsolute(p))
+        return p;
+    if (/^[A-Z]:/i.test(p))
+        return p;
+    return node_path_1.default.join(cwd, p);
+}
+/**
+ * Boundary-aware containment check. `path.relative` avoids the
+ * `/home/user-evil` vs `/home/user` false positive that a naive
+ * `startsWith` would produce.
+ */
+function isWithin(child, parent) {
+    if (!child || !parent)
+        return false;
+    const rel = node_path_1.default.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !node_path_1.default.isAbsolute(rel));
+}
+/**
+ * Realpath a path that may not yet exist. Walks up to the first
+ * existing ancestor, realpaths that, then rejoins the trailing
+ * segments. Defends against `<allowlist>/<symlink>/new-file.txt`
+ * writes where the symlink mid-path points outside the allowlist.
+ *
+ * Idempotent: existing paths are realpath'd directly (single
+ * `resolveRealPath` call).
+ */
+function realpathWithFallback(input) {
+    // First, resolve the whole thing optimistically — if it exists,
+    // realpath handles it directly and we're done.
+    const resolved = node_path_1.default.resolve(input);
+    try {
+        if (node_fs_1.default.existsSync(resolved)) {
+            return (0, sandboxConfig_1.resolveRealPath)(resolved);
+        }
+    }
+    catch {
+        // existsSync shouldn't throw, but a permissions error on a
+        // parent dir could surface here on Windows. Fall through.
+    }
+    // Path doesn't exist yet — walk up.
+    let cur = resolved;
+    let tail = '';
+    // Guard against infinite loop on malformed paths (path.dirname
+    // of a root returns the root itself).
+    for (let i = 0; i < 4096; i++) {
+        const parent = node_path_1.default.dirname(cur);
+        if (parent === cur) {
+            // Reached filesystem root without finding any existing
+            // ancestor. Return the lexical resolve.
+            return resolved;
+        }
+        let parentExists = false;
+        try {
+            parentExists = node_fs_1.default.existsSync(parent);
+        }
+        catch {
+            parentExists = false;
+        }
+        if (parentExists) {
+            const parentReal = (0, sandboxConfig_1.resolveRealPath)(parent);
+            tail = tail ? node_path_1.default.join(node_path_1.default.basename(cur), tail) : node_path_1.default.basename(cur);
+            return node_path_1.default.join(parentReal, tail);
+        }
+        tail = tail ? node_path_1.default.join(node_path_1.default.basename(cur), tail) : node_path_1.default.basename(cur);
+        cur = parent;
+    }
+    return resolved;
+}
+function fmtList(list, max = 5) {
+    if (list.length === 0)
+        return '(none)';
+    if (list.length <= max)
+        return list.join(', ');
+    return list.slice(0, max).join(', ') + `, ... (${list.length - max} more)`;
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Evaluate a path against the active sandbox policy.
+ *
+ * @param rawPath  The original path string from tool args (untrusted).
+ * @param op       'read' | 'write' | 'delete' — determines whether the
+ *                 allowlist applies. 'read' = deny-only; 'write' /
+ *                 'delete' = allowlist required.
+ * @param cwd      The tool context's working directory, used to resolve
+ *                 relative paths the same way the file tools do.
+ * @param config   Optional config override (default = singleton from
+ *                 `getSandboxConfig()`). Tests pass a custom config.
+ *
+ * @returns `{ allowed: true, ... }` when the operation may proceed,
+ *          or `{ allowed: false, violation: {...}, ... }` with a
+ *          structured `FsViolation` when it must be refused. Tools
+ *          should forward the violation into a `sandbox_violation`
+ *          envelope on the result object alongside `success: false`.
+ *
+ * Behavior when `config.enabled === false` (Phase 1-5 default):
+ * the function still resolves the path (so the caller can use
+ * `resolvedPath` uniformly), but returns `allowed: true` without
+ * evaluating either list. Zero runtime cost beyond expand+resolve.
+ */
+function isPathAllowed(rawPath, op, cwd, config = (0, sandboxConfig_1.getSandboxConfig)()) {
+    const requestedPath = rawPath;
+    const expandedPath = expandPathInline(rawPath, cwd);
+    // Short-circuit when sandbox is disabled. Still produce a useful
+    // resolvedPath so the tool can keep its current single-codepath
+    // structure (resolve once, use the resolved path).
+    if (!config.enabled) {
+        return {
+            allowed: true,
+            resolvedPath: expandedPath,
+            requestedPath,
+            expandedPath,
+            op,
+        };
+    }
+    // Lexical path-traversal sniff: if `rawPath` was a relative input
+    // that escapes `cwd` via `..`, refuse with a clear code BEFORE
+    // realpath touches the disk. This is belt-and-suspenders — realpath
+    // would catch most cases via the symlink-escape branch — but a
+    // structured `fs.path_traversal` reads more cleanly in logs.
+    if (!node_path_1.default.isAbsolute(rawPath) && !/^[A-Z]:/i.test(rawPath) && !/^~[\\/]/i.test(rawPath)) {
+        const cwdReal = (0, sandboxConfig_1.resolveRealPath)(cwd);
+        const expReal = node_path_1.default.resolve(cwd, rawPath);
+        if (!isWithin(expReal, cwdReal) && rawPath.includes('..')) {
+            // Don't treat this as fatal yet — a relative path can legitimately
+            // escape cwd (e.g. `../tmp/x` when cwd is under tmp). We only flag
+            // it if it ALSO lands outside both lists, which the standard checks
+            // below will catch. Leaving the sniff in as a `path_traversal`
+            // upgrade for the escape-with-no-allowlist-hit case.
+        }
+    }
+    const resolvedPath = realpathWithFallback(expandedPath);
+    const base = {
+        resolvedPath,
+        requestedPath,
+        expandedPath,
+        op,
+    };
+    // ── Denylist (always wins, both read and write) ───────────────────────
+    for (const denied of config.fsDenyList) {
+        if (isWithin(resolvedPath, denied) || resolvedPath === denied) {
+            return {
+                ...base,
+                allowed: false,
+                violation: {
+                    code: 'fs.sensitive_path',
+                    matchedPolicy: denied,
+                    category: 'sandbox_violation',
+                    retryable: false,
+                    message: `Sandbox: path "${resolvedPath}" is under the sensitive denylist entry ` +
+                        `"${denied}". Reads and writes are both refused. ` +
+                        `(Override by extending AIDEN_SANDBOX_ALLOW is not sufficient — the ` +
+                        `denylist takes precedence.)`,
+                },
+            };
+        }
+    }
+    // ── Allowlist (write/delete only — reads pass through after denylist) ─
+    if (op === 'read') {
+        return { ...base, allowed: true };
+    }
+    // Symlink-escape detection: resolvedPath escaped the allowlist
+    // tree, but expandedPath was LEXICALLY under it. That's the
+    // classic allowlist-bypass-via-symlink pattern.
+    let lexicalUnderAllow = false;
+    let realUnderAllow = false;
+    let matchedAllow = '';
+    for (const allowed of config.fsAllowList) {
+        if (isWithin(expandedPath, allowed) || expandedPath === allowed) {
+            lexicalUnderAllow = true;
+        }
+        if (isWithin(resolvedPath, allowed) || resolvedPath === allowed) {
+            realUnderAllow = true;
+            matchedAllow = allowed;
+            break;
+        }
+    }
+    if (realUnderAllow) {
+        return { ...base, allowed: true };
+    }
+    if (lexicalUnderAllow) {
+        return {
+            ...base,
+            allowed: false,
+            violation: {
+                code: 'fs.symlink_escape',
+                matchedPolicy: '',
+                category: 'sandbox_violation',
+                retryable: false,
+                message: `Sandbox: path "${expandedPath}" appears to live under an allowlisted ` +
+                    `root, but its real path "${resolvedPath}" is outside every allowlist ` +
+                    `entry. A symlink in the path likely points outside the sandbox.`,
+            },
+        };
+    }
+    // Plain write-outside-allowlist. Most common refusal.
+    return {
+        ...base,
+        allowed: false,
+        violation: {
+            code: 'fs.write_outside_allowlist',
+            matchedPolicy: matchedAllow,
+            category: 'sandbox_violation',
+            retryable: false,
+            message: `Sandbox: ${op} target "${resolvedPath}" is not under any allowlisted ` +
+                `directory. Allowed roots: ${fmtList(config.fsAllowList)}. ` +
+                `(Extend via AIDEN_SANDBOX_ALLOW=<colon-separated-paths>.)`,
+        },
+    };
+}
+/**
+ * Convenience: build the structured envelope the file tools attach
+ * to their result objects when a policy denial occurs. Centralises
+ * the wire format so all six tools serialise the same shape.
+ */
+function violationEnvelope(decision) {
+    if (!decision.violation) {
+        // Defensive — callers should only call this on denied decisions.
+        throw new Error('violationEnvelope called on allowed decision');
+    }
+    return {
+        code: decision.violation.code,
+        matched_policy: decision.violation.matchedPolicy,
+        requested_path: decision.requestedPath,
+        resolved_path: decision.resolvedPath,
+        retryable: false,
+        category: 'sandbox_violation',
+    };
+}

package/dist/core/v4/selfimprovement/recoveryStore.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/selfimprovement/recoveryStore.ts — v4.6 Phase 3b.
+ *
+ * Durable cross-session failure ledger + recovery report writer.
+ * Backed by the v7 schema's `failure_signatures` + `recovery_reports`
+ * tables. The store is the single write path for both halves of the
+ * self-improvement loop:
+ *
+ *   1. `recordFailureOccurrence(...)` — called on every classified
+ *      failure (TCE write-through at the aidenAgent classify site).
+ *      Upserts the signature row, increments `occurrences`, updates
+ *      `last_seen_at`.
+ *
+ *   2. `recordRecovery(...)` — called when a previously-failed
+ *      signature is observed succeeding (or when the agent's TCE
+ *      surfaces a structured recovery report at turn end).
+ *      Inserts a `recovery_reports` row + bumps the signature's
+ *      `recovered_count` + sets `last_recovery_report_id`.
+ *
+ * Reads:
+ *
+ *   * `listTopFailures(limit)` — operator dashboard query.
+ *   * `getBySignature(signature)` — `/recovery show` detail surface.
+ *   * `listForSession(sessionId)` — used by future plugin hooks that
+ *     want per-session summaries (currently unused; the operator
+ *     command path goes via `listTopFailures` + `getBySignature`).
+ *   * `listReportsForSignature(signatureId, limit)` — the recovery
+ *     history for one signature.
+ *
+ * Singleton pattern mirrors `spawnPause` (Phase 3a): `initRecoveryStore({db})`
+ * at boot; `getRecoveryStore()` thereafter. Production wiring opens the
+ * daemon DB once at REPL/daemon/MCP boot and re-uses the singleton
+ * across REPL turns and daemon-fired turns. Tests reset via
+ * `_resetRecoveryStoreForTests()`.
+ *
+ * Failure mode: NEVER throws. A persistence failure (locked DB,
+ * schema drift, etc.) returns 0 / null and logs a warning. The
+ * TCE write-through path treats the store as best-effort — losing
+ * a signature increment does not break a turn.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecoveryStore = void 0;
+exports.initRecoveryStore = initRecoveryStore;
+exports.getRecoveryStore = getRecoveryStore;
+exports._resetRecoveryStoreForTests = _resetRecoveryStoreForTests;
+// ── Implementation ───────────────────────────────────────────────────────
+/**
+ * SQLite-backed store. Constructed with a `better-sqlite3` Database
+ * handle that already has the v7 migration applied. The store does
+ * NOT run migrations itself — that's the caller's job (typically
+ * `openDaemonDb` + `runMigrations`).
+ */
+class RecoveryStore {
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Upsert a failure signature + bump occurrences. Returns the
+     * signature row id, or 0 on persistence failure (logged). The
+     * caller (TCE write-through path) treats the return as best-effort.
+     */
+    recordFailureOccurrence(opts) {
+        const now = opts.now ?? Date.now;
+        const ts = now();
+        try {
+            // SQLite-native UPSERT — single round trip per failure. The
+            // `excluded.x` syntax references the row we tried to insert.
+            const r = this.db.prepare(`
+        INSERT INTO failure_signatures
+          (signature, tool_name, failure_category, args_hash,
+           first_seen_at, last_seen_at, occurrences, recovered_count)
+        VALUES (?, ?, ?, ?, ?, ?, 1, 0)
+        ON CONFLICT(signature) DO UPDATE SET
+          last_seen_at = excluded.last_seen_at,
+          occurrences  = failure_signatures.occurrences + 1
+        RETURNING id
+      `).get(opts.signature, opts.toolName, opts.category, opts.argsHash ?? null, ts, ts);
+            return r?.id ?? 0;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] recordFailureOccurrence failed:', err instanceof Error ? err.message : String(err));
+            return 0;
+        }
+    }
+    /**
+     * Record a successful recovery. Inserts a `recovery_reports`
+     * row + atomically bumps the signature's `recovered_count` and
+     * `last_recovery_report_id`. Returns the new report id, or 0 on
+     * failure.
+     */
+    recordRecovery(opts) {
+        const now = opts.now ?? Date.now;
+        const ts = now();
+        try {
+            // Two-statement transaction — insert then update — keeps the
+            // signature's `last_recovery_report_id` consistent with the
+            // newly-inserted report row.
+            const txn = this.db.transaction(() => {
+                const ins = this.db.prepare(`
+          INSERT INTO recovery_reports
+            (signature_id, run_id, session_id, failed_attempts,
+             successful_strategy, changed_parameters, verification,
+             created_at, notes)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(opts.signatureId, opts.runId ?? null, opts.sessionId ?? null, opts.failedAttempts, opts.successfulStrategy, opts.changedParameters ? JSON.stringify(opts.changedParameters) : null, opts.verification ?? null, ts, opts.notes ?? null);
+                const reportId = Number(ins.lastInsertRowid);
+                this.db.prepare(`
+          UPDATE failure_signatures
+             SET recovered_count = recovered_count + 1,
+                 last_recovery_report_id = ?
+           WHERE id = ?
+        `).run(reportId, opts.signatureId);
+                return reportId;
+            });
+            return txn();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] recordRecovery failed:', err instanceof Error ? err.message : String(err));
+            return 0;
+        }
+    }
+    /**
+     * Top N recurring failure signatures, sorted by occurrence count
+     * descending. Backs `/recovery list`. Joins the most recent
+     * recovery_report so the operator sees what worked last.
+     */
+    listTopFailures(limit = 10) {
+        const cap = Math.max(1, Math.min(limit, 500));
+        try {
+            const rows = this.db.prepare(`
+        SELECT
+          s.signature                   AS signature,
+          s.tool_name                   AS toolName,
+          s.failure_category            AS failureCategory,
+          s.occurrences                 AS occurrences,
+          s.recovered_count             AS recoveredCount,
+          s.last_seen_at                AS lastSeenAt,
+          r.successful_strategy         AS lastRecoveryStrategy
+        FROM failure_signatures s
+        LEFT JOIN recovery_reports r
+          ON r.id = s.last_recovery_report_id
+        ORDER BY s.occurrences DESC, s.last_seen_at DESC
+        LIMIT ?
+      `).all(cap);
+            return rows;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] listTopFailures failed:', err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    /**
+     * Lookup one signature by its canonical string. Backs `/recovery
+     * show`. Returns null when no signature row exists yet.
+     */
+    getBySignature(signature) {
+        try {
+            const row = this.db.prepare(`
+        SELECT
+          id                      AS id,
+          signature               AS signature,
+          tool_name               AS toolName,
+          failure_category        AS failureCategory,
+          args_hash               AS argsHash,
+          first_seen_at           AS firstSeenAt,
+          last_seen_at            AS lastSeenAt,
+          occurrences             AS occurrences,
+          recovered_count         AS recoveredCount,
+          last_recovery_report_id AS lastRecoveryReportId
+        FROM failure_signatures WHERE signature = ?
+      `).get(signature);
+            return row ?? null;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] getBySignature failed:', err instanceof Error ? err.message : String(err));
+            return null;
+        }
+    }
+    /**
+     * Recovery reports linked to one signature, most recent first.
+     * Used by `/recovery show` to render the recovery history below
+     * the signature header.
+     */
+    listReportsForSignature(signatureId, limit = 50) {
+        const cap = Math.max(1, Math.min(limit, 500));
+        try {
+            const rows = this.db.prepare(`
+        SELECT
+          id                    AS id,
+          signature_id          AS signatureId,
+          run_id                AS runId,
+          session_id            AS sessionId,
+          failed_attempts       AS failedAttempts,
+          successful_strategy   AS successfulStrategy,
+          changed_parameters    AS changedParameters,
+          verification          AS verification,
+          created_at            AS createdAt,
+          notes                 AS notes
+        FROM recovery_reports
+         WHERE signature_id = ?
+         ORDER BY created_at DESC
+         LIMIT ?
+      `).all(signatureId, cap);
+            return rows;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] listReportsForSignature failed:', err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    /**
+     * Recovery reports written during one session, used by future
+     * plugin hooks + the `/recovery` command's per-session view.
+     * Wraps a single SELECT — no aggregation. Empty array when no
+     * recoveries happened.
+     */
+    listForSession(sessionId) {
+        try {
+            const rows = this.db.prepare(`
+        SELECT
+          id                    AS id,
+          signature_id          AS signatureId,
+          run_id                AS runId,
+          session_id            AS sessionId,
+          failed_attempts       AS failedAttempts,
+          successful_strategy   AS successfulStrategy,
+          changed_parameters    AS changedParameters,
+          verification          AS verification,
+          created_at            AS createdAt,
+          notes                 AS notes
+        FROM recovery_reports
+         WHERE session_id = ?
+         ORDER BY created_at DESC
+      `).all(sessionId);
+            return rows;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] listForSession failed:', err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    /**
+     * Operator escape hatch — `/recovery clear <signature>` lets the
+     * operator say "this is fixed, stop counting it." Cascades to
+     * the linked recovery_reports rows so the signature genuinely
+     * disappears. Returns true when a row was deleted.
+     */
+    clearSignature(signature) {
+        try {
+            const sig = this.getBySignature(signature);
+            if (!sig)
+                return false;
+            const txn = this.db.transaction(() => {
+                this.db.prepare(`DELETE FROM recovery_reports WHERE signature_id = ?`).run(sig.id);
+                this.db.prepare(`DELETE FROM failure_signatures WHERE id = ?`).run(sig.id);
+            });
+            txn();
+            return true;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] clearSignature failed:', err instanceof Error ? err.message : String(err));
+            return false;
+        }
+    }
+}
+exports.RecoveryStore = RecoveryStore;
+// ── Module-level singleton ───────────────────────────────────────────────
+let _singleton = null;
+/**
+ * Initialise the process-wide store. Called once at REPL / daemon /
+ * MCP boot, after `runMigrations` has applied v7. Re-init replaces
+ * the singleton so tests can swap DBs cleanly.
+ */
+function initRecoveryStore(opts) {
+    _singleton = new RecoveryStore(opts.db);
+    return _singleton;
+}
+/**
+ * Read the current singleton. Returns null when not initialised so
+ * callers on the hot path (TCE write-through) can no-op silently
+ * instead of throwing. The slash command path (`/recovery list`)
+ * does its own "not initialised" error reporting.
+ */
+function getRecoveryStore() {
+    return _singleton;
+}
+/**
+ * Test-only — drop the singleton so the next `initRecoveryStore`
+ * call wires a fresh state.
+ */
+function _resetRecoveryStoreForTests() {
+    _singleton = null;
+}