gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

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

@@ -0,0 +1,227 @@
+// gsd-2 + Auto-mode worker process registry (DB-backed coordination, Phase B)
+//
+// IMPORTANT — naming clarification (codex review LOW N1):
+// This module is the AUTO-MODE PROCESS REGISTRY. It tracks long-running
+// `gsd auto` worker processes for cross-process coordination via the shared
+// SQLite WAL. It is NOT the in-process subagent registry, which lives at
+// `src/resources/extensions/subagent/worker-registry.ts` and tracks dispatched
+// subagent threads within a single process.
+//
+// Both modules use the word "worker" but they are unrelated:
+//   - subagent/worker-registry.ts → ephemeral in-process subagent threads
+//   - db/auto-workers.ts          → durable cross-process auto-mode sessions
+//
+// Single-host invariant: SQLite WAL coordination only works on local disk.
+// NFS / network filesystems break heartbeat semantics. Multi-host execution
+// needs a real coordinator (etcd, Postgres) — out of scope for Phase B.
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { _getAdapter, isDbAvailable, transaction, insertAuditEvent, } from "../gsd-db.js";
+import { normalizeRealPath } from "../paths.js";
+const HEARTBEAT_TTL_SECONDS = 60;
+// Version label is for diagnostics only — embedded in audit_events and
+// workers.version. Bumping this manually on protocol changes is fine; we
+// don't pull it from package.json to avoid module-load filesystem I/O.
+const WORKER_REGISTRY_VERSION = "1";
+/**
+ * Register a new auto-mode worker process. Returns the generated worker_id
+ * for the session to store on its AutoSession.
+ *
+ * The worker is created with `status='active'` and an initial heartbeat
+ * stamp; callers must invoke heartbeatAutoWorker() periodically (e.g. once
+ * per loop iteration) to refresh the TTL.
+ */
+export function registerAutoWorker(opts) {
+    if (!isDbAvailable()) {
+        throw new Error("registerAutoWorker: DB unavailable");
+    }
+    const workerId = `auto-${hostname()}-${process.pid}-${randomUUID().slice(0, 8)}`;
+    const now = new Date().toISOString();
+    transaction(() => {
+        const db = _getAdapter();
+        db.prepare(`INSERT INTO workers (
+        worker_id, host, pid, started_at, version,
+        last_heartbeat_at, status, project_root_realpath
+      ) VALUES (
+        :worker_id, :host, :pid, :started_at, :version,
+        :last_heartbeat_at, 'active', :project_root_realpath
+      )`).run({
+            ":worker_id": workerId,
+            ":host": hostname(),
+            ":pid": process.pid,
+            ":started_at": now,
+            ":version": WORKER_REGISTRY_VERSION,
+            ":last_heartbeat_at": now,
+            ":project_root_realpath": opts.projectRootRealpath,
+        });
+    });
+    insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "worker-registered",
+        ts: now,
+        payload: {
+            workerId,
+            host: hostname(),
+            pid: process.pid,
+            version: WORKER_REGISTRY_VERSION,
+            projectRootRealpath: opts.projectRootRealpath,
+        },
+    });
+    return workerId;
+}
+/**
+ * Refresh the worker's heartbeat. Call once per auto-loop iteration.
+ * Idempotent — silently no-ops if the worker no longer exists (e.g. row was
+ * cleaned up by a janitor).
+ */
+export function heartbeatAutoWorker(workerId) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    db.prepare(`UPDATE workers SET last_heartbeat_at = :now WHERE worker_id = :worker_id AND status = 'active'`).run({ ":now": now, ":worker_id": workerId });
+}
+/**
+ * Mark the worker as crashed. Used by janitors / doctor commands when a
+ * worker's heartbeat has expired beyond the TTL window.
+ */
+export function markWorkerCrashed(workerId) {
+    if (!isDbAvailable())
+        return;
+    const db = _getAdapter();
+    let changes = 0;
+    transaction(() => {
+        const result = db.prepare(`UPDATE workers SET status = 'crashed' WHERE worker_id = :worker_id AND status = 'active'`).run({ ":worker_id": workerId });
+        changes =
+            typeof result.changes === "number"
+                ? result.changes
+                : 0;
+    });
+    if (changes < 1)
+        return;
+    insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "worker-crashed",
+        ts: new Date().toISOString(),
+        payload: { workerId },
+    });
+}
+/**
+ * Mark the worker as stopping. Called from the stopAuto path when the user
+ * cleanly shuts down auto-mode.
+ */
+export function markWorkerStopping(workerId) {
+    if (!isDbAvailable())
+        return;
+    const db = _getAdapter();
+    transaction(() => {
+        db.prepare(`UPDATE workers SET status = 'stopping' WHERE worker_id = :worker_id`).run({ ":worker_id": workerId });
+    });
+}
+/**
+ * Return all workers whose status is 'active' AND whose heartbeat is within
+ * the TTL window. Workers older than the TTL are NOT auto-marked crashed
+ * here — that's a separate janitor responsibility — but they are filtered
+ * out of the active set so callers see a fresh view.
+ */
+export function getActiveAutoWorkers() {
+    if (!isDbAvailable())
+        return [];
+    const db = _getAdapter();
+    const cutoffMs = Date.now() - HEARTBEAT_TTL_SECONDS * 1000;
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const rows = db.prepare(`SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     WHERE status = 'active' AND last_heartbeat_at >= :cutoff
+     ORDER BY started_at`).all({ ":cutoff": cutoffIso });
+    return rows;
+}
+/** Return all worker rows regardless of status or TTL. */
+export function getAllAutoWorkers() {
+    if (!isDbAvailable())
+        return [];
+    const db = _getAdapter();
+    const rows = db.prepare(`SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     ORDER BY started_at`).all();
+    return rows;
+}
+/**
+ * Look up a single worker row. Returns null if no row exists.
+ */
+export function getAutoWorker(workerId) {
+    if (!isDbAvailable())
+        return null;
+    const db = _getAdapter();
+    const row = db.prepare(`SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers WHERE worker_id = :worker_id`).get({ ":worker_id": workerId });
+    return row ?? null;
+}
+/** Test/janitor helper: TTL constant exported for callers to compute expirations. */
+export function autoWorkerHeartbeatTtlSeconds() {
+    return HEARTBEAT_TTL_SECONDS;
+}
+function isWorkerProcessAlive(candidate) {
+    const pid = candidate.pid;
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    if (candidate.host !== hostname())
+        return false;
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EPERM")
+            return true;
+        return false;
+    }
+}
+/**
+ * Phase C pt 2 — find the most recently active worker for a project root
+ * whose heartbeat has lapsed (the "previous crashed session" indicator).
+ *
+ * Used by crash-recovery.ts:readCrashLock to detect when a prior auto-mode
+ * session ended without cleanup. Workers are only treated as stale after
+ * their heartbeat has lapsed and the OS PID liveness check says the process
+ * is no longer alive.
+ *
+ * Returns null if no stale worker exists for this project root.
+ */
+export function findStaleWorkerForProject(projectRootRealpath) {
+    if (!isDbAvailable())
+        return null;
+    const db = _getAdapter();
+    const cutoffMs = Date.now() - HEARTBEAT_TTL_SECONDS * 1000;
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const row = db.prepare(`SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     WHERE project_root_realpath = :project_root
+       AND status = 'active'
+       AND last_heartbeat_at < :cutoff
+     ORDER BY started_at DESC
+     LIMIT 1`).get({ ":project_root": projectRootRealpath, ":cutoff": cutoffIso });
+    if (row && !isWorkerProcessAlive(row))
+        return row;
+    // Older rows and external fixtures may have captured a non-realpath spelling
+    // of the same project root, e.g. /var/... vs /private/var/... on macOS.
+    const canonicalProjectRoot = normalizeRealPath(projectRootRealpath);
+    const staleRows = db.prepare(`SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     WHERE status = 'active'
+       AND last_heartbeat_at < :cutoff
+     ORDER BY started_at DESC`).all({ ":cutoff": cutoffIso });
+    return staleRows.find((candidate) => normalizeRealPath(candidate.project_root_realpath) === canonicalProjectRoot
+        && !isWorkerProcessAlive(candidate)) ?? null;
+}

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

