mcp-coordinator 0.2.1 → 0.4.0

package/dist/cli/dashboard.js

@@ -1,14 +1,18 @@
 import { Command } from "commander";
-import { exec } from "child_process";
+import { spawn } from "child_process";
 export function createDashboardCommand() {
     return new Command("dashboard")
         .description("Open the real-time dashboard")
         .action(() => {
         const url = "http://localhost:3100/dashboard";
         console.log(`Dashboard: ${url}`);
-        const cmd = process.platform === "darwin"
-            ? `open "${url}"`
-            : `xdg-open "${url}" 2>/dev/null`;
-        exec(cmd, () => { });
+        // Use spawn with an argv array (no shell) so the URL is never
+        // interpolated into a shell command — eliminates command-injection risk.
+        const opener = process.platform === "darwin" ? "open"
+            : process.platform === "win32" ? "explorer.exe"
+                : "xdg-open";
+        const child = spawn(opener, [url], { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
     });
 }

package/dist/cli/server/backup.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * Check whether the coordinator daemon appears to be running.
+ * Returns the pid if alive, or null otherwise.
+ */
+export declare function getRunningCoordinatorPid(configDir: string): number | null;
+export declare function createServerBackupCommand(): Command;

package/dist/cli/server/backup.js

@@ -0,0 +1,162 @@
+import { Command } from "commander";
+import { existsSync, readFileSync, statSync } from "fs";
+import { join, resolve, basename } from "path";
+import { create as tarCreate } from "tar";
+import { getConfigDir, loadConfig } from "../config.js";
+/**
+ * Format a timestamp suitable for filenames: YYYY-MM-DD-HHMMSS (UTC).
+ */
+function timestampSlug(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}` +
+        `-${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}`);
+}
+/**
+ * Returns true if a process with the given pid is currently alive.
+ * On both POSIX and Windows, sending signal 0 acts as a liveness probe
+ * (it raises ESRCH if the process is dead, EPERM if alive but not ours).
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but we lack permission — still "alive".
+        if (err.code === "EPERM")
+            return true;
+        return false;
+    }
+}
+/**
+ * Check whether the coordinator daemon appears to be running.
+ * Returns the pid if alive, or null otherwise.
+ */
+export function getRunningCoordinatorPid(configDir) {
+    const pidPath = join(configDir, "server.pid");
+    if (!existsSync(pidPath))
+        return null;
+    const raw = readFileSync(pidPath, "utf-8").trim();
+    const pid = parseInt(raw, 10);
+    if (Number.isNaN(pid))
+        return null;
+    return isProcessAlive(pid) ? pid : null;
+}
+/**
+ * Recursively walk a directory and yield relative file paths.
+ * Used purely for reporting (file count) — tar handles the actual packing.
+ */
+async function countFiles(root) {
+    const { readdir, stat } = await import("fs/promises");
+    let count = 0;
+    const walk = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                count += 1;
+            }
+        }
+    };
+    if (existsSync(root))
+        await walk(root);
+    return count;
+}
+/**
+ * Build the list of entries (relative to configDir) we want to include in the
+ * tarball. We deliberately keep the layout flat — the same paths used at
+ * runtime — so a `tar -xzf` into `~/.mcp-coordinator/` is a valid restore.
+ *
+ * NOTE on live backups: this command refuses to run while the coordinator is
+ * up because better-sqlite3's WAL journal may have uncommitted writes that
+ * file-copy will miss. For online backups, switch to SQLite's Online Backup
+ * API (`db.backup(path)` from better-sqlite3) and snapshot config.json
+ * separately — see docs/superpowers/working/v04/backup-integration.md.
+ */
+function buildEntries(configDir, dataDirAbsolute) {
+    const entries = [];
+    if (existsSync(join(configDir, "config.json")))
+        entries.push("config.json");
+    // The data dir might live outside ~/.mcp-coordinator (custom --data-dir).
+    // tar's `cwd` option can only point at one directory, so when the data dir
+    // is non-default we pack it under its absolute path inside the archive
+    // (preserving structure for round-trip restore via --data-dir).
+    const defaultDataDir = join(configDir, "data");
+    if (resolve(dataDirAbsolute) === resolve(defaultDataDir) && existsSync(defaultDataDir)) {
+        entries.push("data");
+    }
+    return entries;
+}
+export function createServerBackupCommand() {
+    return new Command("backup")
+        .description("Snapshot the coordinator config + SQLite database to a tar.gz archive")
+        .option("--output <path>", "Output tarball path (default ./mcp-coordinator-backup-<ts>.tar.gz)")
+        .option("--data-dir <path>", "Data directory to back up (overrides config.server.data_dir)")
+        .option("--force", "Skip the running-coordinator safety check")
+        .action(async (opts) => {
+        const configDir = getConfigDir();
+        const config = loadConfig(configDir);
+        const dataDir = resolve(opts.dataDir ?? process.env.COORDINATOR_DATA_DIR ?? config.server.data_dir);
+        // Safety: refuse when the daemon is up. WAL writes might be in flight.
+        const runningPid = getRunningCoordinatorPid(configDir);
+        if (runningPid !== null && !opts.force) {
+            console.error(`Coordinator is running (PID ${runningPid}).`);
+            console.error("Refusing to back up: live SQLite WAL writes may be in flight.");
+            console.error("Either stop it first ('mcp-coordinator server stop') or pass --force.");
+            process.exit(1);
+        }
+        if (!existsSync(configDir)) {
+            console.error(`No coordinator config directory at ${configDir} — nothing to back up.`);
+            process.exit(1);
+        }
+        const ts = timestampSlug();
+        const outputPath = resolve(opts.output ?? join(process.cwd(), `mcp-coordinator-backup-${ts}.tar.gz`));
+        const defaultDataDir = join(configDir, "data");
+        const dataIsCustom = resolve(dataDir) !== resolve(defaultDataDir);
+        // Pack ~/.mcp-coordinator entries from configDir as cwd.
+        const entries = buildEntries(configDir, dataDir);
+        // For custom data dirs, pack them under their absolute path so restore
+        // can reproduce the original location (or be redirected with --data-dir).
+        const customDataEntries = [];
+        if (dataIsCustom && existsSync(dataDir)) {
+            customDataEntries.push({ cwd: resolve(dataDir, ".."), entry: basename(dataDir) });
+        }
+        if (entries.length === 0 && customDataEntries.length === 0) {
+            console.error("Nothing to back up: no config.json and no data directory found.");
+            process.exit(1);
+        }
+        // First archive pass: config + default data (if any).
+        if (entries.length > 0) {
+            await tarCreate({ gzip: true, file: outputPath, cwd: configDir, portable: true }, entries);
+        }
+        // Second pass for a custom data dir — append into the same archive.
+        // tar's gzip mode doesn't support append, so we re-create instead by
+        // extracting the previous entries and re-packing. Simpler path: emit
+        // a sibling .data.tar.gz when custom dir is in use, and document it.
+        if (customDataEntries.length > 0) {
+            const dataArchive = outputPath.replace(/\.tar\.gz$/, ".data.tar.gz");
+            for (const { cwd, entry } of customDataEntries) {
+                await tarCreate({ gzip: true, file: dataArchive, cwd, portable: true }, [entry]);
+            }
+            console.log(`Custom data dir packed separately: ${dataArchive}`);
+        }
+        // outputPath only exists if entries.length > 0; report on whichever
+        // archive(s) we actually produced.
+        const reportPath = entries.length > 0
+            ? outputPath
+            : outputPath.replace(/\.tar\.gz$/, ".data.tar.gz");
+        const sizeBytes = existsSync(reportPath) ? statSync(reportPath).size : 0;
+        const sizeMB = (sizeBytes / (1024 * 1024)).toFixed(2);
+        const fileCount = (existsSync(join(configDir, "config.json")) ? 1 : 0) +
+            (await countFiles(dataIsCustom ? dataDir : defaultDataDir));
+        console.log("Backup complete.");
+        console.log(`  Archive:   ${reportPath}`);
+        console.log(`  Size:      ${sizeMB} MB (${sizeBytes} bytes)`);
+        console.log(`  Files:     ${fileCount}`);
+        console.log(`  ConfigDir: ${configDir}`);
+        console.log(`  DataDir:   ${dataDir}${dataIsCustom ? " (custom)" : ""}`);
+    });
+}

package/dist/cli/server/index.js

@@ -3,11 +3,16 @@ import { createServerStartCommand } from "./start.js";
 import { createServerStopCommand } from "./stop.js";
 import { createServerStatusCommand } from "./status.js";
 import { createServerLogsCommand } from "./logs.js";
+import { createServerBackupCommand } from "./backup.js";
+import { createServerRestoreCommand } from "./restore.js";
 export function createServerProgram() {
     const server = new Command("server").description("Manage the coordination server");
     server.addCommand(createServerStartCommand());
     server.addCommand(createServerStopCommand());
     server.addCommand(createServerStatusCommand());
     server.addCommand(createServerLogsCommand());
+    // v0.4 Operability
+    server.addCommand(createServerBackupCommand());
+    server.addCommand(createServerRestoreCommand());
     return server;
 }

package/dist/cli/server/restore.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createServerRestoreCommand(): Command;

package/dist/cli/server/restore.js

@@ -0,0 +1,117 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync, renameSync, statSync } from "fs";
+import { resolve } from "path";
+import { extract as tarExtract, list as tarList } from "tar";
+import { getConfigDir } from "../config.js";
+import { getRunningCoordinatorPid } from "./backup.js";
+function timestampSlug(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}` +
+        `-${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}`);
+}
+/**
+ * Inspect the tarball without extracting and return the list of top-level
+ * entries (file or dir names). Used to validate structure before touching
+ * the user's existing config dir.
+ */
+async function listTarballEntries(tarPath) {
+    const entries = [];
+    await tarList({
+        file: tarPath,
+        onReadEntry: (entry) => {
+            // Trailing slash on dirs — strip it, take the first path segment only.
+            const head = entry.path.replace(/\\/g, "/").split("/")[0];
+            if (head && !entries.includes(head))
+                entries.push(head);
+        },
+    });
+    return entries;
+}
+export function createServerRestoreCommand() {
+    return new Command("restore")
+        .description("Restore a coordinator config + database snapshot from a tar.gz archive")
+        .argument("<tarball>", "Path to the backup .tar.gz produced by 'mcp-coordinator server backup'")
+        .option("--force", "Skip the running-coordinator safety check")
+        .option("--no-backup", "Do not snapshot the existing config dir before overwriting")
+        .option("--data-dir <path>", "Override data directory (rarely needed)")
+        .action(async (tarballArg, opts) => {
+        const tarPath = resolve(tarballArg);
+        if (!existsSync(tarPath)) {
+            console.error(`Tarball not found: ${tarPath}`);
+            process.exit(1);
+        }
+        const tarStat = statSync(tarPath);
+        if (!tarStat.isFile()) {
+            console.error(`Not a regular file: ${tarPath}`);
+            process.exit(1);
+        }
+        const configDir = getConfigDir();
+        // Safety: refuse when the daemon is running so we don't clobber an
+        // open SQLite handle (would corrupt the WAL on the daemon side).
+        const runningPid = getRunningCoordinatorPid(configDir);
+        if (runningPid !== null && !opts.force) {
+            console.error(`Coordinator is running (PID ${runningPid}).`);
+            console.error("Refusing to restore: stop the coordinator first or pass --force.");
+            process.exit(1);
+        }
+        // Validate tarball contents BEFORE moving anything aside.
+        let entries;
+        try {
+            entries = await listTarballEntries(tarPath);
+        }
+        catch (err) {
+            console.error(`Failed to read tarball: ${err.message}`);
+            process.exit(1);
+        }
+        const hasConfig = entries.includes("config.json");
+        const hasData = entries.includes("data");
+        if (!hasConfig && !hasData) {
+            console.error("Tarball does not contain expected entries (config.json or data/).");
+            console.error(`Top-level entries found: ${entries.join(", ") || "(none)"}`);
+            process.exit(1);
+        }
+        // Snapshot the existing config dir before overwriting.
+        // commander auto-flips `--no-backup` -> opts.backup = false. The default
+        // value is `true` (the option is registered with .option("--no-backup")
+        // below, which makes commander seed `opts.backup = true`).
+        const shouldSnapshot = opts.backup !== false;
+        let snapshotPath = null;
+        if (shouldSnapshot && existsSync(configDir)) {
+            snapshotPath = `${configDir}.bak-${timestampSlug()}`;
+            renameSync(configDir, snapshotPath);
+            console.log(`Existing config moved aside: ${snapshotPath}`);
+        }
+        // Recreate the target dir and extract.
+        mkdirSync(configDir, { recursive: true });
+        try {
+            await tarExtract({ file: tarPath, cwd: configDir });
+        }
+        catch (err) {
+            console.error(`Extraction failed: ${err.message}`);
+            // Try to roll back the snapshot if we made one.
+            if (snapshotPath !== null && existsSync(snapshotPath)) {
+                // Best-effort: only roll back if extraction created an empty dir.
+                try {
+                    renameSync(configDir, `${configDir}.failed-${timestampSlug()}`);
+                    renameSync(snapshotPath, configDir);
+                    console.error("Rolled back to previous config dir.");
+                }
+                catch {
+                    console.error(`Manual recovery required — snapshot at: ${snapshotPath}`);
+                }
+            }
+            process.exit(1);
+        }
+        console.log("Restore complete.");
+        console.log(`  Source:    ${tarPath}`);
+        console.log(`  ConfigDir: ${configDir}`);
+        console.log(`  Restored:  ${entries.filter((e) => e === "config.json" || e === "data").join(", ")}`);
+        if (snapshotPath !== null) {
+            console.log(`  Previous:  ${snapshotPath}  (delete once verified)`);
+        }
+        if (opts.dataDir !== undefined) {
+            console.log(`  Note:      --data-dir was provided but restore extracts to default location.\n` +
+                `             Update config.json or COORDINATOR_DATA_DIR if you need a non-default path.`);
+        }
+    });
+}

