@bridge_gpt/mcp-server 0.2.2 → 0.2.4

package/build/conductor/store.js

@@ -0,0 +1,1156 @@
+/**
+ * Local SQLite event store for the conductor ledger.
+ *
+ * This is the reusable infrastructure layer consumed by both the conductor MCP
+ * tools and the conductor CLI. It owns the WAL-mode SQLite connection lifecycle,
+ * the append-only `events` table (plus schema-only `messages` and
+ * `supervisor_projection` tables reserved for later tickets), and the
+ * emit/poll/wait/snapshot/doctor/purge operations.
+ *
+ * Concurrency & safety invariants:
+ *   - Public event writes are append-only: {@link emitConductorEvent} only ever
+ *     INSERTs. The only deletes live behind {@link applyEventRetention}
+ *     (maintenance) and {@link purgeConductorLedger} (explicit purge).
+ *   - Payload size and secret validation happen BEFORE any write transaction.
+ *   - Reads default to compact, reference-oriented summaries; full payloads are
+ *     returned only on explicit `data_mode="full"`.
+ *   - Connections are always closed in a `finally`.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import Database from "better-sqlite3";
+import { SEMANTIC_EVENT_TYPES, assertSemanticEventType, } from "./taxonomy.js";
+import { ConductorValidationError } from "./errors.js";
+import { prepareDataJsonForStorage } from "./data-normalization.js";
+import { ensureConductorDatabaseFile, getConductorLedgerPath, getConductorPathHealth, detectNetworkMountedHome, } from "./paths.js";
+const BUSY_TIMEOUT_DEFAULT = 10_000;
+const BUSY_TIMEOUT_MIN = 250;
+const BUSY_TIMEOUT_MAX = 120_000;
+const RETENTION_DAYS_DEFAULT = 30;
+const RETENTION_DAYS_MAX = 3650;
+const RETENTION_MAX_ROWS_DEFAULT = 50_000;
+const RETENTION_MAX_ROWS_MIN = 100;
+const RETENTION_MAX_ROWS_MAX = 10_000_000;
+const POLL_LIMIT_DEFAULT = 100;
+const POLL_LIMIT_MAX = 1000;
+// Message relay per-type cooldown bounds (BAPI-397). A value <= 0 disables the
+// cooldown; positive values are clamped to [1s, 24h].
+const MESSAGE_COOLDOWN_DEFAULT_MS = 300_000;
+const MESSAGE_COOLDOWN_MIN_MS = 1_000;
+const MESSAGE_COOLDOWN_MAX_MS = 86_400_000;
+// Worker-poll delivery bounds (BAPI-397).
+const CHECK_MESSAGES_LIMIT_DEFAULT = 10;
+const CHECK_MESSAGES_LIMIT_MAX = 100;
+const WAIT_TIMEOUT_MAX_MS = 120_000;
+const WAIT_POLL_INTERVAL_MS = 500;
+const SUMMARY_FIELD_MAX_CHARS = 500;
+function parseBoundedInt(raw, fallback, min, max) {
+    if (raw === undefined || raw.trim().length === 0)
+        return fallback;
+    const parsed = Number.parseInt(raw.trim(), 10);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(max, Math.max(min, parsed));
+}
+/**
+ * Resolve store configuration from environment with safe defaults and bounds.
+ *   - `BAPI_CONDUCTOR_BUSY_TIMEOUT_MS` (default 10000, clamped [250, 120000]).
+ *   - `BAPI_CONDUCTOR_RETENTION_DAYS` (default 30). A value <= 0 DISABLES
+ *     age-based retention; positive values are clamped to [1, 3650].
+ *   - `BAPI_CONDUCTOR_RETENTION_MAX_ROWS` (default 50000). A value <= 0 DISABLES
+ *     the row cap; positive values are clamped to [100, 10000000].
+ */
+export function resolveConductorStoreConfig(env = process.env) {
+    const busy_timeout_ms = parseBoundedInt(env.BAPI_CONDUCTOR_BUSY_TIMEOUT_MS, BUSY_TIMEOUT_DEFAULT, BUSY_TIMEOUT_MIN, BUSY_TIMEOUT_MAX);
+    // Retention days: <= 0 disables (sentinel 0); positive values clamped.
+    const rawDays = env.BAPI_CONDUCTOR_RETENTION_DAYS;
+    let retention_days = RETENTION_DAYS_DEFAULT;
+    if (rawDays !== undefined && rawDays.trim().length > 0) {
+        const parsed = Number.parseInt(rawDays.trim(), 10);
+        if (!Number.isFinite(parsed)) {
+            retention_days = RETENTION_DAYS_DEFAULT;
+        }
+        else if (parsed <= 0) {
+            retention_days = 0; // disabled
+        }
+        else {
+            retention_days = Math.min(RETENTION_DAYS_MAX, parsed);
+        }
+    }
+    // Retention max rows: <= 0 disables (sentinel 0); positive values clamped.
+    const rawRows = env.BAPI_CONDUCTOR_RETENTION_MAX_ROWS;
+    let retention_max_rows = RETENTION_MAX_ROWS_DEFAULT;
+    if (rawRows !== undefined && rawRows.trim().length > 0) {
+        const parsed = Number.parseInt(rawRows.trim(), 10);
+        if (!Number.isFinite(parsed)) {
+            retention_max_rows = RETENTION_MAX_ROWS_DEFAULT;
+        }
+        else if (parsed <= 0) {
+            retention_max_rows = 0; // disabled
+        }
+        else {
+            retention_max_rows = Math.min(RETENTION_MAX_ROWS_MAX, Math.max(RETENTION_MAX_ROWS_MIN, parsed));
+        }
+    }
+    // Message relay cooldown: <= 0 disables (sentinel 0); positive values clamped.
+    const rawCooldown = env.BAPI_CONDUCTOR_MESSAGE_COOLDOWN_MS;
+    let message_cooldown_ms = MESSAGE_COOLDOWN_DEFAULT_MS;
+    if (rawCooldown !== undefined && rawCooldown.trim().length > 0) {
+        const parsed = Number.parseInt(rawCooldown.trim(), 10);
+        if (!Number.isFinite(parsed)) {
+            message_cooldown_ms = MESSAGE_COOLDOWN_DEFAULT_MS;
+        }
+        else if (parsed <= 0) {
+            message_cooldown_ms = 0; // disabled
+        }
+        else {
+            message_cooldown_ms = Math.min(MESSAGE_COOLDOWN_MAX_MS, Math.max(MESSAGE_COOLDOWN_MIN_MS, parsed));
+        }
+    }
+    return { busy_timeout_ms, retention_days, retention_max_rows, message_cooldown_ms };
+}
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+/**
+ * Current conductor SQLite schema version. Bumped to 2 in BAPI-395 because the
+ * `events.type` CHECK constraint vocabulary grew (git/PR/CI/gate taxonomy).
+ * Bumped to 3 in BAPI-397 because the message relay adds the `message.sent`,
+ * `message.delivered`, and `message.acked` audit event types to the same
+ * `events.type` CHECK vocabulary (and adds message relay indexes). Bumped to 4 in
+ * BAPI-398 because the C6 conditional-merge pipeline adds the `merge.dry_run`,
+ * `merge.attempted`, `merge.succeeded`, and `merge.failed` lifecycle event types
+ * to the same `events.type` CHECK vocabulary. Bumped to 5 in BAPI-413 because
+ * the per-merge human approval feature adds the `merge.pending_approval` lifecycle
+ * event type to the same CHECK vocabulary. Older ledgers stamped at a lower
+ * version are rebuilt by {@link migrateConductorSchemaIfNeeded} so their CHECK
+ * clause accepts the current taxonomy.
+ */
+export const CURRENT_CONDUCTOR_SCHEMA_VERSION = 5;
+/** Render the taxonomy `CHECK (type IN (...))` clause from the single source of truth. */
+function buildTypeCheckClause() {
+    const list = SEMANTIC_EVENT_TYPES.map((t) => `'${t}'`).join(", ");
+    return `CHECK (type IN (${list}))`;
+}
+/**
+ * Render the `CREATE TABLE` SQL for the events table (or a differently-named
+ * migration scratch table) using the CURRENT taxonomy CHECK clause. Shared by
+ * initialization and migration so the accepted event-type vocabulary is rendered
+ * from a single source.
+ */
+function buildEventsTableSql(tableName) {
+    return `
+    CREATE TABLE IF NOT EXISTS ${tableName} (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      id TEXT NOT NULL UNIQUE,
+      source TEXT NOT NULL,
+      type TEXT NOT NULL ${buildTypeCheckClause()},
+      subject TEXT,
+      run_id TEXT,
+      worker_id TEXT,
+      producer TEXT,
+      schema_version INTEGER NOT NULL DEFAULT 1,
+      time TEXT NOT NULL,
+      data_json TEXT NOT NULL,
+      confidence REAL,
+      observed_via TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `;
+}
+/** Render the `CREATE INDEX` SQL for the events table indexes (idempotent). */
+function buildEventsIndexesSql() {
+    return `
+    CREATE INDEX IF NOT EXISTS idx_events_seq ON events (seq);
+    CREATE INDEX IF NOT EXISTS idx_events_time ON events (time);
+    CREATE INDEX IF NOT EXISTS idx_events_type ON events (type);
+    CREATE INDEX IF NOT EXISTS idx_events_run_id ON events (run_id);
+    CREATE INDEX IF NOT EXISTS idx_events_worker_id ON events (worker_id);
+    CREATE INDEX IF NOT EXISTS idx_events_source ON events (source);
+  `;
+}
+/** Render the auxiliary (schema-only) tables reserved for later tickets. */
+function buildAuxiliaryTablesSql() {
+    return `
+    CREATE TABLE IF NOT EXISTS messages (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      id TEXT NOT NULL UNIQUE,
+      run_id TEXT NOT NULL,
+      worker_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      payload_json TEXT NOT NULL DEFAULT '{}',
+      state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'delivered', 'acked', 'failed')),
+      available_at TEXT NOT NULL DEFAULT (datetime('now')),
+      acked_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    -- The supervisor projection is actively maintained by the conductor
+    -- supervisor runtime (BAPI-396, \`conductor supervise --run-id <id>\`): the
+    -- foreground loop upserts a row after every deterministic iteration. It is
+    -- the OPERATIONAL state mirror of the run; raw events remain the source of
+    -- truth. The existing JSON columns are sufficient for resumable state, so the
+    -- table shape is unchanged.
+    CREATE TABLE IF NOT EXISTS supervisor_projection (
+      run_id TEXT PRIMARY KEY,
+      status TEXT NOT NULL DEFAULT 'unknown',
+      last_seq INTEGER,
+      last_event_time TEXT,
+      active_workers_json TEXT NOT NULL DEFAULT '[]',
+      gates_json TEXT NOT NULL DEFAULT '{}',
+      assessment_json TEXT,
+      summary_json TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `;
+}
+/**
+ * Render the auxiliary message relay indexes (idempotent). Two access patterns
+ * drive the column order:
+ *   - per-worker pending poll (`checkWorkerMessages`): filter run_id+worker_id,
+ *     state='pending', available_at gate, ordered by seq ->
+ *     `(run_id, worker_id, state, available_at, seq)`.
+ *   - per-type cooldown probe (`sendWorkerMessage`): filter run_id+worker_id+type
+ *     over a recent created_at window -> `(run_id, worker_id, type, created_at)`.
+ */
+function buildAuxiliaryIndexesSql() {
+    return `
+    CREATE INDEX IF NOT EXISTS idx_messages_worker_pending
+      ON messages (run_id, worker_id, state, available_at, seq);
+    CREATE INDEX IF NOT EXISTS idx_messages_cooldown
+      ON messages (run_id, worker_id, type, created_at);
+  `;
+}
+/** Read the SQLite `user_version` pragma as a number (0 when unreadable). */
+function readUserVersion(db) {
+    const uv = db.pragma("user_version", { simple: true });
+    if (typeof uv === "number")
+        return uv;
+    const parsed = Number.parseInt(String(uv), 10);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/** Return true when a table with the given name exists. */
+function conductorTableExists(db, name) {
+    const row = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(name);
+    return !!row?.name;
+}
+/**
+ * Create all conductor tables and indexes (idempotent) and stamp
+ * `PRAGMA user_version = CURRENT_CONDUCTOR_SCHEMA_VERSION`. Only `events` is
+ * exercised by tools/CLI today; `messages` and `supervisor_projection` are
+ * schema-only scaffolding.
+ */
+export function initializeConductorSchema(db) {
+    db.exec(`${buildEventsTableSql("events")}${buildEventsIndexesSql()}${buildAuxiliaryTablesSql()}${buildAuxiliaryIndexesSql()}`);
+    db.pragma(`user_version = ${CURRENT_CONDUCTOR_SCHEMA_VERSION}`);
+}
+/**
+ * Upgrade a pre-existing ledger whose `events.type` CHECK constraint predates the
+ * current taxonomy. Detects `user_version < CURRENT_CONDUCTOR_SCHEMA_VERSION` and,
+ * when an `events` table already exists, rebuilds it inside a single transaction
+ * using the CURRENT taxonomy CHECK clause: copy all rows into a scratch table,
+ * drop the old table, rename the scratch table to `events`, and recreate the
+ * indexes. `user_version` is stamped to the current version ONLY after the
+ * rebuild commits — a failed migration leaves the original data and version
+ * intact. A ledger with no `events` table is freshly initialized instead.
+ */
+export function migrateConductorSchemaIfNeeded(db) {
+    if (readUserVersion(db) >= CURRENT_CONDUCTOR_SCHEMA_VERSION)
+        return;
+    if (!conductorTableExists(db, "events")) {
+        initializeConductorSchema(db);
+        return;
+    }
+    const migrate = db.transaction(() => {
+        // Scratch table named for the current schema version (v4, BAPI-398) so the
+        // migration rebuild never reads as a stale pre-merge-taxonomy artifact.
+        db.exec(buildEventsTableSql("events_migrated_v5"));
+        db.exec(`INSERT INTO events_migrated_v5
+         (seq, id, source, type, subject, run_id, worker_id, producer, schema_version, time, data_json, confidence, observed_via, created_at)
+       SELECT seq, id, source, type, subject, run_id, worker_id, producer, schema_version, time, data_json, confidence, observed_via, created_at
+       FROM events`);
+        db.exec("DROP TABLE events");
+        db.exec("ALTER TABLE events_migrated_v5 RENAME TO events");
+        db.exec(buildEventsIndexesSql());
+        // Ensure auxiliary tables and their relay indexes exist on older ledgers too.
+        db.exec(buildAuxiliaryTablesSql());
+        db.exec(buildAuxiliaryIndexesSql());
+    });
+    migrate();
+    // Stamp the version only after the rebuild has committed successfully.
+    db.pragma(`user_version = ${CURRENT_CONDUCTOR_SCHEMA_VERSION}`);
+}
+// ---------------------------------------------------------------------------
+// Connection lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Open the ledger for writes: ensure the directory/file exist with restrictive
+ * permissions, open SQLite, apply WAL/concurrency pragmas, and initialize the
+ * schema before returning the live connection.
+ */
+export function openWritableConductorDatabase(config = resolveConductorStoreConfig()) {
+    ensureConductorDatabaseFile();
+    const db = new Database(getConductorLedgerPath());
+    // busy_timeout MUST be set first: `journal_mode = WAL` and the schema writes
+    // below take a lock, and with the default 0ms timeout a concurrent writer
+    // would get an immediate SQLITE_BUSY instead of waiting. Setting it first lets
+    // every subsequent locking operation honor the timeout (verified under a
+    // 5-process concurrent-emit integration test).
+    db.pragma(`busy_timeout = ${config.busy_timeout_ms}`);
+    // Switching to WAL takes a brief EXCLUSIVE lock and returns SQLITE_BUSY
+    // *immediately* (ignoring busy_timeout) when other connections are already
+    // open. WAL is a persistent file-level property, so tolerating a transient
+    // busy here is safe: whichever concurrent opener wins establishes WAL for all
+    // connections, and busy_timeout covers the actual write transactions
+    // regardless of journal mode. (Verified under a 5-process concurrent emit.)
+    try {
+        db.pragma("journal_mode = WAL");
+    }
+    catch {
+        /* another connection is mid-conversion / already owns the file lock */
+    }
+    db.pragma("synchronous = NORMAL");
+    db.pragma("foreign_keys = ON");
+    // Skip all schema work on connections that find an already-current ledger —
+    // this removes per-emit write contention. A fresh ledger is initialized; an
+    // older ledger (user_version < current) is migrated to the current taxonomy
+    // BEFORE any write happens against the returned connection.
+    if (readUserVersion(db) !== CURRENT_CONDUCTOR_SCHEMA_VERSION) {
+        if (conductorTableExists(db, "events")) {
+            migrateConductorSchemaIfNeeded(db);
+        }
+        else {
+            initializeConductorSchema(db);
+        }
+    }
+    return db;
+}
+/**
+ * Open the ledger read-only when it already exists; otherwise return `null`.
+ * Never creates files and never runs schema migrations.
+ */
+export function openReadonlyConductorDatabaseIfExists(config = resolveConductorStoreConfig()) {
+    const dbPath = getConductorLedgerPath();
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    }
+    catch {
+        return null;
+    }
+    db.pragma(`busy_timeout = ${config.busy_timeout_ms}`);
+    return db;
+}
+// ---------------------------------------------------------------------------
+// Row projections
+// ---------------------------------------------------------------------------
+function truncateField(value) {
+    if (typeof value === "string" && value.length > SUMMARY_FIELD_MAX_CHARS) {
+        return `${value.slice(0, SUMMARY_FIELD_MAX_CHARS)}… [truncated ${value.length - SUMMARY_FIELD_MAX_CHARS} chars]`;
+    }
+    return value;
+}
+function parseDataJson(row) {
+    try {
+        const parsed = JSON.parse(row.data_json);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Compact, metadata-first projection. Excludes `data.raw`; when raw payload data
+ * exists, surfaces its key names via `raw_keys`. Long normalized string fields
+ * are truncated. `references` / `payload_ref` are preserved when present.
+ */
+export function rowToEventSummary(row) {
+    const data = parseDataJson(row);
+    const { raw, ...rest } = data;
+    const compactData = {};
+    for (const [key, value] of Object.entries(rest)) {
+        compactData[key] = truncateField(value);
+    }
+    const summary = {
+        seq: row.seq,
+        id: row.id,
+        source: row.source,
+        type: row.type,
+        subject: row.subject,
+        run_id: row.run_id,
+        worker_id: row.worker_id,
+        producer: row.producer,
+        schema_version: row.schema_version,
+        time: row.time,
+        confidence: row.confidence,
+        observed_via: row.observed_via,
+        data: compactData,
+    };
+    if (raw !== undefined && raw !== null && typeof raw === "object") {
+        summary.raw_keys = Object.keys(raw);
+    }
+    return summary;
+}
+/** Full projection: complete (already-redacted) `data_json` plus all envelope fields. */
+export function rowToEventFull(row) {
+    return {
+        seq: row.seq,
+        id: row.id,
+        source: row.source,
+        type: row.type,
+        subject: row.subject,
+        run_id: row.run_id,
+        worker_id: row.worker_id,
+        producer: row.producer,
+        schema_version: row.schema_version,
+        time: row.time,
+        confidence: row.confidence,
+        observed_via: row.observed_via,
+        data: parseDataJson(row),
+    };
+}
+function projectRow(row, dataMode) {
+    return dataMode === "full" ? rowToEventFull(row) : rowToEventSummary(row);
+}
+// ---------------------------------------------------------------------------
+// Emit (append-only)
+// ---------------------------------------------------------------------------
+/**
+ * Append exactly one event to the ledger. Validates taxonomy + confidence and
+ * prepares/redacts the data JSON BEFORE opening the write transaction. Defaults
+ * `id`, `time`, and `schema_version`. Closes the connection in a `finally`.
+ */
+export function emitConductorEvent(input, config = resolveConductorStoreConfig()) {
+    // --- Validation & preparation OUTSIDE any SQLite transaction. ---
+    const type = assertSemanticEventType(input.type);
+    if (typeof input.source !== "string" || input.source.trim().length === 0) {
+        throw new ConductorValidationError("Event 'source' is required and must be a non-empty string.");
+    }
+    let confidence = null;
+    if (input.confidence !== undefined && input.confidence !== null) {
+        if (typeof input.confidence !== "number" || !Number.isFinite(input.confidence)) {
+            throw new ConductorValidationError("Event 'confidence' must be a finite number between 0 and 1.");
+        }
+        if (input.confidence < 0 || input.confidence > 1) {
+            throw new ConductorValidationError("Event 'confidence' must be between 0 and 1 (inclusive).");
+        }
+        confidence = input.confidence;
+    }
+    const dataJson = prepareDataJsonForStorage(input.data);
+    const id = typeof input.id === "string" && input.id.trim().length > 0 ? input.id : randomUUID();
+    const time = typeof input.time === "string" && input.time.trim().length > 0
+        ? input.time
+        : new Date().toISOString();
+    const schemaVersion = typeof input.schema_version === "number" && Number.isFinite(input.schema_version)
+        ? input.schema_version
+        : 1;
+    const db = openWritableConductorDatabase(config);
+    try {
+        const insert = db.prepare(`INSERT INTO events
+         (id, source, type, subject, run_id, worker_id, producer, schema_version, time, data_json, confidence, observed_via)
+       VALUES
+         (@id, @source, @type, @subject, @run_id, @worker_id, @producer, @schema_version, @time, @data_json, @confidence, @observed_via)`);
+        const runInsert = db.transaction(() => {
+            insert.run({
+                id,
+                source: input.source,
+                type,
+                subject: input.subject ?? null,
+                run_id: input.run_id ?? null,
+                worker_id: input.worker_id ?? null,
+                producer: input.producer ?? null,
+                schema_version: schemaVersion,
+                time,
+                data_json: dataJson,
+                confidence,
+                observed_via: input.observed_via ?? null,
+            });
+        });
+        runInsert();
+        const row = db.prepare("SELECT * FROM events WHERE id = ?").get(id);
+        // Retention runs AFTER the insert has committed, in its own transaction, and
+        // is BEST-EFFORT: the write is already durable, so a transient failure here
+        // (e.g. SQLITE_BUSY on the DELETE under concurrency) must NOT turn a
+        // committed emit into a reported failure — that would invite a retrying
+        // producer to append a duplicate event with a new UUID.
+        try {
+            applyEventRetention(db, config);
+        }
+        catch {
+            /* retention is maintenance; the emit already committed */
+        }
+        return { ok: true, event: rowToEventSummary(row) };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Retention maintenance: delete events older than the configured age and trim
+ * the oldest events beyond the row cap. Each cleanup runs in its own short
+ * transaction. A retention setting of 0 disables that dimension.
+ *
+ * Age is measured on `created_at` (server ingestion time), NOT the caller-
+ * supplied `time`: retaining on `time` would let a backfilled/backdated event be
+ * INSERTed and then immediately deleted within the same emit call (a "phantom"
+ * that no later poll could observe). `created_at` is also stored in the exact
+ * `datetime('now')` format, so the lexicographic comparison below is correct
+ * (caller `time` is ISO-8601 with `T`/`Z`, which does not compare cleanly).
+ */
+export function applyEventRetention(db, config) {
+    if (config.retention_days > 0) {
+        const deleteByAge = db.transaction(() => {
+            db.prepare(`DELETE FROM events WHERE created_at < datetime('now', @cutoff)`).run({ cutoff: `-${config.retention_days} days` });
+        });
+        deleteByAge();
+    }
+    if (config.retention_max_rows > 0) {
+        const deleteByCap = db.transaction(() => {
+            db.prepare(`DELETE FROM events
+           WHERE seq <= (
+             SELECT seq FROM events ORDER BY seq DESC LIMIT 1 OFFSET @cap
+           )`).run({ cap: config.retention_max_rows });
+        });
+        deleteByCap();
+    }
+}
+// ---------------------------------------------------------------------------
+// Read: poll / wait
+// ---------------------------------------------------------------------------
+/** Build an allowlisted, parameterized WHERE fragment from a filter. */
+function buildFilterClause(filter) {
+    const conditions = [];
+    const params = {};
+    if (!filter)
+        return { clause: "", params };
+    if (filter.type) {
+        // Defense-in-depth: reject non-taxonomy type filters before building SQL
+        // (the Zod tool layer already enforces this, but the store is the boundary).
+        assertSemanticEventType(filter.type);
+        conditions.push("type = @f_type");
+        params.f_type = filter.type;
+    }
+    if (filter.types && filter.types.length > 0) {
+        const placeholders = filter.types.map((_t, i) => `@f_types_${i}`);
+        filter.types.forEach((t, i) => {
+            assertSemanticEventType(t);
+            params[`f_types_${i}`] = t;
+        });
+        conditions.push(`type IN (${placeholders.join(", ")})`);
+    }
+    if (filter.source) {
+        conditions.push("source = @f_source");
+        params.f_source = filter.source;
+    }
+    if (filter.run_id) {
+        conditions.push("run_id = @f_run_id");
+        params.f_run_id = filter.run_id;
+    }
+    if (filter.worker_id) {
+        conditions.push("worker_id = @f_worker_id");
+        params.f_worker_id = filter.worker_id;
+    }
+    if (filter.subject) {
+        conditions.push("subject = @f_subject");
+        params.f_subject = filter.subject;
+    }
+    if (filter.producer) {
+        conditions.push("producer = @f_producer");
+        params.f_producer = filter.producer;
+    }
+    return {
+        clause: conditions.length > 0 ? ` AND ${conditions.join(" AND ")}` : "",
+        params,
+    };
+}
+/**
+ * Read events with `seq >= since_seq` (inclusive cursor), ordered ascending,
+ * applying allowlisted filters and a bounded limit. Returns compact summaries
+ * unless `data_mode="full"`. `next_seq` is the cursor to pass on the next call.
+ */
+export function pollConductorEvents(options = {}, config = resolveConductorStoreConfig()) {
+    const sinceSeq = typeof options.since_seq === "number" && options.since_seq >= 0
+        ? Math.floor(options.since_seq)
+        : 1;
+    const dataMode = options.data_mode === "full" ? "full" : "summary";
+    const limit = Math.min(POLL_LIMIT_MAX, Math.max(1, Math.floor(options.limit ?? POLL_LIMIT_DEFAULT)));
+    const db = openReadonlyConductorDatabaseIfExists(config);
+    if (!db) {
+        return { events: [], next_seq: sinceSeq, count: 0 };
+    }
+    try {
+        const { clause, params } = buildFilterClause(options.filter);
+        const rows = db
+            .prepare(`SELECT * FROM events WHERE seq >= @since_seq${clause} ORDER BY seq ASC LIMIT @limit`)
+            .all({ since_seq: sinceSeq, limit, ...params });
+        const events = rows.map((row) => projectRow(row, dataMode));
+        const nextSeq = rows.length > 0 ? rows[rows.length - 1].seq + 1 : sinceSeq;
+        return { events, next_seq: nextSeq, count: rows.length };
+    }
+    finally {
+        db.close();
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Bounded server-side wait: poll immediately, then sleep and re-poll until
+ * matching events appear or `timeout_ms` elapses. SQLite locks are never held
+ * between polls (each poll opens/closes a read-only connection). The timeout is
+ * clamped to {@link WAIT_TIMEOUT_MAX_MS}.
+ */
+export async function waitForConductorEvent(options = {}, config = resolveConductorStoreConfig()) {
+    const timeoutMs = Math.min(WAIT_TIMEOUT_MAX_MS, Math.max(0, Math.floor(options.timeout_ms ?? WAIT_TIMEOUT_MAX_MS)));
+    const deadline = Date.now() + timeoutMs;
+    // Poll immediately at least once.
+    let result = pollConductorEvents(options, config);
+    while (result.count === 0 && Date.now() < deadline) {
+        const remaining = deadline - Date.now();
+        await sleep(Math.min(WAIT_POLL_INTERVAL_MS, Math.max(1, remaining)));
+        result = pollConductorEvents(options, config);
+    }
+    return { ...result, timed_out: result.count === 0 };
+}
+function safeJsonParse(value, fallback) {
+    if (value === null)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Parse a raw `supervisor_projection` row into a {@link SupervisorProjection},
+ * decoding the JSON columns with safe fallbacks. Shared by the read path
+ * ({@link getSupervisorSnapshot}) and the write path
+ * ({@link upsertSupervisorProjection}) so projection parsing lives in exactly
+ * one place. Malformed JSON in any column never throws — it falls back to an
+ * empty structure / null while preserving the row's scalar identity fields.
+ */
+export function rowToSupervisorProjection(row) {
+    return {
+        run_id: row.run_id,
+        status: row.status,
+        last_seq: row.last_seq,
+        last_event_time: row.last_event_time,
+        active_workers: safeJsonParse(row.active_workers_json, []),
+        gates: safeJsonParse(row.gates_json, {}),
+        assessment: safeJsonParse(row.assessment_json, null),
+        summary: safeJsonParse(row.summary_json, null),
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+/**
+ * Read the supervisor projection for `run_id` (read-only). Returns
+ * `{ run_id, status: "unknown", projection: null }` when no projection exists.
+ * The projection is maintained by the conductor supervisor runtime
+ * (`conductor supervise`); this read never derives state from raw events.
+ */
+export function getSupervisorSnapshot(runId, config = resolveConductorStoreConfig()) {
+    const db = openReadonlyConductorDatabaseIfExists(config);
+    if (!db) {
+        return { run_id: runId, status: "unknown", projection: null };
+    }
+    try {
+        const row = db
+            .prepare("SELECT * FROM supervisor_projection WHERE run_id = ?")
+            .get(runId);
+        if (!row) {
+            return { run_id: runId, status: "unknown", projection: null };
+        }
+        return { run_id: row.run_id, status: row.status, projection: rowToSupervisorProjection(row) };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Upsert the supervisor projection row for a run (BAPI-396). Stores the
+ * arbitrary JSON inputs (`active_workers`, `gates`, `assessment`, `summary`) as
+ * JSON text, stamps `updated_at = datetime('now')` on every write, then re-reads
+ * the row and returns it parsed through {@link rowToSupervisorProjection}. The
+ * connection is always closed in a `finally`. The statement is fully
+ * parameterized — run-supplied values never enter the SQL string.
+ */
+export function upsertSupervisorProjection(input, config = resolveConductorStoreConfig()) {
+    if (typeof input.run_id !== "string" || input.run_id.trim().length === 0) {
+        throw new ConductorValidationError("Supervisor projection 'run_id' is required.");
+    }
+    const activeWorkersJson = JSON.stringify(input.active_workers ?? []);
+    const gatesJson = JSON.stringify(input.gates ?? {});
+    const assessmentJson = input.assessment == null ? null : JSON.stringify(input.assessment);
+    const summaryJson = input.summary == null ? null : JSON.stringify(input.summary);
+    const db = openWritableConductorDatabase(config);
+    try {
+        const upsert = db.prepare(`INSERT INTO supervisor_projection
+         (run_id, status, last_seq, last_event_time, active_workers_json, gates_json, assessment_json, summary_json, updated_at)
+       VALUES
+         (@run_id, @status, @last_seq, @last_event_time, @active_workers_json, @gates_json, @assessment_json, @summary_json, datetime('now'))
+       ON CONFLICT(run_id) DO UPDATE SET
+         status = excluded.status,
+         last_seq = excluded.last_seq,
+         last_event_time = excluded.last_event_time,
+         active_workers_json = excluded.active_workers_json,
+         gates_json = excluded.gates_json,
+         assessment_json = excluded.assessment_json,
+         summary_json = excluded.summary_json,
+         updated_at = datetime('now')`);
+        const runUpsert = db.transaction(() => {
+            upsert.run({
+                run_id: input.run_id,
+                status: input.status,
+                last_seq: input.last_seq,
+                last_event_time: input.last_event_time,
+                active_workers_json: activeWorkersJson,
+                gates_json: gatesJson,
+                assessment_json: assessmentJson,
+                summary_json: summaryJson,
+            });
+        });
+        runUpsert();
+        const row = db
+            .prepare("SELECT * FROM supervisor_projection WHERE run_id = ?")
+            .get(input.run_id);
+        return { ok: true, projection: rowToSupervisorProjection(row) };
+    }
+    finally {
+        db.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Doctor (read-only)
+// ---------------------------------------------------------------------------
+/**
+ * Read-only health inspection. Reports path/permission health, schema presence,
+ * journal mode, event count, max seq, resolved retention/concurrency settings,
+ * and network-home degradation. Never creates the DB, inserts a diagnostic
+ * event, or mutates WAL/schema state.
+ */
+export function doctorConductorLedger(config = resolveConductorStoreConfig()) {
+    const health = getConductorPathHealth();
+    const network = detectNetworkMountedHome();
+    const warnings = [...health.warnings];
+    if (network.network_mounted && network.warning) {
+        warnings.push(network.warning);
+    }
+    let schemaPresent = false;
+    let journalMode = null;
+    let eventCount = null;
+    let maxSeq = null;
+    let userVersion = null;
+    const db = openReadonlyConductorDatabaseIfExists(config);
+    if (db) {
+        try {
+            const tableRow = db
+                .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'events'")
+                .get();
+            schemaPresent = !!tableRow?.name;
+            const journal = db.pragma("journal_mode", { simple: true });
+            journalMode = typeof journal === "string" ? journal : journal != null ? String(journal) : null;
+            const uv = db.pragma("user_version", { simple: true });
+            userVersion = typeof uv === "number" ? uv : Number.parseInt(String(uv), 10) || null;
+            if (schemaPresent) {
+                const countRow = db.prepare("SELECT COUNT(*) AS c, MAX(seq) AS m FROM events").get();
+                eventCount = countRow.c;
+                maxSeq = countRow.m;
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    return {
+        path: health.path,
+        directory_path: health.directory_path,
+        directory_exists: health.directory_exists,
+        database_exists: health.database_exists,
+        directory_mode: health.directory_mode,
+        database_mode: health.database_mode,
+        directory_permissions_ok: health.directory_permissions_ok,
+        database_permissions_ok: health.database_permissions_ok,
+        schema_present: schemaPresent,
+        journal_mode: journalMode,
+        event_count: eventCount,
+        max_seq: maxSeq,
+        user_version: userVersion,
+        retention: {
+            busy_timeout_ms: config.busy_timeout_ms,
+            retention_days: config.retention_days,
+            retention_max_rows: config.retention_max_rows,
+        },
+        message_relay: {
+            message_cooldown_ms: config.message_cooldown_ms,
+        },
+        degraded: network.network_mounted,
+        warnings,
+    };
+}
+// ---------------------------------------------------------------------------
+// Purge (explicit, isolated full deletion)
+// ---------------------------------------------------------------------------
+/**
+ * Explicitly delete ALL rows from `events`, `messages`, and
+ * `supervisor_projection`. If the DB does not exist, returns a successful empty
+ * purge. Runs `wal_checkpoint(TRUNCATE)` after deletion when possible.
+ */
+export function purgeConductorLedger(config = resolveConductorStoreConfig()) {
+    if (!existsSync(getConductorLedgerPath())) {
+        return {
+            ok: true,
+            existed: false,
+            deleted: { events: 0, messages: 0, supervisor_projection: 0 },
+        };
+    }
+    const db = openWritableConductorDatabase(config);
+    try {
+        const purge = db.transaction(() => {
+            const events = db.prepare("DELETE FROM events").run().changes;
+            const messages = db.prepare("DELETE FROM messages").run().changes;
+            const supervisor = db.prepare("DELETE FROM supervisor_projection").run().changes;
+            return { events, messages, supervisor_projection: supervisor };
+        });
+        const deleted = purge();
+        try {
+            db.pragma("wal_checkpoint(TRUNCATE)");
+        }
+        catch {
+            /* checkpoint is best-effort */
+        }
+        return { ok: true, existed: true, deleted };
+    }
+    finally {
+        db.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Cooperative message relay (BAPI-397, conductor C5)
+// ---------------------------------------------------------------------------
+/** Conservative allowlist for a relay message `type` token. */
+const MESSAGE_TYPE_PATTERN = /^[A-Za-z0-9._:-]{1,100}$/;
+/**
+ * Build the ticket-required idempotency key for a relayed message:
+ * `worker_message:{run_id}:{worker_id}:{type}:{cause_seq}`. Identity tokens are
+ * trimmed; `cause_seq` is rendered as an integer. NO payload ever enters the key.
+ */
+export function makeWorkerMessageId(input) {
+    const runId = String(input.run_id).trim();
+    const workerId = String(input.worker_id).trim();
+    const type = String(input.type).trim();
+    const causeSeq = Math.trunc(input.cause_seq);
+    return `worker_message:${runId}:${workerId}:${type}:${causeSeq}`;
+}
+/**
+ * Validate the identity tuple of a relay message. Throws a
+ * {@link ConductorValidationError} (sanitized, never echoing payload) for empty
+ * identity fields, an unsafe/oversized `type`, or a non-integer/negative
+ * `cause_seq`.
+ */
+export function validateWorkerMessageIdentity(input) {
+    if (typeof input.run_id !== "string" || input.run_id.trim().length === 0) {
+        throw new ConductorValidationError("Message 'run_id' is required and must be a non-empty string.");
+    }
+    if (typeof input.worker_id !== "string" || input.worker_id.trim().length === 0) {
+        throw new ConductorValidationError("Message 'worker_id' is required and must be a non-empty string.");
+    }
+    if (typeof input.type !== "string" || input.type.trim().length === 0) {
+        throw new ConductorValidationError("Message 'type' is required and must be a non-empty string.");
+    }
+    if (!MESSAGE_TYPE_PATTERN.test(input.type.trim())) {
+        throw new ConductorValidationError("Message 'type' must be 1-100 characters from [A-Za-z0-9._:-].");
+    }
+    if (typeof input.cause_seq !== "number" ||
+        !Number.isFinite(input.cause_seq) ||
+        !Number.isInteger(input.cause_seq) ||
+        input.cause_seq < 0) {
+        throw new ConductorValidationError("Message 'cause_seq' must be a finite non-negative integer.");
+    }
+}
+/**
+ * Project a raw `messages` row into the worker-facing {@link ConductorWorkerMessage}.
+ * `payload_json` is parsed safely; malformed JSON falls back to `{}` without
+ * leaking a parse exception or the raw row.
+ */
+export function rowToConductorWorkerMessage(row) {
+    let payload = {};
+    try {
+        const parsed = JSON.parse(row.payload_json);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            payload = parsed;
+        }
+    }
+    catch {
+        payload = {};
+    }
+    return {
+        seq: row.seq,
+        id: row.id,
+        run_id: row.run_id,
+        worker_id: row.worker_id,
+        type: row.type,
+        payload,
+        state: row.state,
+        available_at: row.available_at,
+        acked_at: row.acked_at,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+/**
+ * Narrow duplicate-classifier for a SQLite UNIQUE-constraint violation on a
+ * relay insert. Mirrors the approach in `supervisor-ledger.ts` — it does NOT
+ * swallow unrelated storage errors.
+ */
+export function isDuplicateConstraintError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    if (typeof code === "string" && code.startsWith("SQLITE_CONSTRAINT"))
+        return true;
+    const message = error.message;
+    if (typeof message === "string") {
+        const lowered = message.toLowerCase();
+        if (lowered.includes("unique constraint") || lowered.includes("constraint failed"))
+            return true;
+    }
+    return false;
+}
+/** Insert a single audit event into `events` using an ALREADY-open connection. */
+function insertRelayAuditEvent(db, audit) {
+    const dataJson = prepareDataJsonForStorage(audit.data);
+    db.prepare(`INSERT INTO events
+       (id, source, type, subject, run_id, worker_id, producer, schema_version, time, data_json, confidence, observed_via)
+     VALUES
+       (@id, @source, @type, @subject, @run_id, @worker_id, @producer, @schema_version, @time, @data_json, @confidence, @observed_via)`).run({
+        id: audit.id,
+        source: audit.source,
+        type: audit.type,
+        subject: null,
+        run_id: audit.run_id,
+        worker_id: audit.worker_id,
+        producer: audit.producer,
+        schema_version: 1,
+        time: new Date().toISOString(),
+        data_json: dataJson,
+        confidence: null,
+        observed_via: audit.observed_via,
+    });
+}
+/**
+ * Enqueue a supervisor→worker message exactly once per idempotency key and
+ * suppress repeated same-type sends inside the configured cooldown window.
+ *
+ * Ordering: validate → compute id → normalize payload (redaction boundary) →
+ * open writable DB → (1) exact-id duplicate check, (2) per-type cooldown probe,
+ * (3) INSERT pending row + `message.sent` audit event in one transaction. An
+ * insert race on `messages.id` is reclassified as a duplicate. Message payloads
+ * are NEVER logged; unexpected storage errors are re-thrown after the connection
+ * is closed in `finally`.
+ */
+export function sendWorkerMessage(input, config = resolveConductorStoreConfig()) {
+    validateWorkerMessageIdentity(input);
+    const runId = input.run_id.trim();
+    const workerId = input.worker_id.trim();
+    const type = input.type.trim();
+    const messageId = makeWorkerMessageId({
+        run_id: runId,
+        worker_id: workerId,
+        type,
+        cause_seq: input.cause_seq,
+    });
+    // Normalize + redact the payload BEFORE any transaction (same boundary as events).
+    const payloadJson = prepareDataJsonForStorage(input.payload ?? {});
+    // A caller-supplied available_at must be a parseable timestamp: an unparseable
+    // value makes SQLite's `julianday(available_at)` return NULL, so the message
+    // would never satisfy the `<= julianday('now')` delivery gate and would be stuck
+    // pending forever. Reject it at the boundary rather than silently black-holing it.
+    if (typeof input.available_at === "string" && input.available_at.trim().length > 0) {
+        if (!Number.isFinite(Date.parse(input.available_at))) {
+            throw new ConductorValidationError("Message 'available_at' must be a parseable ISO-8601 timestamp.");
+        }
+    }
+    const availableAt = typeof input.available_at === "string" && input.available_at.trim().length > 0
+        ? input.available_at
+        : new Date().toISOString();
+    const cooldownMs = typeof input.cooldown_ms === "number" && Number.isFinite(input.cooldown_ms) && input.cooldown_ms >= 0
+        ? Math.trunc(input.cooldown_ms)
+        : config.message_cooldown_ms;
+    const source = typeof input.source === "string" && input.source.trim().length > 0
+        ? input.source.trim()
+        : "conductor-supervisor";
+    const producer = typeof input.producer === "string" && input.producer.trim().length > 0
+        ? input.producer.trim()
+        : "worker-message-relay";
+    const db = openWritableConductorDatabase(config);
+    try {
+        // (1) Exact idempotency-key hit: never insert or audit a second time.
+        const existing = db
+            .prepare("SELECT * FROM messages WHERE id = ?")
+            .get(messageId);
+        if (existing) {
+            return { status: "duplicate", message: rowToConductorWorkerMessage(existing) };
+        }
+        // (2) Per-type cooldown: a recent non-failed same-type message suppresses a
+        // re-send. SQLite julianday arithmetic avoids ISO-vs-datetime string-compare
+        // bugs. Disabled when cooldownMs <= 0.
+        if (cooldownMs > 0) {
+            const cooldownHit = db
+                .prepare(`SELECT * FROM messages
+             WHERE run_id = @run_id AND worker_id = @worker_id AND type = @type
+               AND state != 'failed'
+               AND (julianday('now') - julianday(created_at)) * 86400000.0 < @cooldown_ms
+             ORDER BY seq DESC
+             LIMIT 1`)
+                .get({ run_id: runId, worker_id: workerId, type, cooldown_ms: cooldownMs });
+            if (cooldownHit) {
+                return { status: "cooldown_suppressed", message: rowToConductorWorkerMessage(cooldownHit) };
+            }
+        }
+        // (3) Insert the pending message + its `message.sent` audit event atomically.
+        const insertMessage = db.prepare(`INSERT INTO messages (id, run_id, worker_id, type, payload_json, state, available_at)
+       VALUES (@id, @run_id, @worker_id, @type, @payload_json, 'pending', @available_at)`);
+        const runInsert = db.transaction(() => {
+            insertMessage.run({
+                id: messageId,
+                run_id: runId,
+                worker_id: workerId,
+                type,
+                payload_json: payloadJson,
+                available_at: availableAt,
+            });
+            insertRelayAuditEvent(db, {
+                id: `message.sent:${messageId}`,
+                source,
+                type: "message.sent",
+                run_id: runId,
+                worker_id: workerId,
+                producer,
+                observed_via: "message-relay",
+                data: {
+                    summary: "supervisor message enqueued",
+                    status: "sent",
+                    details: { message_id: messageId, message_type: type, cause_seq: Math.trunc(input.cause_seq) },
+                },
+            });
+        });
+        try {
+            runInsert();
+        }
+        catch (error) {
+            // A racing insert on the same idempotency key collides on messages.id —
+            // reclassify as an idempotent duplicate rather than a failure.
+            if (isDuplicateConstraintError(error)) {
+                const raced = db
+                    .prepare("SELECT * FROM messages WHERE id = ?")
+                    .get(messageId);
+                if (raced) {
+                    return { status: "duplicate", message: rowToConductorWorkerMessage(raced) };
+                }
+            }
+            throw error;
+        }
+        const row = db
+            .prepare("SELECT * FROM messages WHERE id = ?")
+            .get(messageId);
+        return { status: "enqueued", message: rowToConductorWorkerMessage(row) };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Cooperative worker poll: read pending, available messages for one worker and
+ * acknowledge each in the SAME write transaction (pending → delivered → acked),
+ * writing `message.delivered` and `message.acked` audit events. Acked messages
+ * are never redelivered because the selection predicate matches `pending` only.
+ *
+ * The whole select+transition runs inside a single write transaction so a worker
+ * always reads each pending message exactly once. Returned payloads are NEVER
+ * logged; the connection is closed in `finally`.
+ */
+export function checkWorkerMessages(input, config = resolveConductorStoreConfig()) {
+    if (typeof input.run_id !== "string" || input.run_id.trim().length === 0) {
+        throw new ConductorValidationError("Message poll 'run_id' is required and must be a non-empty string.");
+    }
+    if (typeof input.worker_id !== "string" || input.worker_id.trim().length === 0) {
+        throw new ConductorValidationError("Message poll 'worker_id' is required and must be a non-empty string.");
+    }
+    const runId = input.run_id.trim();
+    const workerId = input.worker_id.trim();
+    const limit = typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0
+        ? Math.min(CHECK_MESSAGES_LIMIT_MAX, Math.floor(input.limit))
+        : CHECK_MESSAGES_LIMIT_DEFAULT;
+    const db = openWritableConductorDatabase(config);
+    try {
+        const selectPending = db.prepare(`SELECT * FROM messages
+         WHERE run_id = @run_id AND worker_id = @worker_id AND state = 'pending'
+           AND julianday(available_at) <= julianday('now')
+         ORDER BY seq ASC
+         LIMIT @limit`);
+        const toDelivered = db.prepare("UPDATE messages SET state = 'delivered', updated_at = datetime('now') WHERE seq = @seq AND state = 'pending'");
+        const toAcked = db.prepare("UPDATE messages SET state = 'acked', acked_at = datetime('now'), updated_at = datetime('now') WHERE seq = @seq AND state = 'delivered'");
+        const reread = db.prepare("SELECT * FROM messages WHERE seq = ?");
+        const delivered = [];
+        const runDelivery = db.transaction(() => {
+            const pending = selectPending.all({ run_id: runId, worker_id: workerId, limit });
+            for (const row of pending) {
+                // Race-safe: only proceed when THIS call won the pending → delivered move.
+                const claimed = toDelivered.run({ seq: row.seq });
+                if (claimed.changes !== 1)
+                    continue;
+                insertRelayAuditEvent(db, {
+                    id: `message.delivered:${row.id}`,
+                    source: "conductor-worker",
+                    type: "message.delivered",
+                    run_id: row.run_id,
+                    worker_id: row.worker_id,
+                    producer: "worker-message-relay",
+                    observed_via: "message-relay",
+                    data: {
+                        summary: "supervisor message delivered to worker",
+                        status: "delivered",
+                        details: { message_id: row.id, message_type: row.type },
+                    },
+                });
+                toAcked.run({ seq: row.seq });
+                insertRelayAuditEvent(db, {
+                    id: `message.acked:${row.id}`,
+                    source: "conductor-worker",
+                    type: "message.acked",
+                    run_id: row.run_id,
+                    worker_id: row.worker_id,
+                    producer: "worker-message-relay",
+                    observed_via: "message-relay",
+                    data: {
+                        summary: "supervisor message acknowledged by worker",
+                        status: "acked",
+                        details: { message_id: row.id, message_type: row.type },
+                    },
+                });
+                const finalRow = reread.get(row.seq);
+                delivered.push(rowToConductorWorkerMessage(finalRow));
+            }
+        });
+        // BEGIN IMMEDIATE: this is a read-then-write transaction (SELECT pending, then
+        // UPDATE). A default/deferred transaction takes only a WAL read snapshot on the
+        // first SELECT and upgrades on the first UPDATE; if another connection commits
+        // in between, SQLite throws SQLITE_BUSY_SNAPSHOT *without* honoring busy_timeout.
+        // In the real conductor run the supervisor + N workers all write the same
+        // ledger, so check_messages is the hottest concurrent path — acquiring the write
+        // lock up front lets busy_timeout cover the contention and avoids the snapshot race.
+        runDelivery.immediate();
+        return { messages: delivered, count: delivered.length, acked_count: delivered.length };
+    }
+    finally {
+        db.close();
+    }
+}