@@ -0,0 +1,105 @@
+// gsd-2 + Worker IPC command queue (DB-backed coordination, Phase B)
+//
+// New infrastructure for dispatcher-to-worker IPC (cancel signals, pause
+// requests, etc.). NOT a replacement for any existing on-disk queue and
+// NOT related to startAutoCommandPolling() in auto.ts (which polls a
+// remote channel like Telegram, not a local file queue).
+//
+// Broadcast semantics (codex review LOW B4):
+// SQLite indexes NULLs in B-trees, so the single index
+// idx_command_queue_pending(target_worker, claimed_at) serves both:
+//   - targeted queries: WHERE target_worker = ?
+//   - broadcast queries: WHERE target_worker IS NULL
+// Workers should poll for both forms (their own ID + broadcasts) on each
+// claim cycle.
+import { _getAdapter, isDbAvailable, transaction, } from "../gsd-db.js";
+/**
+ * Enqueue a command. Returns the new row id. Broadcast commands
+ * (targetWorker=null) will be claimed by exactly one worker — the IPC
+ * model is "single delivery to whoever claims first", not pub-sub.
+ */
+export function enqueueCommand(input) {
+    if (!isDbAvailable()) {
+        throw new Error("enqueueCommand: DB unavailable");
+    }
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    const result = transaction(() => {
+        return db.prepare(`INSERT INTO command_queue (target_worker, command, args_json, enqueued_at)
+       VALUES (:target_worker, :command, :args_json, :enqueued_at)`).run({
+            ":target_worker": input.targetWorker,
+            ":command": input.command,
+            ":args_json": JSON.stringify(input.args ?? {}),
+            ":enqueued_at": now,
+        });
+    });
+    return Number(result.lastInsertRowid ?? 0);
+}
+/**
+ * Atomically claim the next pending command for the given worker. Returns
+ * the claimed row, or null if nothing to claim.
+ *
+ * Polls both targeted (target_worker = workerId) and broadcast
+ * (target_worker IS NULL) queues, oldest-first.
+ */
+export function claimNextCommand(workerId) {
+    if (!isDbAvailable())
+        return null;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    return transaction(() => {
+        // Find the oldest unclaimed command targeted at this worker OR
+        // broadcast. The partial index covers both via NULL-in-B-tree.
+        const row = db.prepare(`SELECT id, target_worker, command, args_json, enqueued_at,
+              claimed_at, claimed_by, completed_at, result_json
+       FROM command_queue
+       WHERE claimed_at IS NULL
+         AND completed_at IS NULL
+         AND (target_worker = :worker_id OR target_worker IS NULL)
+       ORDER BY enqueued_at ASC, id ASC
+       LIMIT 1`).get({ ":worker_id": workerId });
+        if (!row)
+            return null;
+        // Conditional UPDATE — only succeeds if still unclaimed (guards against
+        // races between two workers polling simultaneously).
+        const result = db.prepare(`UPDATE command_queue
+       SET claimed_at = :now, claimed_by = :worker_id
+       WHERE id = :id AND claimed_at IS NULL AND completed_at IS NULL`).run({ ":now": now, ":worker_id": workerId, ":id": row.id });
+        const changes = typeof result.changes === "number"
+            ? result.changes
+            : 0;
+        if (changes !== 1)
+            return null; // lost the race
+        return { ...row, claimed_at: now, claimed_by: workerId };
+    });
+}
+/**
+ * Mark a command complete with optional result payload. Idempotent — if
+ * the command is already completed, the second call is a no-op.
+ */
+export function completeCommand(id, workerId, result) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    db.prepare(`UPDATE command_queue
+     SET completed_at = :now, result_json = :result_json
+     WHERE id = :id
+       AND claimed_by = :worker_id
+       AND completed_at IS NULL`).run({
+        ":id": id,
+        ":worker_id": workerId,
+        ":now": now,
+        ":result_json": result ? JSON.stringify(result) : null,
+    });
+}
+/** Diagnostic helper: read a single row by id. */
+export function getCommand(id) {
+    if (!isDbAvailable())
+        return null;
+    const db = _getAdapter();
+    const row = db.prepare(`SELECT id, target_worker, command, args_json, enqueued_at,
+            claimed_at, claimed_by, completed_at, result_json
+     FROM command_queue WHERE id = :id`).get({ ":id": id });
+    return row ?? null;
+}

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