package/dist/cli/server/start.js

@@ -24,10 +24,33 @@ export function createServerStartCommand() {
             const isBun = typeof globalThis.Bun !== "undefined";
             const cmd = isBun ? process.execPath : process.execPath;
             const args = isBun ? ["server", "start"] : [process.argv[1], "server", "start"];
+            // Only forward the env vars the daemon actually needs.
+            // Each var is read explicitly (no Object.keys / dynamic indexing into
+            // process.env) so the daemon can't inherit unrelated parent-process
+            // secrets such as AWS_*, GITHUB_TOKEN, OPENAI_API_KEY, etc.
+            const childEnv = {
+                PATH: process.env.PATH ?? "",
+                HOME: process.env.HOME ?? process.env.USERPROFILE ?? "",
+                PORT: String(port),
+                COORDINATOR_DATA_DIR: dataDir,
+            };
+            const fwd = (key, value) => {
+                if (value !== undefined)
+                    childEnv[key] = value;
+            };
+            fwd("NODE_ENV", process.env.NODE_ENV);
+            fwd("LOG_LEVEL", process.env.LOG_LEVEL);
+            fwd("COORDINATOR_AUTH_ENABLED", process.env.COORDINATOR_AUTH_ENABLED);
+            fwd("COORDINATOR_JWT_SECRET", process.env.COORDINATOR_JWT_SECRET);
+            fwd("COORDINATOR_JWT_EXPIRY", process.env.COORDINATOR_JWT_EXPIRY);
+            fwd("COORDINATOR_REGISTRATION_SECRET", process.env.COORDINATOR_REGISTRATION_SECRET);
+            fwd("COORDINATOR_ADMIN_SECRET", process.env.COORDINATOR_ADMIN_SECRET);
+            fwd("COORDINATOR_MQTT_TCP_PORT", process.env.COORDINATOR_MQTT_TCP_PORT);
+            fwd("COORDINATOR_MQTT_WS_PATH", process.env.COORDINATOR_MQTT_WS_PATH);
             const child = spawn(cmd, args, {
                 detached: true,
                 stdio: ["ignore", logFd, logFd],
-                env: { ...process.env, PORT: String(port), COORDINATOR_DATA_DIR: dataDir },
+                env: childEnv,
             });
             // Write PID file
             writeFileSync(join(configDir, "server.pid"), String(child.pid));

package/dist/cli/server/status.js

@@ -1,12 +1,22 @@
 import { Command } from "commander";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
-import { execSync } from "child_process";
 import { getConfigDir, loadConfig } from "../config.js";
+async function fetchJson(url, init) {
+    try {
+        const response = await fetch(url, { ...init, signal: AbortSignal.timeout(3000) });
+        if (!response.ok)
+            return null;
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
 export function createServerStatusCommand() {
     return new Command("status")
         .description("Show coordinator status")
-        .action(() => {
+        .action(async () => {
         const configDir = getConfigDir();
         const pidPath = join(configDir, "server.pid");
         const config = loadConfig();
@@ -26,28 +36,11 @@ export function createServerStatusCommand() {
             console.log("Coordinator: stopped (stale PID file)");
             return;
         }
-        // Health check
-        let health = {};
-        try {
-            const raw = execSync(`curl -s --max-time 3 http://localhost:${port}/health`, {
-                encoding: "utf-8",
-                stdio: ["pipe", "pipe", "pipe"],
-            });
-            health = JSON.parse(raw);
-        }
-        catch { }
-        if (health.status === "ok") {
-            let status = {};
-            try {
-                const raw = execSync(`curl -s --max-time 3 -X POST http://localhost:${port}/api/status`, {
-                    encoding: "utf-8",
-                    stdio: ["pipe", "pipe", "pipe"],
-                });
-                status = JSON.parse(raw);
-            }
-            catch { }
+        const health = await fetchJson(`http://localhost:${port}/health`);
+        if (health?.status === "ok") {
+            const status = await fetchJson(`http://localhost:${port}/api/status`, { method: "POST" });
             console.log(`Coordinator: running (PID ${pid}, port ${port})`);
-            if (status.online !== undefined) {
+            if (status?.online !== undefined) {
                 console.log(`Agents:      ${status.online} online`);
                 console.log(`Threads:     ${status.open_threads} open`);
             }

package/dist/src/agent-activity.js

@@ -59,12 +59,12 @@ export class AgentActivityTracker {
     // ── Private ──
     upsert(agentId, status, file, thread) {
         const db = getDb();
-        db.prepare(`INSERT INTO agent_activity_status (agent_id, activity_status, current_file, current_thread, last_activity_at)
-       VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
-       ON CONFLICT(agent_id) DO UPDATE SET
-         activity_status = excluded.activity_status,
-         current_file = excluded.current_file,
-         current_thread = excluded.current_thread,
+        db.prepare(`INSERT INTO agent_activity_status (agent_id, activity_status, current_file, current_thread, last_activity_at)
+       VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+       ON CONFLICT(agent_id) DO UPDATE SET
+         activity_status = excluded.activity_status,
+         current_file = excluded.current_file,
+         current_thread = excluded.current_thread,
          last_activity_at = CURRENT_TIMESTAMP`).run(agentId, status, file, thread);
     }
 }

package/dist/src/agent-registry.js

@@ -2,12 +2,12 @@ import { getDb } from "./database.js";
 export class AgentRegistry {
     register(agentId, name, modules) {
         const db = getDb();
-        db.prepare(`INSERT INTO agents (id, name, modules, status, registered_at, last_seen_at)
-       VALUES (?, ?, ?, 'online', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
-       ON CONFLICT(id) DO UPDATE SET
-         name = excluded.name,
-         modules = excluded.modules,
-         status = 'online',
+        db.prepare(`INSERT INTO agents (id, name, modules, status, registered_at, last_seen_at)
+       VALUES (?, ?, ?, 'online', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+       ON CONFLICT(id) DO UPDATE SET
+         name = excluded.name,
+         modules = excluded.modules,
+         status = 'online',
          last_seen_at = CURRENT_TIMESTAMP`).run(agentId, name, JSON.stringify(modules));
         return this.get(agentId);
     }

package/dist/src/announce-workflow.d.ts

@@ -0,0 +1,52 @@
+import type { Thread } from "./types.js";
+import type { CoordinatorServices } from "./server-setup.js";
+import type { CategorizedImpact } from "./impact-scorer.js";
+import { type PlanQualityResult } from "./plan-quality.js";
+/**
+ * S2 fix: shared `announce_work` orchestration.
+ *
+ * The MCP tool handler (`server-setup.ts`) and the REST endpoint
+ * (`serve-http.ts`) historically duplicated ~95 lines of code that
+ * scored impact, overrode respondents, auto-resolved when alone,
+ * and emitted impact/introspection/plan-quality SSE events.
+ *
+ * This module extracts that common orchestration. Both transports
+ * call `runCommonAnnounceFlow()` after creating the thread; each
+ * transport then adds its own pre-step (MCP: conflict detection)
+ * and post-step (MCP: MQTT publish + context gathering, REST: JSON
+ * response) so existing SSE/response contracts are preserved.
+ *
+ * Why not unify the response/SSE shapes too? The MCP and REST
+ * `thread_opened` event payloads have DIFFERENT field sets today
+ * (e.g. MCP uses `initiator`, REST uses `agent_id` + `agent_name`).
+ * essaim (and other consumers) may depend on those exact shapes.
+ * Behavioral unification is a separate, riskier change deferred to
+ * a later major.
+ */
+export interface CommonFlowResult {
+    /** The same thread you passed in, refreshed after the override+auto-resolve. */
+    updated: Thread;
+    /** Impact scoring across all online agents. */
+    categorized: CategorizedImpact;
+    /** Concerned agent IDs (== updated.expected_respondents). */
+    respondents: string[];
+    /** Plan quality assessment (callers may emit downgrade event). */
+    planQuality: PlanQualityResult;
+}
+export interface CommonFlowParams {
+    agent_id: string;
+    subject: string;
+    plan?: string;
+    target_modules: string[];
+    target_files: string[];
+    depends_on_files?: string[];
+    exports_affected?: string[];
+    keep_open?: boolean;
+}
+/**
+ * Run the common post-`announceWork` orchestration. Mutates the thread row
+ * (overrides `expected_respondents`, may transition to `resolved`) and emits
+ * SSE events for impact scoring + introspection. Pure side-effects on the
+ * services + DB; returns metadata callers use to build their own responses.
+ */
+export declare function runCommonAnnounceFlow(services: CoordinatorServices, threadId: string, params: CommonFlowParams): CommonFlowResult;

package/dist/src/announce-workflow.js

@@ -0,0 +1,91 @@
+import { getDb } from "./database.js";
+import { assessPlanQuality } from "./plan-quality.js";
+/**
+ * Run the common post-`announceWork` orchestration. Mutates the thread row
+ * (overrides `expected_respondents`, may transition to `resolved`) and emits
+ * SSE events for impact scoring + introspection. Pure side-effects on the
+ * services + DB; returns metadata callers use to build their own responses.
+ */
+export function runCommonAnnounceFlow(services, threadId, params) {
+    const { registry, consultation, impactScorer, introspection, sseEmitter } = services;
+    // 1. Score impact: categorize all online agents into concerned / gray_zone / pass.
+    const categorized = impactScorer.categorize({
+        agent_id: params.agent_id,
+        target_modules: params.target_modules,
+        target_files: params.target_files,
+        depends_on_files: params.depends_on_files,
+        exports_affected: params.exports_affected,
+    });
+    // 2. Override expected_respondents on the thread with the scored set.
+    // Auto-resolve only when truly alone — if peers are online but not concerned
+    // (e.g., they haven't announced yet), keep the thread open so a subsequent
+    // announce can match via Layer 0. Thread will timeout naturally if no one joins.
+    const db = getDb();
+    const concernedIds = categorized.concerned.map((s) => s.agent_id);
+    db.prepare("UPDATE threads SET expected_respondents = ? WHERE id = ?")
+        .run(JSON.stringify(concernedIds), threadId);
+    const otherOnlineCount = registry.listOnline().filter((a) => a.id !== params.agent_id).length;
+    const shouldAutoResolve = concernedIds.length === 0 && otherOnlineCount === 0;
+    const currentThread = consultation.getThread(threadId);
+    if (shouldAutoResolve && currentThread.status === "open" && !params.keep_open) {
+        db.prepare("UPDATE threads SET status = 'resolved', resolved_at = ? WHERE id = ?")
+            .run(new Date().toISOString(), threadId);
+        consultation.emitResolution(threadId, "auto_resolved");
+    }
+    // 3. Emit impact_scored SSE events for every scored agent.
+    for (const s of [...categorized.concerned, ...categorized.gray_zone, ...categorized.pass]) {
+        sseEmitter.emit("impact_scored", {
+            thread_id: threadId,
+            agent_id: s.agent_id,
+            agent_name: s.agent_name,
+            score: s.score,
+            reasons: s.reasons,
+            category: scoredCategory(s),
+        });
+    }
+    // 4. Create introspection records and emit introspection_requested for gray_zone agents.
+    for (const s of categorized.gray_zone) {
+        introspection.create({ thread_id: threadId, agent_id: s.agent_id, score: s.score, reasons: s.reasons });
+        sseEmitter.emit("introspection_requested", {
+            thread_id: threadId,
+            agent_id: s.agent_id,
+            agent_name: s.agent_name,
+            score: s.score,
+            reasons: s.reasons,
+        });
+    }
+    // 5. Plan quality downgrade event — both transports emit this when a plan
+    // was provided but quality was insufficient. Callers can re-emit if their
+    // payload shape differs (MCP vs REST agent_name source).
+    const planQuality = assessPlanQuality(params.plan);
+    if (params.plan && planQuality.mode === "discovery") {
+        sseEmitter.emit("impact_scored", {
+            thread_id: threadId,
+            agent_id: params.agent_id,
+            agent_name: registry.get(params.agent_id)?.name || params.agent_id,
+            score: planQuality.score,
+            reasons: [planDowngradeReason(planQuality)],
+            category: "plan_quality",
+        });
+    }
+    const updated = consultation.getThread(threadId);
+    const respondents = JSON.parse(updated.expected_respondents || "[]");
+    return { updated, categorized, respondents, planQuality };
+}
+function scoredCategory(s) {
+    if (s.score >= 90)
+        return "concerned";
+    if (s.score >= 30)
+        return "gray_zone";
+    return "pass";
+}
+function planDowngradeReason(pq) {
+    const flags = [];
+    if (!pq.checks.mentions_files)
+        flags.push("no files");
+    if (!pq.checks.concrete_approach)
+        flags.push("vague approach");
+    if (!pq.checks.sufficient_detail)
+        flags.push("too short");
+    return `plan downgraded: score ${pq.score}/3 — ${flags.join(" ")}`.trim();
+}

package/dist/src/consultation.d.ts

@@ -13,8 +13,22 @@ export interface ResolutionEvent {
 export declare class Consultation {
     private onResolveCallback;
     private log;
+    private timeoutSweeperHandle;
     constructor(logger?: Logger);
     onResolve(callback: (event: ResolutionEvent) => void): void;
+    /**
+     * 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?: number): void;
+    stopTimeoutSweeper(): void;
     emitResolution(threadId: string, type: ResolutionType, approvedBy?: string, approvedByName?: string): void;
     announceWork(params: {
         agent_id: string;
@@ -60,6 +74,14 @@ export declare class Consultation {
          * parsing the thread list themselves.
          */
         assigned_to_me?: string;
+        /**
+         * P2 perf: bound resolved-thread queries to a recency window. Without
+         * this, the impact scorer would scan all-time resolved threads on every
+         * announce_work call (O(historical-threads) per scoring pass). The window
+         * applies to resolved_at when status='resolved', otherwise to created_at,
+         * so the filter is meaningful for both states.
+         */
+        since_minutes?: number;
     }): Thread[];
     getThreadUpdates(agentId: string, since?: string): ThreadMessage[];
     logActionSummary(params: {