mcp-coordinator 0.2.1 → 0.4.0

package/dist/src/consultation.js

@@ -4,12 +4,45 @@ import { silentLogger } from "./logger.js";
 export class Consultation {
     onResolveCallback = null;
     log;
+    timeoutSweeperHandle = null;
     constructor(logger) {
         this.log = logger || silentLogger;
     }
     onResolve(callback) {
         this.onResolveCallback = callback;
     }
+    /**
+     * B2 fix: replace the side-effect-on-read timeout check with an explicit
+     * background sweeper. Each tick atomically claims and resolves any thread
+     * past its deadline, then emits resolution events outside the transaction.
+     *
+     * Default tick interval: 30 seconds. Tests can pass a shorter interval to
+     * exercise the sweeper, or call checkTimeouts() explicitly.
+     *
+     * Safe to call multiple times — second call is a no-op until the previous
+     * sweeper is stopped.
+     */
+    startTimeoutSweeper(intervalMs = 30000) {
+        if (this.timeoutSweeperHandle)
+            return;
+        this.timeoutSweeperHandle = setInterval(() => {
+            try {
+                this.checkTimeouts();
+            }
+            catch (err) {
+                this.log.warn({ err }, "Timeout sweeper iteration failed");
+            }
+        }, intervalMs);
+        // Don't keep the event loop alive just for the sweeper.
+        if (typeof this.timeoutSweeperHandle.unref === "function")
+            this.timeoutSweeperHandle.unref();
+    }
+    stopTimeoutSweeper() {
+        if (this.timeoutSweeperHandle) {
+            clearInterval(this.timeoutSweeperHandle);
+            this.timeoutSweeperHandle = null;
+        }
+    }
     emitResolution(threadId, type, approvedBy, approvedByName) {
         const db = getDb();
         const thread = this.getThread(threadId);
@@ -39,23 +72,31 @@ export class Consultation {
     announceWork(params) {
         const db = getDb();
         const id = randomUUID();
-        // Find expected respondents: online agents (not initiator) whose modules overlap
-        const onlineAgents = db
-            .prepare("SELECT id, modules FROM agents WHERE status = 'online' AND id != ?")
-            .all(params.agent_id);
-        const respondents = onlineAgents.filter((agent) => {
-            const agentModules = JSON.parse(agent.modules);
-            return params.target_modules.some((tm) => agentModules.some((am) => am === tm || am.startsWith(tm + "/") || tm.startsWith(am + "/")));
+        // B1 fix: SELECT respondents + INSERT thread must be atomic w.r.t. agent
+        // registry mutations (registerAgent / setOffline). Without a transaction,
+        // a race between announce and a concurrent setOffline produces a thread
+        // whose expected_respondents contains an agent that just went away — the
+        // thread then stays open forever waiting for an absent voter.
+        const tx = db.transaction(() => {
+            const onlineAgents = db
+                .prepare("SELECT id, modules FROM agents WHERE status = 'online' AND id != ?")
+                .all(params.agent_id);
+            const respondents = onlineAgents.filter((agent) => {
+                const agentModules = JSON.parse(agent.modules);
+                return params.target_modules.some((tm) => agentModules.some((am) => am === tm || am.startsWith(tm + "/") || tm.startsWith(am + "/")));
+            });
+            const respondentIds = respondents.map((r) => r.id);
+            // Directed dispatch skips module-based auto-resolve: if the thread is
+            // explicitly aimed at an agent, we keep it open for them regardless of
+            // what the module scorer finds.
+            const assignedTo = params.assigned_to ?? null;
+            const keepOpen = params.keep_open || assignedTo !== null;
+            const autoResolve = respondentIds.length === 0 && !keepOpen;
+            db.prepare(`INSERT INTO threads (id, initiator_id, subject, plan, target_modules, target_files, status, expected_respondents, resolved_at, depends_on_files, exports_affected, timeout_seconds, assigned_to)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, params.agent_id, params.subject, params.plan || null, JSON.stringify(params.target_modules), JSON.stringify(params.target_files), autoResolve ? "resolved" : "open", JSON.stringify(respondentIds), autoResolve ? new Date().toISOString() : null, JSON.stringify(params.depends_on_files || []), JSON.stringify(params.exports_affected || []), keepOpen ? 0 : 600, assignedTo);
+            return { autoResolve, respondentIds, assignedTo };
         });
-        const respondentIds = respondents.map((r) => r.id);
-        // Directed dispatch skips module-based auto-resolve: if the thread is
-        // explicitly aimed at an agent, we keep it open for them regardless of
-        // what the module scorer finds.
-        const assignedTo = params.assigned_to ?? null;
-        const keepOpen = params.keep_open || assignedTo !== null;
-        const autoResolve = respondentIds.length === 0 && !keepOpen;
-        db.prepare(`INSERT INTO threads (id, initiator_id, subject, plan, target_modules, target_files, status, expected_respondents, resolved_at, depends_on_files, exports_affected, timeout_seconds, assigned_to)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, params.agent_id, params.subject, params.plan || null, JSON.stringify(params.target_modules), JSON.stringify(params.target_files), autoResolve ? "resolved" : "open", JSON.stringify(respondentIds), autoResolve ? new Date().toISOString() : null, JSON.stringify(params.depends_on_files || []), JSON.stringify(params.exports_affected || []), keepOpen ? 0 : 600, assignedTo);
+        const { autoResolve, respondentIds, assignedTo } = tx();
         this.log.info({
             thread_id: id,
             agent_id: params.agent_id,
@@ -81,7 +122,7 @@ export class Consultation {
         const id = randomUUID();
         // Simple token estimate: ~4 chars per token for English/French
         const tokenEstimate = Math.ceil(params.content.length / 4);
-        db.prepare(`INSERT INTO thread_messages (id, thread_id, agent_id, agent_name, type, content, context_snapshot, in_reply_to, round, token_estimate)
+        db.prepare(`INSERT INTO thread_messages (id, thread_id, agent_id, agent_name, type, content, context_snapshot, in_reply_to, round, token_estimate)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, params.thread_id, params.agent_id, params.agent_name || null, params.type, params.content, params.context_snapshot || null, params.in_reply_to || null, thread.round, tokenEstimate);
         this.log.debug({
             thread_id: params.thread_id,
@@ -109,12 +150,23 @@ export class Consultation {
             throw new Error(`Thread ${threadId} not found`);
         if (thread.status !== "resolving")
             throw new Error(`Thread is ${thread.status}, not resolving`);
-        // Post approve message
-        this.postResolutionMessage(threadId, agentId, "approve", "Approved");
+        // B1 fix: post + check + transition must be atomic, else two concurrent
+        // approvals each see "all approved" and fire emitResolution twice. Using
+        // a transaction + UPDATE ... WHERE status='resolving' (CAS) ensures only
+        // the first transaction wins the consensus race; the loser's UPDATE
+        // affects 0 rows and emit is suppressed.
+        const tx = db.transaction(() => {
+            this.postResolutionMessage(threadId, agentId, "approve", "Approved");
+            if (!this.allRespondentsApproved(threadId))
+                return false;
+            const res = db
+                .prepare("UPDATE threads SET status = 'resolved', resolved_at = ? WHERE id = ? AND status = 'resolving'")
+                .run(new Date().toISOString(), threadId);
+            return res.changes > 0;
+        });
+        const wonRace = tx();
         this.log.debug({ thread_id: threadId, agent_id: agentId }, "Resolution approved");
-        // Check if all expected respondents have approved
-        if (this.allRespondentsApproved(threadId)) {
-            db.prepare("UPDATE threads SET status = 'resolved', resolved_at = ? WHERE id = ?").run(new Date().toISOString(), threadId);
+        if (wonRace) {
             this.emitResolution(threadId, "consensus", agentId, agentName || agentId);
         }
     }
@@ -194,30 +246,43 @@ export class Consultation {
     }
     checkTimeouts() {
         const db = getDb();
-        // Get threads that will be timed out (before updating them)
-        const timedOut = db.prepare(`
-      SELECT id FROM threads
-      WHERE status IN ('open', 'resolving')
-      AND timeout_seconds > 0
-      AND datetime(created_at, '+' || (timeout_seconds * round) || ' seconds') < CURRENT_TIMESTAMP
-    `).all();
+        // B2 fix: SELECT-then-UPDATE wrapped in a transaction so two concurrent
+        // sweepers can't both claim the same thread. The UPDATE returns
+        // db.changes (rows affected) — we use the SELECT only to know which
+        // thread IDs to emit for. The transaction makes both observe the same
+        // snapshot.
+        const tx = db.transaction(() => {
+            const timedOut = db.prepare(`
+        SELECT id FROM threads
+        WHERE status IN ('open', 'resolving')
+        AND timeout_seconds > 0
+        AND datetime(created_at, '+' || (timeout_seconds * round) || ' seconds') < CURRENT_TIMESTAMP
+      `).all();
+            if (timedOut.length === 0)
+                return [];
+            db.prepare(`
+        UPDATE threads SET status = 'resolved',
+          resolution_summary = 'Résolu par timeout — pas de réponse dans le délai',
+          resolved_at = CURRENT_TIMESTAMP
+        WHERE status IN ('open', 'resolving')
+        AND timeout_seconds > 0
+        AND datetime(created_at, '+' || (timeout_seconds * round) || ' seconds') < CURRENT_TIMESTAMP
+      `).run();
+            return timedOut;
+        });
+        const timedOut = tx();
         if (timedOut.length === 0)
             return;
-        db.prepare(`
-      UPDATE threads SET status = 'resolved',
-        resolution_summary = 'Résolu par timeout — pas de réponse dans le délai',
-        resolved_at = CURRENT_TIMESTAMP
-      WHERE status IN ('open', 'resolving')
-      AND timeout_seconds > 0
-      AND datetime(created_at, '+' || (timeout_seconds * round) || ' seconds') < CURRENT_TIMESTAMP
-    `).run();
         this.log.info({ count: timedOut.length, thread_ids: timedOut.map(t => t.id) }, "Threads timed out");
+        // Emit OUTSIDE the transaction so listeners can re-enter the DB safely.
         for (const t of timedOut) {
             this.emitResolution(t.id, "timeout");
         }
     }
     getThread(threadId) {
-        this.checkTimeouts();
+        // B2 fix: timeout sweeping moved to startTimeoutSweeper() background timer.
+        // Reads no longer mutate state. Tests that need synchronous timeout
+        // resolution should call checkTimeouts() explicitly.
         const db = getDb();
         return (db.prepare("SELECT * FROM threads WHERE id = ?").get(threadId) || null);
     }
@@ -232,7 +297,7 @@ export class Consultation {
         return { thread, messages };
     }
     listThreads(filters) {
-        this.checkTimeouts();
+        // B2 fix: removed checkTimeouts() side-effect; sweeper handles it.
         const db = getDb();
         let sql = "SELECT * FROM threads WHERE 1=1";
         const params = [];
@@ -255,14 +320,22 @@ export class Consultation {
             sql += " AND (assigned_to IS NULL OR assigned_to = ?)";
             params.push(filters.assigned_to_me);
         }
+        if (typeof filters.since_minutes === "number") {
+            // For resolved threads, gate on resolved_at (the moment that matters
+            // for "recent enough to still influence scoring"). For open/resolving
+            // threads, gate on created_at since they have no resolved_at yet.
+            // COALESCE picks the right column per row.
+            sql += " AND COALESCE(resolved_at, created_at) > datetime('now', '-' || ? || ' minutes')";
+            params.push(filters.since_minutes);
+        }
         sql += " ORDER BY created_at DESC";
         return db.prepare(sql).all(...params);
     }
     getThreadUpdates(agentId, since) {
         const db = getDb();
-        let sql = `SELECT tm.* FROM thread_messages tm
-               JOIN threads t ON tm.thread_id = t.id
-               WHERE t.status IN ('open', 'resolving')
+        let sql = `SELECT tm.* FROM thread_messages tm
+               JOIN threads t ON tm.thread_id = t.id
+               WHERE t.status IN ('open', 'resolving')
                AND tm.agent_id != ?`;
         const params = [agentId];
         if (since) {
@@ -284,7 +357,7 @@ export class Consultation {
     logActionSummary(params) {
         const db = getDb();
         const id = randomUUID();
-        db.prepare(`INSERT INTO action_summaries (id, session_id, agent_id, file_path, summary)
+        db.prepare(`INSERT INTO action_summaries (id, session_id, agent_id, file_path, summary)
        VALUES (?, ?, ?, ?, ?)`).run(id, params.session_id, params.agent_id, params.file_path || null, params.summary);
         return db.prepare("SELECT * FROM action_summaries WHERE id = ?").get(id);
     }
@@ -310,7 +383,7 @@ export class Consultation {
         const db = getDb();
         const thread = this.getThread(threadId);
         const id = randomUUID();
-        db.prepare(`INSERT INTO thread_messages (id, thread_id, agent_id, type, content, round)
+        db.prepare(`INSERT INTO thread_messages (id, thread_id, agent_id, type, content, round)
        VALUES (?, ?, ?, ?, ?, ?)`).run(id, threadId, agentId, type, content, thread.round);
     }
     allRespondentsApproved(threadId) {
@@ -323,7 +396,7 @@ export class Consultation {
         // increments the round, and prior-round approvals must be re-collected
         // for the new proposal.
         const approvals = db
-            .prepare(`SELECT DISTINCT agent_id FROM thread_messages
+            .prepare(`SELECT DISTINCT agent_id FROM thread_messages
          WHERE thread_id = ? AND type = 'approve' AND round = ?`)
             .all(threadId, thread.round);
         const approvedIds = new Set(approvals.map((a) => a.agent_id));

package/dist/src/database.js

@@ -3,132 +3,132 @@ import { mkdirSync } from "fs";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 let db;
-const SCHEMA = `
-    CREATE TABLE IF NOT EXISTS agents (
-      id TEXT PRIMARY KEY,
-      name TEXT NOT NULL,
-      modules TEXT DEFAULT '[]',
-      status TEXT DEFAULT 'offline',
-      registered_at TEXT DEFAULT CURRENT_TIMESTAMP,
-      last_seen_at TEXT DEFAULT CURRENT_TIMESTAMP
-    );
-
-    CREATE TABLE IF NOT EXISTS threads (
-      id TEXT PRIMARY KEY,
-      initiator_id TEXT NOT NULL,
-      subject TEXT NOT NULL,
-      plan TEXT,
-      target_modules TEXT DEFAULT '[]',
-      target_files TEXT DEFAULT '[]',
-      status TEXT DEFAULT 'open',
-      resolution_summary TEXT,
-      conflicts TEXT,
-      round INTEGER DEFAULT 1,
-      max_rounds INTEGER DEFAULT 4,
-      timeout_seconds INTEGER DEFAULT 600,
-      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-      resolved_at TEXT,
-      expected_respondents TEXT,
-      depends_on_files TEXT,
-      exports_affected TEXT,
-      claimed_by TEXT,
-      claimed_at TEXT,
-      FOREIGN KEY (initiator_id) REFERENCES agents(id)
-    );
-
-    CREATE TABLE IF NOT EXISTS thread_messages (
-      id TEXT PRIMARY KEY,
-      thread_id TEXT NOT NULL,
-      agent_id TEXT NOT NULL,
-      agent_name TEXT,
-      type TEXT NOT NULL,
-      content TEXT NOT NULL,
-      context_snapshot TEXT,
-      in_reply_to TEXT,
-      round INTEGER NOT NULL,
-      token_estimate INTEGER DEFAULT 0,
-      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-      FOREIGN KEY (thread_id) REFERENCES threads(id),
-      FOREIGN KEY (agent_id) REFERENCES agents(id)
-    );
-
-    CREATE TABLE IF NOT EXISTS action_summaries (
-      id TEXT PRIMARY KEY,
-      session_id TEXT NOT NULL,
-      agent_id TEXT NOT NULL,
-      file_path TEXT,
-      summary TEXT NOT NULL,
-      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-      FOREIGN KEY (agent_id) REFERENCES agents(id)
-    );
-
-    CREATE TABLE IF NOT EXISTS events (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      type TEXT NOT NULL,
-      payload TEXT NOT NULL,
-      created_at TEXT DEFAULT CURRENT_TIMESTAMP
-    );
-
-    CREATE TABLE IF NOT EXISTS dependency_map (
-      module_id TEXT PRIMARY KEY,
-      depends_on TEXT DEFAULT '[]',
-      exports TEXT DEFAULT '[]',
-      owners TEXT DEFAULT '[]'
-    );
-
-    CREATE TABLE IF NOT EXISTS file_activity (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      session_id TEXT NOT NULL,
-      agent_id TEXT NOT NULL,
-      agent_name TEXT,
-      tool_name TEXT NOT NULL,
-      file_path TEXT NOT NULL,
-      module TEXT,
-      created_at TEXT DEFAULT CURRENT_TIMESTAMP
-    );
-
-    CREATE INDEX IF NOT EXISTS idx_threads_status ON threads(status);
-    CREATE INDEX IF NOT EXISTS idx_threads_initiator ON threads(initiator_id);
-    CREATE INDEX IF NOT EXISTS idx_messages_thread ON thread_messages(thread_id);
-    CREATE INDEX IF NOT EXISTS idx_messages_agent ON thread_messages(agent_id);
-    CREATE INDEX IF NOT EXISTS idx_summaries_agent ON action_summaries(agent_id);
-    CREATE INDEX IF NOT EXISTS idx_summaries_session ON action_summaries(session_id);
-    CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
-    CREATE INDEX IF NOT EXISTS idx_file_activity_agent ON file_activity(agent_id);
-    CREATE INDEX IF NOT EXISTS idx_file_activity_path ON file_activity(file_path);
-
-    CREATE TABLE IF NOT EXISTS introspections (
-      id TEXT PRIMARY KEY,
-      thread_id TEXT NOT NULL,
-      agent_id TEXT NOT NULL,
-      score INTEGER NOT NULL,
-      reasons TEXT,
-      status TEXT DEFAULT 'pending',
-      response TEXT,
-      concerned INTEGER DEFAULT 0,
-      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-      responded_at TEXT,
-      FOREIGN KEY (thread_id) REFERENCES threads(id),
-      FOREIGN KEY (agent_id) REFERENCES agents(id)
-    );
-
-    CREATE INDEX IF NOT EXISTS idx_introspections_agent ON introspections(agent_id);
-    CREATE INDEX IF NOT EXISTS idx_introspections_status ON introspections(status);
-
-    CREATE TABLE IF NOT EXISTS agent_activity_status (
-      agent_id TEXT PRIMARY KEY,
-      activity_status TEXT DEFAULT 'idle',
-      current_file TEXT,
-      current_thread TEXT,
-      last_activity_at TEXT DEFAULT CURRENT_TIMESTAMP,
-      FOREIGN KEY (agent_id) REFERENCES agents(id)
-    );
-
-    CREATE TABLE IF NOT EXISTS revoked_agents (
-      agent_id TEXT PRIMARY KEY,
-      revoked_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
-      revoked_by TEXT NOT NULL
-    );
+const SCHEMA = `
+    CREATE TABLE IF NOT EXISTS agents (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      modules TEXT DEFAULT '[]',
+      status TEXT DEFAULT 'offline',
+      registered_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      last_seen_at TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE TABLE IF NOT EXISTS threads (
+      id TEXT PRIMARY KEY,
+      initiator_id TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      plan TEXT,
+      target_modules TEXT DEFAULT '[]',
+      target_files TEXT DEFAULT '[]',
+      status TEXT DEFAULT 'open',
+      resolution_summary TEXT,
+      conflicts TEXT,
+      round INTEGER DEFAULT 1,
+      max_rounds INTEGER DEFAULT 4,
+      timeout_seconds INTEGER DEFAULT 600,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      resolved_at TEXT,
+      expected_respondents TEXT,
+      depends_on_files TEXT,
+      exports_affected TEXT,
+      claimed_by TEXT,
+      claimed_at TEXT,
+      FOREIGN KEY (initiator_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS thread_messages (
+      id TEXT PRIMARY KEY,
+      thread_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      agent_name TEXT,
+      type TEXT NOT NULL,
+      content TEXT NOT NULL,
+      context_snapshot TEXT,
+      in_reply_to TEXT,
+      round INTEGER NOT NULL,
+      token_estimate INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (thread_id) REFERENCES threads(id),
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS action_summaries (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      file_path TEXT,
+      summary TEXT NOT NULL,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      payload TEXT NOT NULL,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE TABLE IF NOT EXISTS dependency_map (
+      module_id TEXT PRIMARY KEY,
+      depends_on TEXT DEFAULT '[]',
+      exports TEXT DEFAULT '[]',
+      owners TEXT DEFAULT '[]'
+    );
+
+    CREATE TABLE IF NOT EXISTS file_activity (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      agent_name TEXT,
+      tool_name TEXT NOT NULL,
+      file_path TEXT NOT NULL,
+      module TEXT,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_threads_status ON threads(status);
+    CREATE INDEX IF NOT EXISTS idx_threads_initiator ON threads(initiator_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_thread ON thread_messages(thread_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_agent ON thread_messages(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_summaries_agent ON action_summaries(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_summaries_session ON action_summaries(session_id);
+    CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+    CREATE INDEX IF NOT EXISTS idx_file_activity_agent ON file_activity(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_file_activity_path ON file_activity(file_path);
+
+    CREATE TABLE IF NOT EXISTS introspections (
+      id TEXT PRIMARY KEY,
+      thread_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      score INTEGER NOT NULL,
+      reasons TEXT,
+      status TEXT DEFAULT 'pending',
+      response TEXT,
+      concerned INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      responded_at TEXT,
+      FOREIGN KEY (thread_id) REFERENCES threads(id),
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_introspections_agent ON introspections(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_introspections_status ON introspections(status);
+
+    CREATE TABLE IF NOT EXISTS agent_activity_status (
+      agent_id TEXT PRIMARY KEY,
+      activity_status TEXT DEFAULT 'idle',
+      current_file TEXT,
+      current_thread TEXT,
+      last_activity_at TEXT DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS revoked_agents (
+      agent_id TEXT PRIMARY KEY,
+      revoked_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      revoked_by TEXT NOT NULL
+    );
 `;
 function createBetterSqlite3(dataDir) {
     mkdirSync(dataDir, { recursive: true });

package/dist/src/db-adapter.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Database adapter surface.
+ *
+ * Design intent: this file is the *contract* both `createBetterSqlite3` and
+ * `createBunSqlite` (in `database.ts`) implement. The interfaces are a strict
+ * subset of better-sqlite3's API that Bun:sqlite also satisfies, so callers
+ * stay portable across both runtimes.
+ *
+ * Helpers (e.g. `withTransaction`) live here so portable code paths can use
+ * one canonical entry point without each call site re-deriving the
+ * `db.transaction(fn)()` two-step pattern.
+ */
 export interface RunResult {
     changes: number;
     lastInsertRowid: number;
@@ -13,3 +25,21 @@ export interface DatabaseAdapter {
     close(): void;
     transaction<T>(fn: () => T): () => T;
 }
+/**
+ * Run `fn` inside a single SQLite transaction and return its result.
+ *
+ * Replaces the verbose two-step pattern:
+ *
+ *     const tx = db.transaction(() => { ...; return value; });
+ *     const value = tx();
+ *
+ * with:
+ *
+ *     const value = withTransaction(db, () => { ...; return value; });
+ *
+ * Errors thrown inside `fn` propagate to the caller and the transaction is
+ * rolled back by the underlying driver (better-sqlite3 / bun:sqlite both do
+ * this). Use this for any read-modify-write block where multiple statements
+ * must be atomic.
+ */
+export declare function withTransaction<T>(db: DatabaseAdapter, fn: () => T): T;

package/dist/src/db-adapter.js

@@ -1 +1,32 @@
-export {};
+/**
+ * Database adapter surface.
+ *
+ * Design intent: this file is the *contract* both `createBetterSqlite3` and
+ * `createBunSqlite` (in `database.ts`) implement. The interfaces are a strict
+ * subset of better-sqlite3's API that Bun:sqlite also satisfies, so callers
+ * stay portable across both runtimes.
+ *
+ * Helpers (e.g. `withTransaction`) live here so portable code paths can use
+ * one canonical entry point without each call site re-deriving the
+ * `db.transaction(fn)()` two-step pattern.
+ */
+/**
+ * Run `fn` inside a single SQLite transaction and return its result.
+ *
+ * Replaces the verbose two-step pattern:
+ *
+ *     const tx = db.transaction(() => { ...; return value; });
+ *     const value = tx();
+ *
+ * with:
+ *
+ *     const value = withTransaction(db, () => { ...; return value; });
+ *
+ * Errors thrown inside `fn` propagate to the caller and the transaction is
+ * rolled back by the underlying driver (better-sqlite3 / bun:sqlite both do
+ * this). Use this for any read-modify-write block where multiple statements
+ * must be atomic.
+ */
+export function withTransaction(db, fn) {
+    return db.transaction(fn)();
+}

package/dist/src/dependency-map.js

@@ -1,4 +1,5 @@
 import { getDb } from "./database.js";
+import { withTransaction } from "./db-adapter.js";
 export class DependencyMapper {
     getMap() {
         const db = getDb();
@@ -16,16 +17,15 @@ export class DependencyMapper {
     }
     setMap(map) {
         const db = getDb();
-        const stmt = db.prepare(`INSERT INTO dependency_map (module_id, depends_on, exports, owners)
-       VALUES (?, ?, ?, ?)
-       ON CONFLICT(module_id) DO UPDATE SET
+        const stmt = db.prepare(`INSERT INTO dependency_map (module_id, depends_on, exports, owners)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(module_id) DO UPDATE SET
          depends_on = excluded.depends_on, exports = excluded.exports, owners = excluded.owners`);
-        const tx = db.transaction(() => {
+        withTransaction(db, () => {
             for (const [id, info] of Object.entries(map)) {
                 stmt.run(id, JSON.stringify(info.depends_on), JSON.stringify(info.exports), JSON.stringify(info.owners));
             }
         });
-        tx();
     }
     getModuleInfo(moduleId) {
         const db = getDb();

package/dist/src/file-tracker.d.ts

@@ -17,5 +17,15 @@ export declare class FileTracker {
         conflict: boolean;
         agents: string[];
     };
+    /**
+     * P2 perf: batch lookup of recent file→agents activity. Replaces N
+     * `checkFileConflict` calls (one per file) with a single SQL query, then
+     * builds an in-memory reverse index. The impact scorer uses this so its
+     * per-file inner loop is O(1) Map.get() rather than O(F) SQL round-trips.
+     *
+     * Excludes the calling agent (so the scorer doesn't flag the announcer
+     * against themselves). Returns Map<file_path, Set<agent_id>>.
+     */
+    getFileToAgentsIndex(filePaths: string[], excludeAgentId: string, withinMinutes?: number): Map<string, Set<string>>;
     fileToModule(filePath: string): string;
 }