@@ -0,0 +1,210 @@
+// gsd-2 + Milestone leases with fencing tokens (DB-backed coordination, Phase B)
+//
+// One worker at a time may hold a lease on a given milestone. Leases carry a
+// monotonic fencing token that increments on every successful takeover, so
+// stale workers can be cheaply detected and rejected at write time
+// (unit_dispatches.milestone_lease_token).
+//
+// Codex review BLOCKING B1: claim semantics must atomically handle two
+// distinct cases inside one transaction:
+//   1. First claim (no row exists)         → INSERT with fencing_token=1
+//   2. Takeover (row exists, expired/released) → UPDATE w/ fencing_token+1
+// `INSERT OR ABORT` alone is wrong because the row already exists for any
+// takeover and a plain INSERT cannot succeed.
+import { randomUUID } from "node:crypto";
+import { _getAdapter, isDbAvailable, transaction, insertAuditEvent, } from "../gsd-db.js";
+const LEASE_TTL_SECONDS = 60;
+function isDuplicateLeaseInsertError(err) {
+    const code = err && typeof err === "object" && "code" in err
+        ? String(err.code ?? "")
+        : "";
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/\bFOREIGN KEY\b/i.test(msg)) {
+        return false;
+    }
+    if (code === "SQLITE_CONSTRAINT" || code === "SQLITE_CONSTRAINT_PRIMARYKEY" || code === "SQLITE_CONSTRAINT_UNIQUE") {
+        return true;
+    }
+    return /\bUNIQUE\b|\bPRIMARY KEY\b|\bconstraint failed\b/i.test(msg);
+}
+function ttlExpiry(now) {
+    return new Date(now.getTime() + LEASE_TTL_SECONDS * 1000).toISOString();
+}
+/**
+ * Acquire (or take over an expired) milestone lease for the given worker.
+ *
+ * Atomicity: the entire claim runs inside a single transaction so the
+ * INSERT-vs-UPDATE branch decision can never tear under concurrent claims.
+ * Fencing token is computed by SQL (`fencing_token + 1`), never supplied
+ * by the client. Initial value is 1.
+ *
+ * datetime('now') uses local wall-clock time, so this remains single-host
+ * SQLite WAL coordination only. Cross-host coordination would need a real
+ * coordinator; out of scope for Phase B.
+ */
+export function claimMilestoneLease(workerId, milestoneId) {
+    if (!isDbAvailable()) {
+        throw new Error("claimMilestoneLease: DB unavailable");
+    }
+    const now = new Date();
+    const nowIso = now.toISOString();
+    const expiresIso = ttlExpiry(now);
+    return transaction(() => {
+        const db = _getAdapter();
+        // Step 1: try a fresh INSERT. If it fails because the row already
+        // exists, fall through to the takeover branch below.
+        let inserted = false;
+        try {
+            db.prepare(`INSERT INTO milestone_leases (
+          milestone_id, worker_id, fencing_token,
+          acquired_at, expires_at, status
+        ) VALUES (
+          :milestone_id, :worker_id, 1,
+          :acquired_at, :expires_at, 'held'
+        )`).run({
+                ":milestone_id": milestoneId,
+                ":worker_id": workerId,
+                ":acquired_at": nowIso,
+                ":expires_at": expiresIso,
+            });
+            inserted = true;
+        }
+        catch (err) {
+            // SQLite raises a constraint error on duplicate PK — catch and fall
+            // through to UPDATE. Any other error is a bug; rethrow.
+            if (!isDuplicateLeaseInsertError(err))
+                throw err;
+        }
+        if (inserted) {
+            insertAuditEvent({
+                eventId: randomUUID(),
+                traceId: workerId,
+                category: "orchestration",
+                type: "lease-acquired",
+                ts: nowIso,
+                payload: { workerId, milestoneId, token: 1, mode: "fresh" },
+            });
+            return { ok: true, token: 1, expiresAt: expiresIso };
+        }
+        // Step 2: takeover. Conditional UPDATE — only succeeds if the existing
+        // lease is expired or explicitly released. Fencing token is incremented
+        // by SQL (`fencing_token + 1`) so the new holder's token monotonically
+        // exceeds the prior holder's. db.changes() === 1 confirms the takeover
+        // actually happened (vs. losing the race to another worker).
+        const updateResult = db.prepare(`UPDATE milestone_leases
+       SET worker_id = :worker_id,
+           fencing_token = fencing_token + 1,
+           acquired_at = :acquired_at,
+           expires_at = :expires_at,
+           status = 'held'
+       WHERE milestone_id = :milestone_id
+         AND (status IN ('expired','released')
+              OR datetime(expires_at) < datetime('now'))`).run({
+            ":milestone_id": milestoneId,
+            ":worker_id": workerId,
+            ":acquired_at": nowIso,
+            ":expires_at": expiresIso,
+        });
+        const changes = typeof updateResult.changes === "number"
+            ? updateResult.changes
+            : 0;
+        if (changes === 1) {
+            // Read back to obtain the new token value.
+            const row = db.prepare(`SELECT worker_id, fencing_token, expires_at FROM milestone_leases WHERE milestone_id = :milestone_id`).get({ ":milestone_id": milestoneId });
+            const token = row?.fencing_token ?? 1;
+            insertAuditEvent({
+                eventId: randomUUID(),
+                traceId: workerId,
+                category: "orchestration",
+                type: "lease-acquired",
+                ts: nowIso,
+                payload: { workerId, milestoneId, token, mode: "takeover" },
+            });
+            return { ok: true, token, expiresAt: expiresIso };
+        }
+        // Lease still held by someone else — read current holder for the error.
+        const holder = db.prepare(`SELECT worker_id, expires_at FROM milestone_leases WHERE milestone_id = :milestone_id`).get({ ":milestone_id": milestoneId });
+        return {
+            ok: false,
+            error: "held_by",
+            byWorker: holder?.worker_id ?? "unknown",
+            expiresAt: holder?.expires_at ?? "",
+        };
+    });
+}
+/**
+ * Refresh the lease's expires_at when the worker heartbeats. Idempotent —
+ * silently no-ops if the lease was already taken over or released.
+ */
+export function refreshMilestoneLease(workerId, milestoneId, fencingToken) {
+    if (!isDbAvailable())
+        return false;
+    const now = new Date();
+    const expiresIso = ttlExpiry(now);
+    const db = _getAdapter();
+    const result = db.prepare(`UPDATE milestone_leases
+     SET expires_at = :expires_at
+     WHERE milestone_id = :milestone_id
+       AND worker_id = :worker_id
+       AND fencing_token = :token
+       AND status = 'held'`).run({
+        ":expires_at": expiresIso,
+        ":milestone_id": milestoneId,
+        ":worker_id": workerId,
+        ":token": fencingToken,
+    });
+    const changes = typeof result.changes === "number"
+        ? result.changes
+        : 0;
+    return changes === 1;
+}
+/**
+ * Voluntarily release the lease (e.g. clean shutdown). Future claims may
+ * proceed without waiting for TTL expiry.
+ */
+export function releaseMilestoneLease(workerId, milestoneId, fencingToken) {
+    if (!isDbAvailable())
+        return false;
+    const db = _getAdapter();
+    return transaction(() => {
+        const result = db.prepare(`UPDATE milestone_leases
+       SET status = 'released'
+       WHERE milestone_id = :milestone_id
+         AND worker_id = :worker_id
+         AND fencing_token = :token
+         AND status = 'held'`).run({
+            ":milestone_id": milestoneId,
+            ":worker_id": workerId,
+            ":token": fencingToken,
+        });
+        const changes = typeof result.changes === "number"
+            ? result.changes
+            : 0;
+        if (changes === 1) {
+            insertAuditEvent({
+                eventId: randomUUID(),
+                traceId: workerId,
+                category: "orchestration",
+                type: "lease-released",
+                ts: new Date().toISOString(),
+                payload: { workerId, milestoneId, token: fencingToken },
+            });
+        }
+        return changes === 1;
+    });
+}
+/**
+ * Read current lease row for diagnostics. Returns null if no row exists.
+ */
+export function getMilestoneLease(milestoneId) {
+    if (!isDbAvailable())
+        return null;
+    const db = _getAdapter();
+    const row = db.prepare(`SELECT milestone_id, worker_id, fencing_token, acquired_at, expires_at, status
+     FROM milestone_leases WHERE milestone_id = :milestone_id`).get({ ":milestone_id": milestoneId });
+    return row ?? null;
+}
+/** TTL exported so callers (e.g. tests / janitors) can compute expirations. */
+export function milestoneLeaseTtlSeconds() {
+    return LEASE_TTL_SECONDS;
+}

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

