opencode-swarm 7.163.1 → 7.164.0

package/dist/db/canonical-project.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical project identity for the SQLite durable-state foundation (issue #2480).
+ *
+ * Policy (docs/sqlite-durable-state.md §Identity):
+ * - This helper answers ONE question: "are these two directory spellings the same project
+ *   root, so they must share ONE `.swarm/swarm.db` connection?" It is project-root
+ *   IDENTITY, not security-sensitive file equivalence — those are different threat models
+ *   and deliberately different helpers (issue #2474 / Workstream B1 owns the repo-wide
+ *   identity rollout; this is the DB-layer-scoped implementation D1 builds on).
+ * - Resolution: `path.resolve` (lexical cleanup) → best-effort `fs.realpathSync`
+ *   (collapses symlinks/junctions and, on Windows, expands 8.3 short names) →
+ *   case-fold the WHOLE key on win32 only. On POSIX, case is significant: `/a/B` and
+ *   `/a/b` are different roots and must stay isolated.
+ * - Never throws: if `realpathSync` fails (broken symlink, permission, race), the
+ *   lexically-resolved path is used as-is. A canonicalization failure must not prevent
+ *   the project DB from opening; it only risks a duplicate handle for exotic spellings,
+ *   which is the pre-existing behavior.
+ */
+import { realpathSync } from 'node:fs';
+/** DI seam for tests (fault-injected realpath failures). */
+export declare const _internals: {
+    realpathSync: typeof realpathSync;
+};
+/**
+ * Return the canonical cache key for a project directory.
+ *
+ * - `C:\Proj` and `c:\proj\` map to one key on Windows (one DB handle).
+ * - A symlink or junction to the same directory maps to one key on every platform.
+ * - Distinct POSIX casings remain distinct roots.
+ */
+export declare function canonicalProjectKey(directory: string): string;

package/dist/db/db-errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Typed errors for the SQLite durable-state foundation (issue #2480).
+ *
+ * Callers use `category` to make fail-open decisions and to emit ONE coalesced
+ * advisory per condition instead of repeating raw SQLite errors. Messages never
+ * contain SQL text or user file contents; at most the `.swarm/swarm.db` artifact
+ * name appears.
+ */
+export type ProjectDbErrorCategory = 'mkdir_failed' | 'driver_unavailable' | 'open_failed' | 'migration_failed';
+export type DbWriteErrorCategory = 'disk_full' | 'read_only' | 'corrupt' | 'busy' | 'unknown';
+export declare class ProjectDbError extends Error {
+    readonly category: ProjectDbErrorCategory;
+    constructor(category: ProjectDbErrorCategory, message: string);
+}
+export declare class DbWriteError extends Error {
+    readonly category: DbWriteErrorCategory;
+    constructor(category: DbWriteErrorCategory, message: string);
+}
+/**
+ * Classify a write/open failure into a `DbWriteErrorCategory` from errno and
+ * SQLite error text. Used by the group-commit writer to decide retry/degrade
+ * behavior (issue #2480 disk-full / read-only / corrupt handling).
+ */
+export declare function classifyDbWriteError(err: unknown): DbWriteErrorCategory;

package/dist/db/driver-parity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Bun ↔ Node driver-parity contract for `.swarm/swarm.db` (issue #2480
+ * obligation 2).
+ *
+ * A single suite, run against WHATEVER driver the shared sqlite loader
+ * resolved:
+ * - under `bun test`: the real `bun:sqlite` driver (and the node adapter
+ *   against the strict fake in `sqlite-loader.test.ts`);
+ * - under the merge-queue smoke job (`scripts/repro-1873.mjs`, 3-OS, real
+ *   Node 22): the real `node:sqlite` driver through the adapter.
+ *
+ * The contract pins the behavioral deltas documented for #1873/#2480:
+ * - EXACT parameter counts: every bound-parameter call must pass exactly as
+ *   many values as the statement has placeholders. `node:sqlite` rejects a
+ *   mismatched count (`SQLITE_RANGE`); `bun:sqlite` tolerates some lax forms.
+ *   Portable code never relies on the lax form.
+ * - Multi-statement strings only through the no-parameter `run(sql)` path
+ *   (which routes to `exec` on both drivers).
+ * - Transaction + SAVEPOINT nesting round trip.
+ * - WAL / busy_timeout / synchronous pragma reads.
+ */
+import type { Database } from 'bun:sqlite';
+export interface DriverParityProbe {
+    /** True when the resolved driver is the node:sqlite adapter. */
+    isNodeAdapter: boolean;
+}
+/**
+ * Assert the driver-parity contract on a FRESH database (the caller owns its
+ * lifecycle and closes it). Throws on the first violation.
+ */
+export declare function runDriverParityContract(db: Database, probe?: DriverParityProbe): void;

package/dist/db/durability.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-table durability classes for `.swarm/swarm.db` (issue #2480 obligation 4).
+ *
+ * SQLite's `synchronous` pragma is connection-scoped and takes effect at the next
+ * commit, so "per-table durability classes" are implemented by escalating the
+ * pragma around write transactions whose target table demands it:
+ *
+ * - `full`  — terminal-state streams (authoritative rows whose loss changes an
+ *   outcome): `synchronous = FULL` for the wrapping transaction. Authoritative
+ *   state must never inherit the rebuildable-index durability setting.
+ * - `normal` — telemetry/operational/diagnostic rows: `synchronous = NORMAL`
+ *   (WAL + NORMAL is durable across application crashes; only an OS/power
+ *   failure can lose the tail — acceptable for rebuildable streams).
+ *
+ * A batch that contains ANY `full`-class write runs the WHOLE transaction at
+ * FULL (escalation rule, group-commit writer consults `batchDurabilityClass`).
+ */
+import type { Database } from 'bun:sqlite';
+/** The durability class of every table in `.swarm/swarm.db`. */
+export declare const DURABILITY_CLASSES: Readonly<Record<string, 'full' | 'normal'>>;
+/** Escalation rule: any full-class op makes the whole batch full-class. */
+export declare function batchDurabilityClass(classes: Iterable<'full' | 'normal'>): 'full' | 'normal';
+/** Apply the `synchronous` pragma for a durability class. Cheap and idempotent. */
+export declare function applySynchronousForClass(db: Database, cls: 'full' | 'normal'): void;
+/**
+ * Run `fn` with the connection's `synchronous` pragma set for `cls`, restoring
+ * NORMAL afterwards. `fn` is expected to complete its own transaction (or be
+ * composed inside one); the pragma takes effect at commit time.
+ *
+ * The connection default is NORMAL (telemetry class), so restoring NORMAL — not
+ * "the previous value" — is the correct post-condition: nothing outside the
+ * foundation ever sets a different value on this connection.
+ *
+ * NESTING CAVEAT (final-critic note): nesting a normal-class helper inside an
+ * open full-class transaction would restore NORMAL before the OUTER commit.
+ * No production path nests these helpers today (group-commit ops never call
+ * the qa-gate/receipt writers); if nesting is ever introduced, restore the
+ * pre-call value instead.
+ */
+export declare function withDurabilityClass<T>(db: Database, cls: 'full' | 'normal', fn: () => T): T;

package/dist/db/group-commit-writer.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Group-commit writer for `.swarm/swarm.db` low-risk stores (issue #2480
+ * obligation 8: "queue -> one txn per flush").
+ *
+ * Design:
+ * - One writer per canonical project root, created lazily on first use and
+ *   closed with the DB handle (`closeGroupCommitWriter`). Nothing here runs at
+ *   plugin init.
+ * - `enqueue(op)` queues a write op. A flush applies EVERY queued op inside
+ *   ONE `BEGIN IMMEDIATE` transaction (the qa-gate-profile lock precedent —
+ *   plain `db.transaction()` issues a deferred BEGIN that lets two writers
+ *   deadlock-escalate to SQLITE_BUSY under two-windows contention).
+ * - Durability escalation: if any op in the batch is `full`-class, the whole
+ *   transaction runs with `PRAGMA synchronous = FULL` (authoritative state
+ *   never inherits the rebuildable-index setting); otherwise NORMAL.
+ * - Backpressure: the queue is bounded; overflow forces a synchronous flush
+ *   rather than dropping writes.
+ * - Failure handling: a `BEGIN IMMEDIATE` busy or a disk-full/read-only
+ *   failure keeps the queue intact, classifies the error (`db-errors.ts`),
+ *   and coalesces to ONE advisory/telemetry signal per degradation episode
+ *   (cooldown); the next flush retries. Ops themselves throwing rolls the
+ *   transaction back and rethrows (the enqueuing store decides fail-open).
+ */
+import type { Database } from 'bun:sqlite';
+import { type DbWriteErrorCategory } from './db-errors.js';
+import { getProjectDb } from './project-db.js';
+/** A single durable write, applied inside a flush transaction. */
+export interface GroupCommitOp {
+    /** Durability class of the target table/stream (escalation input). */
+    durability: 'full' | 'normal';
+    /** Apply the write. Must only touch `.swarm/swarm.db` via the given handle. */
+    run: (db: Database) => void;
+}
+/**
+ * Detect "the underlying handle was closed" failures across BOTH drivers:
+ * bun:sqlite says "database has closed"; node:sqlite raises
+ * ERR_INVALID_STATE "database is not open".
+ */
+declare function isClosedHandleError(err: unknown): boolean;
+/** Queue bound — overflow forces a synchronous flush (never a silent drop). */
+export declare const MAX_QUEUED_OPS = 1024;
+/** Ops at or above this count trigger an immediate synchronous flush. */
+export declare const FLUSH_THRESHOLD_OPS = 64;
+/**
+ * Test seam (repo `_internals` convention): the self-heal rebind's handle
+ * acquisition, injectable so tests can deterministically exercise the
+ * eviction-on-double-closed-handle path (a rebind that returns an ALREADY
+ * closed handle).
+ */
+export declare const _internals: {
+    getProjectDb: typeof getProjectDb;
+    isClosedHandleError: typeof isClosedHandleError;
+};
+export declare class GroupCommitWriter {
+    private db;
+    private queue;
+    private flushing;
+    private degraded;
+    private lastAdvisoryAt;
+    private closed;
+    /**
+     * Canonical cache key this writer was registered under (set by
+     * getGroupCommitWriter). A flush against a CLOSED underlying handle —
+     * possible when a close site evicted the DB handle without closing the
+     * writer — evicts the writer from the registry so the next store call
+     * rebinds to the fresh handle instead of failing forever.
+     */
+    private registryKey;
+    constructor(db: Database);
+    get queuedOpCount(): number;
+    /** #2480: record the registry key for self-healing eviction. */
+    bindRegistryKey(key: string): void;
+    /**
+     * Queue a write op. A synchronous flush runs immediately when the queue
+     * reaches the flush threshold (backpressure), and again at the hard
+     * `MAX_QUEUED_OPS` bound. Throws `DbWriteError` from an inline flush
+     * (threshold or hard bound) when the flush fails — the op is then NOT
+     * accepted; the caller's fail-open handling owns the loss.
+     */
+    enqueue(op: GroupCommitOp): void;
+    /**
+     * Apply every queued op in ONE immediate transaction. On op failure the
+     * transaction rolls back and the error rethrows (queue emptied — the ops
+     * are not idempotently retryable by this layer). On busy/disk-full/
+     * read-only the queue is RETAINED and a typed `DbWriteError` throws.
+     *
+     * Self-healing (#2480): if the underlying handle was CLOSED underneath
+     * this writer (a close site evicted the DB handle without closing the
+     * writer — the pre-fix /swarm close shape), the flush rebinds to a fresh
+     * handle ONCE and re-applies the batch, so post-close writes complete
+     * transparently instead of failing until restart.
+     */
+    flushSync(): void;
+    /** Async facade over the synchronous flush (callers `await` durability). */
+    flush(): Promise<void>;
+    /** Close the writer and drop any unflushed queue. */
+    close(): void;
+    private applyBatch;
+    private noteDegraded;
+    /** Test/observability access to the degradation state. */
+    get degradation(): {
+        category: DbWriteErrorCategory;
+        until: number;
+    } | null;
+}
+/**
+ * Return the group-commit writer for a project root, creating it (and the DB
+ * handle) lazily on first use. Never runs at plugin init.
+ */
+export declare function getGroupCommitWriter(directory: string): GroupCommitWriter;
+/** Flush + close the writer for a root (dispose/exit/close paths). */
+export declare function closeGroupCommitWriter(directory: string): void;
+/** Flush + close every writer, then close every DB handle. Test/close use. */
+export declare function closeAllGroupCommitWriters(): void;
+/** Number of open writers (tests/observability). */
+export declare function getOpenGroupCommitWriterCount(): number;
+export {};

package/dist/db/health.d.ts

@@ -0,0 +1,35 @@
+/**
+ * swarm.db health probe (issue #2480 obligation 5).
+ *
+ * The one sanctioned read-only surface for diagnose-style health checks: runs
+ * the size-capped quick_check + pragma/migration-failure probes and returns a
+ * structured snapshot. Keeping the SQL here (inside `src/db/**`) means the
+ * raw-handle confinement and writer-registry seams stay honest — callers like
+ * `diagnose-service` consume a plain object.
+ */
+/** quick_check size cap: an oversized DB reports `too_large` instead of scanning inline. */
+export declare const SWARM_DB_QUICK_CHECK_MAX_BYTES: number;
+export type SwarmDbHealthSnapshot = {
+    kind: 'absent';
+} | {
+    kind: 'too_large';
+    sizeBytes: number;
+} | {
+    kind: 'open';
+    quickCheck: string;
+    journalMode: string;
+    pageCount: number;
+    migrationFailures: number;
+    /** #2480 review F-07: stale marker file present (a recorded
+     * failure whose cleanup could not run — surfaced for diagnosis). */
+    staleMarker: boolean;
+} | {
+    kind: 'error';
+    category: string;
+    message: string;
+};
+/**
+ * Probe `.swarm/swarm.db` health. Never opens-for-create (an absent DB is
+ * `absent`, which callers render as healthy) and never throws.
+ */
+export declare function getSwarmDbHealthSnapshot(directory: string): SwarmDbHealthSnapshot;

package/dist/db/insight-candidate-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * swarm.db store for insight candidates (issue #2480 D1 migration).
+ *
+ * Replaces `.swarm/insight-candidates.jsonl` (locked read-modify-write JSONL
+ * queue) with the append-only event-stream pattern:
+ *
+ * - Table `insight_candidate` — PK (stream_id, version) is the
+ *   UNIQUE(stream_id, version) stream contract; versions are assigned
+ *   MAX(version)+1 inside the appending transaction.
+ * - `appendInsightCandidatesDb` batches appends through the group-commit
+ *   writer (queue -> one txn per flush).
+ * - `consumeInsightCandidatesDb` is the dual-contract transaction: SELECT the
+ *   pending batch + UPDATE consumed_at for exactly those versions in ONE
+ *   `BEGIN IMMEDIATE` transaction, so concurrent appends and consumes can
+ *   never lose or double-take a candidate.
+ * - Telemetry-sink retention: consumed rows are DELETE-pruned after 7 days,
+ *   and the pending queue is FIFO-capped at 500 (both bounds carried over
+ *   from the legacy store's limits).
+ *
+ * Payloads are opaque serialized JSON strings; the hook layer owns parsing,
+ * validation, and identity (`resolveInsightCandidateId` recomputes identity
+ * from content, so no id column exists).
+ */
+/** The single stream id used by this store (table is stream-shaped for D2+). */
+export declare const INSIGHT_CANDIDATE_STREAM_ID = "insight-candidates";
+/** Legacy queue filename (imported then cold-archived as `.jsonl.imported`). */
+export declare const INSIGHT_CANDIDATES_LEGACY_FILE = "insight-candidates.jsonl";
+/** FIFO cap on pending (unconsumed) candidates — carried over from the file store. */
+export declare const INSIGHT_PENDING_CAP = 500;
+/** Consumed-row retention window (telemetry-sink DELETE-based retention). */
+export declare const INSIGHT_CONSUMED_RETENTION_DAYS = 7;
+export interface InsightCandidateRow {
+    payload: string;
+    createdAt: string;
+}
+/**
+ * One-time (per process, per canonical root) lazy import of the legacy
+ * `.swarm/insight-candidates.jsonl` queue. Never runs at plugin init.
+ */
+export declare function ensureInsightLegacyImported(directory: string): void;
+/**
+ * Append candidates to the stream via the group-commit writer and await the
+ * flush (the legacy store's append was awaited too — durability semantics
+ * are preserved; batching coalesces concurrent callers and multi-candidate
+ * calls into one transaction).
+ */
+export declare function appendInsightCandidatesDb(directory: string, rows: InsightCandidateRow[]): Promise<void>;
+/**
+ * Atomically consume up to `limit` pending candidates: the SELECT and the
+ * consumed_at UPDATE happen in ONE immediate transaction (dual-contract
+ * event+state transition). Consumed rows older than the retention window are
+ * DELETE-pruned in the same transaction. Returns the consumed payloads,
+ * oldest first.
+ */
+export declare function consumeInsightCandidatesDb(directory: string, limit: number): string[];
+/** Count pending (unconsumed) candidates — status/diagnostics surface. */
+export declare function countPendingInsightCandidatesDb(directory: string): number;
+/** List pending payloads, oldest first (postmortem raw-content surface). */
+export declare function listPendingInsightCandidatesDb(directory: string, max: number): string[];
+/** Test hook: reset the per-process import guards. */
+export declare function _resetInsightImportGuards(): void;

package/dist/db/legacy-import.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Idempotent legacy file → swarm.db import (issue #2480 obligation 3).
+ *
+ * Contract (docs/sqlite-durable-state.md §Legacy import):
+ * - Legacy artifact PRESENT + target table/stream EMPTY → import every record
+ *   in ONE `BEGIN IMMEDIATE` transaction (emptiness re-checked inside the
+ *   transaction so a concurrent importer cannot double-import) → on commit,
+ *   rename the artifact to `<name>.imported` (bounded Windows rename retry).
+ * - Crash before commit → nothing imported; the next run retries (idempotent).
+ * - Crash after commit before rename → the next run sees a NON-empty table;
+ *   the stale file is left in place (never re-imported, never silently
+ *   deleted) with a once-per-process warning. This also covers a file that
+ *   reappeared because an older plugin version wrote it again: those lines
+ *   are preserved on disk rather than destroyed.
+ * - Artifact absent, or table already populated → no-op.
+ *
+ * Import runs lazily on first store use, never at plugin init (the
+ * knowledge-receipts migration precedent).
+ */
+import { renameSync } from 'node:fs';
+import { getProjectDb } from './project-db.js';
+/**
+ * Size cap for a single legacy artifact import (#2480 review F-02 — same
+ * guard convention as MAX_TRACEABILITY_BYTES in design-doc-drift). The live
+ * stores were FIFO/entry-bounded when they were files, so anything beyond
+ * this is pathological; it is skipped inert (never imported, never renamed)
+ * rather than loaded into memory.
+ */
+export declare const MAX_LEGACY_IMPORT_BYTES: number;
+export interface LegacyImportResult {
+    /** Rows imported (0 when the import conditions were not met). */
+    imported: number;
+    /** Lines/files skipped because they failed validation. */
+    skipped: number;
+    /** True when the legacy artifact was renamed to `.imported`. */
+    archived: boolean;
+}
+declare function warnStaleLegacyOnce(key: string, fileName: string): void;
+/**
+ * DI seam for tests: the LOW-LEVEL rename is fault-injectable so the retry
+ * loop itself stays under test (replacing the loop would test nothing).
+ */
+export declare const _internals: {
+    renameSync: typeof renameSync;
+    warnStaleLegacyOnce: typeof warnStaleLegacyOnce;
+    maxLegacyImportBytes: () => number;
+};
+/**
+ * Import a legacy `.jsonl` file into an append-only stream table.
+ *
+ * `parseLine` returns the row payload string for a valid line or null to skip
+ * (corrupt line). Rows are inserted with versions 1..n in file order. The
+ * emptiness probe is `streamCount(db)` (e.g. rows for the stream).
+ */
+export declare function importLegacyJsonl(directory: string, opts: {
+    fileName: string;
+    /** Count existing rows for the target stream (inside the txn). */
+    streamCount: (db: ReturnType<typeof getProjectDb>) => number;
+    /** Insert one row at the given version; payload from the parsed line. */
+    insertRow: (db: ReturnType<typeof getProjectDb>, version: number, payload: string) => void;
+    parseLine: (line: string) => string | null;
+}): LegacyImportResult;
+/**
+ * Import a family of legacy `.json` files into an entity table keyed by
+ * `(kind, phase)`. Files are discovered by exact prefix/suffix match in
+ * `.swarm/` (readdir — no user-supplied paths), the phase is parsed from the
+ * filename, and each file's parsed+validated object becomes the row payload.
+ */
+export declare function importLegacyJsonFiles(directory: string, opts: {
+    filePrefix: string;
+    kind: string;
+    /** Count existing rows for the kind (inside the txn). */
+    kindCount: (db: ReturnType<typeof getProjectDb>) => number;
+    /** Upsert one row; payload is the serialized JSON file content. */
+    upsertRow: (db: ReturnType<typeof getProjectDb>, phase: number, payload: string) => void;
+}): LegacyImportResult;
+export {};

package/dist/db/phase-report-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * swarm.db store for per-phase reports (issue #2480 D1 migration).
+ *
+ * Replaces two legacy file families with the entity/KV pattern — one row per
+ * (kind, phase), last-write-wins on a same-phase re-run:
+ * - `.swarm/drift-report-phase-{N}.json` (curator drift, kind
+ *   `curator_drift`) — written by `src/hooks/curator-drift.ts`, read back by
+ *   `readPriorDriftReports` and the curator postmortem.
+ * - `.swarm/doc-drift-phase-{N}.json` (design-doc drift, kind
+ *   `design_doc_drift`) — written by `src/hooks/design-doc-drift.ts` (whose
+ *   legacy bare `writeFile` was non-atomic; the store fixes that).
+ *
+ * Payloads are opaque serialized JSON strings; readers own validation
+ * (skip-corrupt on read, mirroring the legacy readers).
+ */
+export type PhaseReportKind = 'curator_drift' | 'design_doc_drift';
+/** Legacy filename prefixes, one per report kind. */
+export declare const PHASE_REPORT_LEGACY_PREFIXES: Readonly<Record<PhaseReportKind, string>>;
+/**
+ * One-time (per process, per canonical root) lazy import of both legacy
+ * report families. Never runs at plugin init.
+ */
+export declare function ensurePhaseReportsImported(directory: string): void;
+/**
+ * Upsert one phase report via the group-commit writer and await the flush.
+ * A same-phase re-run overwrites the row (the legacy file rewrite semantic)
+ * and `updated_at` moves.
+ */
+export declare function upsertPhaseReportDb(directory: string, kind: PhaseReportKind, phase: number, payload: string): Promise<void>;
+/**
+ * Read all reports of one kind, ascending by phase. Returns the raw payload
+ * strings; the caller validates (the curator drift reader keeps its
+ * skip-corrupt schema check).
+ */
+export declare function readPhaseReportsDb(directory: string, kind: PhaseReportKind): Array<{
+    phase: number;
+    payload: string;
+}>;
+/**
+ * Stable, human-readable locator for a stored report (event payloads and
+ * advisory text reference the DB-backed store instead of a file path).
+ */
+export declare function phaseReportLocator(kind: PhaseReportKind, phase: number): string;
+/** Test hook: reset the per-process import guards. */
+export declare function _resetPhaseReportImportGuards(): void;

package/dist/db/project-db.d.ts

@@ -1,16 +1,32 @@
 /**
  * Per-project SQLite database for opencode-swarm.
  *
- * Owns `.swarm/swarm.db` in each project directory. Stores per-project
- * constraints and QA gate profiles. One cached instance per normalized
- * directory path.
+ * Owns `.swarm/swarm.db` in each project directory: the single durable
+ * substrate of Workstream D (issue #2480). One cached instance per CANONICAL
+ * project identity (`canonical-project.ts`): case-varied Windows spellings,
+ * trailing separators, and symlinked roots of the same project share one
+ * connection. Open failures are typed (`db-errors.ts`), failed migrations are
+ * recorded for diagnosis and retried on the next open, and close runs a
+ * best-effort WAL checkpoint. The durability-class policy for every table
+ * lives in `durability.ts`.
  */
 import type { Database } from 'bun:sqlite';
+/** Number of currently cached project DB handles (tests / observability). */
+export declare function getOpenProjectDbCount(): number;
+/**
+ * Detect "another process applied this migration concurrently" failures:
+ * a UNIQUE constraint violation on schema_migrations.version, or an
+ * "already exists" DDL error (table/index/trigger created by the winner).
+ */
+export declare function isConcurrentMigrationApply(err: unknown): boolean;
 /**
  * Run all pending migrations on the provided database.
- * Idempotent: existing migrations are not re-applied.
+ * Idempotent: existing migrations are not re-applied. Each migration applies
+ * in its own transaction; a failure rolls back, is recorded for diagnosis
+ * (table row, or the marker fallback), and leaves the version un-bumped so
+ * the next open retries it.
  */
-export declare function runProjectMigrations(db: Database): void;
+export declare function runProjectMigrations(db: Database, markerDir?: string): void;
 /**
  * Return the absolute path to `.swarm/swarm.db` for the given directory.
  * Does not create the file or any parent directory.
@@ -26,13 +42,24 @@ export declare function projectDbExists(directory: string): boolean;
 /**
  * Return the cached project database for the given directory, opening it
  * if needed. Creates `.swarm/` if absent and enables WAL + foreign keys.
+ * The cache is keyed by canonical project identity, so case-varied Windows
+ * spellings, trailing separators, and symlinked roots share ONE handle.
+ * Open failures throw a typed `ProjectDbError` and never leave a
+ * half-open handle cached.
  */
 export declare function getProjectDb(directory: string): Database;
 /**
  * Close and remove the cached project database for the given directory.
- * Called by the `/swarm close` clean stage before unlinking `swarm.db` (so a
- * long-lived WAL-mode connection releases its file lock and Windows `unlink`
- * does not fail with EBUSY), and from tests.
+ * Runs a best-effort WAL checkpoint (TRUNCATE, PASSIVE fallback) first so the
+ * close leaves a self-contained DB file where possible. Called by the
+ * `/swarm close` clean stage before unlinking `swarm.db` (so a long-lived
+ * WAL-mode connection releases its file lock and Windows `unlink` does not
+ * fail with EBUSY), by the plugin dispose/exit close paths, and from tests.
+ *
+ * Callers that passed a different spelling of the same root (case variant on
+ * Windows, symlink) share the canonical handle: closing it invalidates every
+ * alias — which is the point (those aliases were previously silent duplicate
+ * writers on one file). Reopening via `getProjectDb` always works.
  */
 export declare function closeProjectDb(directory: string): void;
 /**

package/dist/db/qa-gate-profile.d.ts

@@ -31,6 +31,8 @@ export declare const _internals: {
         profileId: number;
         storagePlanId: string;
     }) => void) | undefined;
+    /** #2480 test probe: synchronous level observed during the last write txn. */
+    lastTxnSynchronous: number;
 };
 /**
  * QA gate flags. All eleven gates are tracked explicitly.

package/dist/hooks/curator-drift.d.ts

@@ -1,14 +1,18 @@
 import type { CriticDriftResult, CuratorConfig, CuratorPhaseResult, DriftReport } from './curator-types.js';
 /**
- * Read all prior drift reports from .swarm/drift-report-phase-*.json files.
+ * Read all prior drift reports (#2480: from the `phase_report` entity table
+ * in `.swarm/swarm.db`, kind `curator_drift`; the legacy
+ * `.swarm/drift-report-phase-*.json` files are imported once — idempotent,
+ * one-txn — and cold-archived `.json.imported`).
  * Returns reports sorted ascending by phase number.
- * Skips corrupt/unreadable files with a console.warn.
+ * Skips corrupt/unreadable payloads with a console.warn.
  */
 export declare function readPriorDriftReports(directory: string): Promise<DriftReport[]>;
 /**
- * Write a drift report to .swarm/drift-report-phase-{N}.json.
- * Creates .swarm/ if it doesn't exist.
- * Returns the absolute path of the written file.
+ * Write a drift report to the `phase_report` entity table (#2480: upsert via
+ * the group-commit writer — one txn per flush, atomic, replacing the legacy
+ * non-batched file rewrite). A same-phase re-run overwrites the row.
+ * Returns the DB-backed report locator.
  */
 export declare function writeDriftReport(directory: string, report: DriftReport): Promise<string>;
 export declare const _internals: {

package/dist/hooks/curator-types.d.ts

@@ -155,6 +155,7 @@ export interface SkillCandidate {
 export interface CriticDriftResult {
     phase: number;
     report: DriftReport;
+    /** #2480: DB-backed locator, e.g. `swarm.db:phase_report(curator_drift,3)`. */
     report_path: string;
     injection_text: string;
 }

package/dist/hooks/knowledge-curator.d.ts

@@ -69,9 +69,11 @@ export declare function enrichLessonToV3(params: {
 /** Max insight candidates folded into the store per phase boundary. */
 export declare const MESO_INSIGHT_BATCH_LIMIT = 20;
 /**
- * Atomically consume up to `batchLimit` insight candidates from
- * `.swarm/insight-candidates.jsonl`, writing back the unconsumed tail under the
- * same lock so concurrent micro-reflection appends are never lost. Fail-open.
+ * Atomically consume up to `batchLimit` insight candidates from the durable
+ * `insight_candidate` stream in `.swarm/swarm.db` (issue #2480). The SELECT
+ * and the consumed_at UPDATE happen in ONE immediate transaction, so
+ * concurrent appends are never lost and a batch is never double-taken.
+ * Fail-open: returns [] on any DB error.
  */
 export declare function consumeInsightCandidates(directory: string, batchLimit?: number): Promise<InsightCandidate[]>;
 /** Build a SwarmKnowledgeEntry from an already-v3-actionable insight candidate. */

package/dist/hooks/micro-reflector.d.ts

@@ -123,14 +123,19 @@ export declare function classifyOutcome(transcript: string, trajectory: Trajecto
 /** Read a task's trajectory slice. Fail-open: [] when absent/corrupt. */
 export declare function readTaskTrajectory(directory: string, taskId: string): Promise<TrajectoryEntry[]>;
 export declare const INSIGHT_CANDIDATES_MAX_ENTRIES = 500;
-/** Append validated candidates to the insight queue (best-effort, fail-open).
- *  Uses transactFile for consistency with consumeInsightCandidates and enforces
- *  a FIFO cap to prevent unbounded growth between phase completions.
+/**
+ * Append validated candidates to the insight queue (best-effort, fail-open).
+ *
+ * #2480: the durable queue is the `insight_candidate` stream table in
+ * `.swarm/swarm.db` (group-commit writer, one txn per flush; FIFO cap 500 on
+ * the pending queue — same bound as before). The legacy
+ * `.swarm/insight-candidates.jsonl` is imported once (idempotent, one-txn)
+ * and cold-archived `.jsonl.imported`.
  *
- *  EXPORTED (#1821) so the PRM pattern producer can write the SAME durable
- *  crash backstop the micro-reflector writes. Any producer that only enqueues
- *  in memory loses its candidate on process death, on queue overflow, and on a
- *  drain failure — with no phase-boundary fold-in to recover it. */
+ * EXPORTED (#1821) so the PRM pattern producer can write the SAME durable
+ * crash backstop the micro-reflector writes. Any producer that only enqueues
+ * in memory loses its candidate on process death, on queue overflow, and on a
+ * drain failure — with no phase-boundary fold-in to recover it. */
 export declare function appendInsightCandidates(directory: string, candidates: InsightCandidate[]): Promise<void>;
 /** Build the bounded micro-reflection prompt (≤ MICRO_PROMPT_INPUT_CAP chars). */
 export declare function buildMicroPrompt(params: {