@@ -0,0 +1,91 @@
+// gsd-2 + Non-correctness-critical key-value storage (Phase C — file-state migration)
+//
+// STRICT INVARIANT (re-stated from gsd-db.ts createRuntimeKvTableV25):
+// runtime_kv is for SOFT state only. UI cursors, dashboard caches,
+// last-seen-version markers, resume cursors, and similar values that
+// can be lost without breaking auto-mode correctness.
+//
+// Anything that drives the auto-loop's control flow MUST get typed
+// columns in unit_dispatches / workers / milestone_leases — never a
+// bag of JSON in runtime_kv. The reviewer's smell test: if losing the
+// row would cause the loop to reorder, double-execute, or stuck-loop,
+// it does NOT belong here.
+//
+// Single-host invariant: SQLite WAL coordination, local disk only.
+// See db/auto-workers.ts for the same constraint applied to coordination.
+import { _getAdapter, isDbAvailable, transaction, } from "../gsd-db.js";
+/**
+ * Set or update a runtime_kv row. The value is JSON-stringified before
+ * storage. Best-effort — silently no-ops when the DB is unavailable.
+ */
+export function setRuntimeKv(scope, scopeId, key, value) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    let valueJson;
+    try {
+        valueJson = JSON.stringify(value);
+    }
+    catch {
+        valueJson = JSON.stringify(String(value));
+    }
+    if (valueJson === undefined) {
+        valueJson = JSON.stringify(null);
+    }
+    transaction(() => {
+        db.prepare(`INSERT INTO runtime_kv (scope, scope_id, key, value_json, updated_at)
+       VALUES (:scope, :scope_id, :key, :value_json, :updated_at)
+       ON CONFLICT (scope, scope_id, key) DO UPDATE SET
+         value_json = excluded.value_json,
+         updated_at = excluded.updated_at`).run({
+            ":scope": scope,
+            ":scope_id": scopeId,
+            ":key": key,
+            ":value_json": valueJson,
+            ":updated_at": now,
+        });
+    });
+}
+/**
+ * Read a runtime_kv value, parsed from JSON. Returns null if the row
+ * doesn't exist or the DB is unavailable.
+ */
+export function getRuntimeKv(scope, scopeId, key) {
+    if (!isDbAvailable())
+        return null;
+    const db = _getAdapter();
+    const row = db.prepare(`SELECT value_json FROM runtime_kv
+     WHERE scope = :scope AND scope_id = :scope_id AND key = :key`).get({ ":scope": scope, ":scope_id": scopeId, ":key": key });
+    if (!row)
+        return null;
+    try {
+        return JSON.parse(row.value_json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a runtime_kv row. Idempotent — silently no-ops when the row
+ * doesn't exist or the DB is unavailable.
+ */
+export function deleteRuntimeKv(scope, scopeId, key) {
+    if (!isDbAvailable())
+        return;
+    const db = _getAdapter();
+    db.prepare(`DELETE FROM runtime_kv WHERE scope = :scope AND scope_id = :scope_id AND key = :key`).run({ ":scope": scope, ":scope_id": scopeId, ":key": key });
+}
+/**
+ * List all rows within a (scope, scopeId) bucket. Useful for diagnostics
+ * and bulk migrations.
+ */
+export function listRuntimeKv(scope, scopeId) {
+    if (!isDbAvailable())
+        return [];
+    const db = _getAdapter();
+    return db.prepare(`SELECT scope, scope_id, key, value_json, updated_at
+     FROM runtime_kv
+     WHERE scope = :scope AND scope_id = :scope_id
+     ORDER BY key`).all({ ":scope": scope, ":scope_id": scopeId });
+}