@vibecodetown/mcp-server 1.3.1

package/build/mcp/events/event_loop.js

@@ -0,0 +1,248 @@
+import * as path from "node:path";
+import crypto from "node:crypto";
+import { startFileWatcher } from "./file_watcher.js";
+import { processEvent } from "./processor.js";
+import { DEFAULT_EVENT_COOLDOWN_MS, DEFAULT_EVENT_DEDUP_BUCKET_MS, DEFAULT_EVENT_MAX_RETRY, DEFAULT_EVENT_RETRY_BACKOFF_MS, DEFAULT_MQ_RETRY_MS, ENV_FLAGS, envFlag, envInt, envStr, } from "./constants.js";
+import { toPosixPath, resolveRelativePosix } from "../path-utils.js";
+import { getVibeDir, getPmRunsDir, getEngineRunsDir, getLegacyRunsDir } from "../paths.js";
+import { appendEventLog } from "./logger.js";
+import { DedupCooldown } from "./dedup_cooldown.js";
+import { refreshNavAndState } from "./nav_refresh.js";
+import { createMQ } from "./mq.js";
+import { createNatsClient } from "./mq_nats.js";
+import { createRedisClient } from "./mq_redis.js";
+const SELF_COMPONENT = "kernel";
+function randomId() {
+    return crypto.randomUUID();
+}
+export function classifyEventType(filePath) {
+    const p = toPosixPath(filePath.toLowerCase());
+    const segments = p.split("/").filter(Boolean);
+    const filename = segments[segments.length - 1] ?? "";
+    const has = (seg) => segments.includes(seg);
+    if (has("results"))
+        return { type: "artifact.result_written", reason: "file_change" };
+    if (has("mapping"))
+        return { type: "artifact.mapping_written", reason: "file_change" };
+    if (has("airlock") && filename === "redaction_report.json") {
+        return { type: "artifact.airlock_report_written", reason: "file_change" };
+    }
+    if (has("airlock") && filename === "safe_context.txt") {
+        return { type: "artifact.airlock_safe_context_written", reason: "file_change" };
+    }
+    if (has("airlock") && filename === "input_fingerprint.json") {
+        return { type: "artifact.airlock_fingerprint_written", reason: "file_change" };
+    }
+    if (has("chunks") && filename === "chunk_manifest.v1.json") {
+        return { type: "artifact.chunk_manifest_written", reason: "file_change" };
+    }
+    if (has("chunks") && filename === "chunk_summary.md") {
+        return { type: "artifact.chunk_summary_written", reason: "file_change" };
+    }
+    if (has("chunks") && filename.startsWith("chk_") && filename.endsWith(".json")) {
+        return { type: "artifact.chunk_written", reason: "file_change" };
+    }
+    if (has("handoff") && (filename.includes("work_order") || filename.includes("clinic_bridge"))) {
+        return { type: "artifact.work_order_updated", reason: "file_change" };
+    }
+    if (has("intent"))
+        return { type: "artifact.intent_generated", reason: "file_change" };
+    if (has("spec") || has("05_spec") || filename === "atomic_specs.json") {
+        return { type: "artifact.spec_generated", reason: "file_change" };
+    }
+    if (has("plan") || has("10_plan") || filename === "plan.json") {
+        return { type: "artifact.plan_updated", reason: "file_change" };
+    }
+    if (filename.includes("work_order"))
+        return { type: "artifact.work_order_updated", reason: "file_change" };
+    return { type: "artifact.file_changed", reason: "file_change" };
+}
+export function detectRunId(workspaceRoot, filePath) {
+    const segments = toPosixPath(path.resolve(filePath)).split("/");
+    const root = toPosixPath(path.resolve(workspaceRoot));
+    const rel = toPosixPath(path.relative(root, path.resolve(filePath)));
+    // .vibe/runs/<run_id>
+    const vibeIdx = rel.split("/").indexOf(".vibe");
+    if (vibeIdx >= 0) {
+        const parts = rel.split("/");
+        const runIdx = parts.indexOf("runs");
+        if (runIdx >= 0 && parts[runIdx + 1])
+            return parts[runIdx + 1];
+    }
+    // engines/spec_high/runs/<run_id>
+    if (rel.includes("engines/spec_high/runs")) {
+        const parts = rel.split("/");
+        const runIdx = parts.indexOf("runs");
+        if (runIdx >= 0 && parts[runIdx + 1])
+            return parts[runIdx + 1];
+    }
+    // legacy runs/<run_id>
+    const parts = rel.split("/");
+    const runIdx = parts.indexOf("runs");
+    if (runIdx >= 0 && parts[runIdx + 1])
+        return parts[runIdx + 1];
+    return "unknown";
+}
+function buildEventRecord(workspaceRoot, filePath) {
+    const { type, reason } = classifyEventType(filePath);
+    const runId = detectRunId(workspaceRoot, filePath);
+    const rel = resolveRelativePosix(workspaceRoot, path.resolve(filePath));
+    return {
+        schema_version: "event.v1",
+        event_id: randomId(),
+        ts: new Date().toISOString(),
+        run_id: runId,
+        type,
+        reason,
+        source: { actor: "system", component: SELF_COMPONENT, host: path.basename(workspaceRoot) },
+        refs: { paths: [rel] },
+        dedup: { bucket_ms: envInt(ENV_FLAGS.EVENT_DEDUP_BUCKET_MS, DEFAULT_EVENT_DEDUP_BUCKET_MS) },
+        note: `file=${rel}`,
+    };
+}
+function getLogPath(workspaceRoot, runId) {
+    if (runId && runId !== "unknown") {
+        return path.join(getVibeDir(workspaceRoot), "runs", runId, "events.jsonl");
+    }
+    return path.join(getVibeDir(workspaceRoot), "logs", "events.global.jsonl");
+}
+export function startEventLoop(workspaceRoot) {
+    const enableWatcher = envFlag(ENV_FLAGS.ENABLE_FILE_WATCHER) ||
+        process.env[ENV_FLAGS.ENABLE_FILE_WATCHER] === undefined; // default ON
+    const enableEventBus = envFlag(ENV_FLAGS.ENABLE_EVENT_BUS);
+    const enableGlobalEvents = envFlag(ENV_FLAGS.ENABLE_GLOBAL_EVENTS);
+    const mqProvider = (process.env[ENV_FLAGS.MQ_PROVIDER] ?? "none").toLowerCase();
+    const mqUrl = envStr(ENV_FLAGS.MQ_URL, "");
+    let mqClient = null;
+    let mqRetryTimer = null;
+    // Initialize optional MQ
+    if (enableEventBus && mqProvider !== "none") {
+        const retryMs = envInt(ENV_FLAGS.MQ_RETRY_MS, DEFAULT_MQ_RETRY_MS);
+        const initMq = async () => {
+            try {
+                if (mqProvider === "nats") {
+                    mqClient = await createNatsClient({ servers: mqUrl || "nats://127.0.0.1:4222" });
+                }
+                else if (mqProvider === "redis") {
+                    mqClient = await createRedisClient(mqUrl || "redis://127.0.0.1:6379");
+                }
+                else {
+                    mqClient = createMQ("none");
+                }
+                if (!mqClient) {
+                    throw new Error("MQ client unavailable");
+                }
+            }
+            catch (e) {
+                console.error(`[event_loop] MQ init failed: ${e instanceof Error ? e.message : String(e)}`);
+                if (!mqRetryTimer) {
+                    mqRetryTimer = setTimeout(() => {
+                        mqRetryTimer = null;
+                        void initMq();
+                    }, retryMs);
+                }
+            }
+        };
+        void initMq();
+    }
+    if (!enableWatcher) {
+        return {
+            async stop() { },
+            status() {
+                return { watching: false, paths: [] };
+            },
+        };
+    }
+    const paths = [getPmRunsDir(workspaceRoot), getEngineRunsDir(workspaceRoot), getLegacyRunsDir(workspaceRoot)];
+    const dedup = new DedupCooldown(envInt(ENV_FLAGS.EVENT_DEDUP_BUCKET_MS, DEFAULT_EVENT_DEDUP_BUCKET_MS), envInt(ENV_FLAGS.EVENT_COOLDOWN_MS, DEFAULT_EVENT_COOLDOWN_MS));
+    const watcher = startFileWatcher(paths, {
+        cwd: workspaceRoot,
+        ignore: (fullPath) => {
+            const p = toPosixPath(fullPath);
+            // ignore self-written/control files
+            if (p.includes("/run_state.v1.json"))
+                return true;
+            if (p.endsWith("/events.jsonl"))
+                return true;
+            if (p.includes("/observer/heartbeat.json"))
+                return true;
+            if (p.endsWith("/nav.json"))
+                return true;
+            return false;
+        },
+        onEvent: (type, changedPath) => {
+            if (type === "unlink")
+                return; // ignore deletes for now
+            const ev = buildEventRecord(workspaceRoot, changedPath);
+            if (ev.run_id === "unknown" && !enableGlobalEvents) {
+                return;
+            }
+            const logPath = getLogPath(workspaceRoot, ev.run_id);
+            // Self paths: run_state/nav writes by kernel should not re-trigger
+            const selfPaths = new Set([
+                resolveRelativePosix(workspaceRoot, path.join(getVibeDir(workspaceRoot), "runs", ev.run_id, "run_state.v1.json")),
+                resolveRelativePosix(workspaceRoot, path.join(getVibeDir(workspaceRoot), "runs", ev.run_id, "nav.json")),
+            ]);
+            processEvent(ev, {
+                logPath,
+                dedup,
+                selfComponent: SELF_COMPONENT,
+                selfPaths,
+                workspaceRoot,
+                allowUnknownRun: ev.run_id === "unknown" && enableGlobalEvents,
+                maxRetry: envInt(ENV_FLAGS.EVENT_MAX_RETRY, DEFAULT_EVENT_MAX_RETRY),
+                retryBackoffMs: envInt(ENV_FLAGS.EVENT_RETRY_BACKOFF_MS, DEFAULT_EVENT_RETRY_BACKOFF_MS),
+                onHandle: async () => {
+                    if (ev.run_id === "unknown")
+                        return;
+                    const res = await refreshNavAndState(workspaceRoot, ev.run_id);
+                    const navSignal = {
+                        schema_version: "event.v1",
+                        event_id: randomId(),
+                        ts: new Date().toISOString(),
+                        run_id: ev.run_id,
+                        type: "signal.nav_updated",
+                        reason: "nav_refreshed",
+                        source: { actor: "system", component: SELF_COMPONENT },
+                        refs: { paths: [res.run_state_path, res.nav_path] },
+                        note: `actions=${res.actions_count}`,
+                    };
+                    appendEventLog(getLogPath(workspaceRoot, ev.run_id), {
+                        status: "handled",
+                        event: navSignal,
+                        ts: new Date().toISOString(),
+                        message: "nav refreshed",
+                    });
+                    if (mqClient) {
+                        await mqClient.publish(navSignal);
+                    }
+                },
+            }).catch((err) => {
+                appendEventLog(logPath, {
+                    status: "failed_parse",
+                    event: ev,
+                    ts: new Date().toISOString(),
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            });
+            // Publish original event to MQ (bell-only, optional)
+            if (mqClient) {
+                mqClient.publish(ev).catch(() => { });
+            }
+        },
+    });
+    return {
+        async stop() {
+            await watcher.close();
+            if (mqRetryTimer) {
+                clearTimeout(mqRetryTimer);
+                mqRetryTimer = null;
+            }
+            if (mqClient)
+                await mqClient.close();
+        },
+        status() {
+            return { watching: true, paths: paths.map((p) => path.resolve(p)) };
+        },
+    };
+}

package/build/mcp/events/file_watcher.d.ts

@@ -0,0 +1,8 @@
+export type FileEventType = "add" | "change" | "unlink";
+export interface FileWatcherOptions {
+    cwd?: string;
+    ignore?: (path: string) => boolean;
+    onEvent: (type: FileEventType, path: string) => void;
+    persistent?: boolean;
+}
+export declare function startFileWatcher(paths: string[], opts: FileWatcherOptions): import("chokidar").FSWatcher;

package/build/mcp/events/file_watcher.js

@@ -0,0 +1,24 @@
+import chokidar from "chokidar";
+import { resolve } from "node:path";
+export function startFileWatcher(paths, opts) {
+    const watcher = chokidar.watch(paths, {
+        cwd: opts.cwd ?? process.cwd(),
+        persistent: opts.persistent ?? true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: 150,
+            pollInterval: 50,
+        },
+    });
+    watcher
+        .on("add", (p) => emit("add", p))
+        .on("change", (p) => emit("change", p))
+        .on("unlink", (p) => emit("unlink", p));
+    function emit(type, p) {
+        const full = resolve(opts.cwd ?? process.cwd(), p);
+        if (opts.ignore?.(full))
+            return;
+        opts.onEvent(type, full);
+    }
+    return watcher;
+}

package/build/mcp/events/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./dedup_cooldown.js";
+export * from "./logger.js";
+export * from "./processor.js";
+export * from "./file_watcher.js";
+export * from "./event_loop.js";
+export * from "./nav_refresh.js";
+export * from "./mq.js";
+export * from "./emitter.js";
+export * from "./replay.js";

package/build/mcp/events/index.js

@@ -0,0 +1,11 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./dedup_cooldown.js";
+export * from "./logger.js";
+export * from "./processor.js";
+export * from "./file_watcher.js";
+export * from "./event_loop.js";
+export * from "./nav_refresh.js";
+export * from "./mq.js";
+export * from "./emitter.js";
+export * from "./replay.js";

package/build/mcp/events/logger.d.ts

@@ -0,0 +1,8 @@
+import type { EventRecord, EventStatus } from "./types.js";
+export interface EventLogEntry {
+    status: EventStatus;
+    event: EventRecord;
+    message?: string;
+    ts: string;
+}
+export declare function appendEventLog(logPath: string, entry: EventLogEntry): void;

package/build/mcp/events/logger.js

@@ -0,0 +1,38 @@
+import { appendFileSync, mkdirSync, renameSync, readdirSync, statSync, unlinkSync, existsSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+import { DEFAULT_EVENTS_GLOBAL_MAX_BYTES, DEFAULT_EVENTS_GLOBAL_MAX_FILES, ENV_FLAGS, envInt, } from "./constants.js";
+function rotateGlobalLogIfNeeded(logPath) {
+    if (basename(logPath) !== "events.global.jsonl")
+        return;
+    if (!existsSync(logPath))
+        return;
+    const maxBytes = envInt(ENV_FLAGS.EVENTS_GLOBAL_MAX_BYTES, DEFAULT_EVENTS_GLOBAL_MAX_BYTES);
+    const maxFiles = envInt(ENV_FLAGS.EVENTS_GLOBAL_MAX_FILES, DEFAULT_EVENTS_GLOBAL_MAX_FILES);
+    try {
+        const { size } = statSync(logPath);
+        if (size < maxBytes)
+            return;
+        const dir = dirname(logPath);
+        const stamp = new Date().toISOString().replace(/[:.]/g, "");
+        const rotated = join(dir, `events.global.${stamp}.jsonl`);
+        renameSync(logPath, rotated);
+        if (maxFiles <= 0)
+            return;
+        const files = readdirSync(dir)
+            .filter((f) => f.startsWith("events.global.") && f.endsWith(".jsonl"))
+            .map((f) => ({ name: f, mtime: statSync(join(dir, f)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime);
+        for (let i = maxFiles; i < files.length; i++) {
+            unlinkSync(join(dir, files[i].name));
+        }
+    }
+    catch {
+        // best-effort rotation
+    }
+}
+export function appendEventLog(logPath, entry) {
+    mkdirSync(dirname(logPath), { recursive: true });
+    rotateGlobalLogIfNeeded(logPath);
+    const line = JSON.stringify(entry);
+    appendFileSync(logPath, `${line}\n`, { encoding: "utf-8" });
+}

package/build/mcp/events/mq.d.ts

@@ -0,0 +1,10 @@
+import type { EventRecord } from "./types.js";
+export type MQProvider = "none" | "nats" | "redis";
+export interface MQClient {
+    publish(event: EventRecord): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Stub factory for MQ client (optional). Real MQ to be wired later.
+ */
+export declare function createMQ(provider: MQProvider): MQClient;

package/build/mcp/events/mq.js

@@ -0,0 +1,22 @@
+class NoopMQ {
+    async publish(_event) {
+        return;
+    }
+    async close() {
+        return;
+    }
+}
+/**
+ * Stub factory for MQ client (optional). Real MQ to be wired later.
+ */
+export function createMQ(provider) {
+    switch (provider) {
+        case "nats":
+        case "redis":
+            // TODO: implement real providers
+            return new NoopMQ();
+        case "none":
+        default:
+            return new NoopMQ();
+    }
+}

package/build/mcp/events/mq_nats.d.ts

@@ -0,0 +1,5 @@
+import type { EventRecord } from "./types.js";
+export declare function createNatsClient(_opts: Record<string, unknown>): Promise<{
+    publish: (ev: EventRecord) => Promise<void>;
+    close: () => Promise<void>;
+} | null>;

package/build/mcp/events/mq_nats.js

@@ -0,0 +1,20 @@
+export async function createNatsClient(_opts) {
+    try {
+        const nats = await import("nats");
+        const sc = nats.StringCodec();
+        const conn = await nats.connect(_opts);
+        const subject = _opts.name ?? "vibe.events";
+        return {
+            async publish(ev) {
+                conn.publish(subject, sc.encode(JSON.stringify(ev)));
+            },
+            async close() {
+                await conn.close();
+            },
+        };
+    }
+    catch (e) {
+        console.error(`[mq_nats] NATS client unavailable: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}

package/build/mcp/events/mq_redis.d.ts

@@ -0,0 +1,5 @@
+import type { EventRecord } from "./types.js";
+export declare function createRedisClient(url?: string): Promise<{
+    publish: (ev: EventRecord) => Promise<void>;
+    close: () => Promise<void>;
+} | null>;

package/build/mcp/events/mq_redis.js

@@ -0,0 +1,20 @@
+export async function createRedisClient(url) {
+    try {
+        const { createClient } = await import("redis");
+        const client = createClient({ url });
+        await client.connect();
+        const channel = "vibe.events";
+        return {
+            async publish(ev) {
+                await client.publish(channel, JSON.stringify(ev));
+            },
+            async close() {
+                await client.disconnect();
+            }
+        };
+    }
+    catch (e) {
+        console.error(`[mq_redis] Redis client unavailable: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}

package/build/mcp/events/nav_refresh.d.ts

@@ -0,0 +1,14 @@
+export interface NavRefreshResult {
+    nav_path: string;
+    run_state_path: string;
+    actions_count: number;
+    phase: string;
+}
+/**
+ * Minimal nav/run_state refresh for event loop.
+ * - Reads facts + scorecard (best-effort)
+ * - Derives phase from run_state if present else falls back to "INTAKE"
+ * - Writes nav.json with next_actions and summary
+ * - Ensures run_state.v1.json exists (creates minimal shell if missing)
+ */
+export declare function refreshNavAndState(workspaceRoot: string, runId: string): Promise<NavRefreshResult>;

package/build/mcp/events/nav_refresh.js

@@ -0,0 +1,64 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { collectFacts } from "../tools/vibe_pm/facts/index.js";
+import { readScorecard } from "../tools/vibe_pm/scorecard/index.js";
+import { resolveNextActions } from "../tools/vibe_pm/navigation/index.js";
+import { getPmRunDir, getVibeDir } from "../paths.js";
+import { resolveRelativePosix } from "../path-utils.js";
+/**
+ * Minimal nav/run_state refresh for event loop.
+ * - Reads facts + scorecard (best-effort)
+ * - Derives phase from run_state if present else falls back to "INTAKE"
+ * - Writes nav.json with next_actions and summary
+ * - Ensures run_state.v1.json exists (creates minimal shell if missing)
+ */
+export async function refreshNavAndState(workspaceRoot, runId) {
+    const runDir = getPmRunDir(workspaceRoot, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const runStatePath = path.join(getVibeDir(workspaceRoot), "runs", runId, "run_state.v1.json");
+    const navPath = path.join(getVibeDir(workspaceRoot), "runs", runId, "nav.json");
+    fs.mkdirSync(path.dirname(runStatePath), { recursive: true });
+    // Load existing run_state to derive phase if available
+    let phase = "INTAKE";
+    try {
+        if (fs.existsSync(runStatePath)) {
+            const raw = JSON.parse(fs.readFileSync(runStatePath, "utf-8"));
+            if (typeof raw?.phase === "string")
+                phase = raw.phase;
+        }
+    }
+    catch {
+        // ignore
+    }
+    const facts = await collectFacts(workspaceRoot, runId, { skipScout: true });
+    const scorecard = await readScorecard(workspaceRoot, runId);
+    const actions = resolveNextActions(facts, scorecard, phase, false);
+    const navData = {
+        schema_version: "nav.v1",
+        run_id: runId,
+        phase,
+        generated_at: new Date().toISOString(),
+        actions,
+        facts_summary: facts.sources,
+    };
+    fs.writeFileSync(navPath, JSON.stringify(navData, null, 2));
+    // Ensure run_state exists minimally
+    if (!fs.existsSync(runStatePath)) {
+        const runState = {
+            schema_version: "run_state.v1",
+            run_id: runId,
+            phase,
+            mode: "balanced",
+            created_at: new Date().toISOString(),
+            decisions_made: facts.ask_queue_count ? 0 : 0,
+            decisions_pending: facts.ask_queue_count ?? 0,
+        };
+        fs.writeFileSync(runStatePath, JSON.stringify(runState, null, 2));
+    }
+    return {
+        nav_path: resolveRelativePosix(workspaceRoot, navPath),
+        run_state_path: resolveRelativePosix(workspaceRoot, runStatePath),
+        actions_count: actions.length,
+        phase,
+    };
+}

package/build/mcp/events/processor.d.ts

@@ -0,0 +1,19 @@
+import { DedupCooldown } from "./dedup_cooldown.js";
+import type { EventRecord, EventStatus } from "./types.js";
+export interface ProcessEventOpts {
+    logPath: string;
+    dedup?: DedupCooldown;
+    cooldownMs?: number;
+    dedupBucketMs?: number;
+    maxRetry?: number;
+    retryBackoffMs?: number;
+    selfComponent?: string;
+    selfPaths?: Set<string>;
+    onHandle?: (ev: EventRecord) => Promise<void> | void;
+    workspaceRoot?: string;
+    allowUnknownRun?: boolean;
+}
+/**
+ * Process a single event with dedup, cooldown, self-trigger guard, read-after-write.
+ */
+export declare function processEvent(ev: EventRecord, opts: ProcessEventOpts): Promise<EventStatus>;

package/build/mcp/events/processor.js

@@ -0,0 +1,76 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { DedupCooldown } from "./dedup_cooldown.js";
+import { DEFAULT_EVENT_COOLDOWN_MS, DEFAULT_EVENT_DEDUP_BUCKET_MS, DEFAULT_EVENT_MAX_RETRY, DEFAULT_EVENT_RETRY_BACKOFF_MS, } from "./constants.js";
+import { appendEventLog } from "./logger.js";
+/**
+ * Process a single event with dedup, cooldown, self-trigger guard, read-after-write.
+ */
+export async function processEvent(ev, opts) {
+    const now = Date.now();
+    const dedup = opts.dedup ?? new DedupCooldown(opts.dedupBucketMs ?? DEFAULT_EVENT_DEDUP_BUCKET_MS, opts.cooldownMs ?? DEFAULT_EVENT_COOLDOWN_MS);
+    const logPath = opts.logPath;
+    // basic schema checks
+    const firstPath = ev.refs?.paths?.[0];
+    if (!firstPath) {
+        appendEventLog(logPath, { status: "failed_schema", event: ev, ts: new Date().toISOString(), message: "refs.paths empty" });
+        return "failed_schema";
+    }
+    if (!ev.run_id || ev.run_id === "unknown") {
+        if (!opts.allowUnknownRun) {
+            appendEventLog(logPath, { status: "failed_schema", event: ev, ts: new Date().toISOString(), message: "run_id unknown" });
+            return "failed_schema";
+        }
+    }
+    // dedup / cooldown
+    const skip = dedup.shouldSkip(ev, now);
+    if (skip === "dedup") {
+        appendEventLog(logPath, { status: "skipped_dedup", event: ev, ts: new Date().toISOString(), message: "duplicate" });
+        return "skipped_dedup";
+    }
+    if (skip === "cooldown") {
+        appendEventLog(logPath, { status: "skipped_cooldown", event: ev, ts: new Date().toISOString(), message: "cooldown" });
+        return "skipped_cooldown";
+    }
+    // self-trigger guard
+    if (opts.selfComponent && ev.source.component === opts.selfComponent) {
+        if (opts.selfPaths?.has(firstPath)) {
+            appendEventLog(logPath, { status: "skipped_self_trigger", event: ev, ts: new Date().toISOString(), message: "self-trigger" });
+            return "skipped_self_trigger";
+        }
+    }
+    // read-after-write
+    const statPath = path.isAbsolute(firstPath)
+        ? firstPath
+        : opts.workspaceRoot
+            ? path.resolve(opts.workspaceRoot, firstPath)
+            : path.resolve(firstPath);
+    const maxRetry = opts.maxRetry ?? DEFAULT_EVENT_MAX_RETRY;
+    const backoffMs = opts.retryBackoffMs ?? DEFAULT_EVENT_RETRY_BACKOFF_MS;
+    let ok = true;
+    for (let i = 0; i <= maxRetry; i++) {
+        try {
+            await stat(statPath);
+            ok = true;
+            break;
+        }
+        catch (err) {
+            ok = false;
+            if (i === maxRetry)
+                break;
+            await delay(backoffMs * Math.pow(2, i));
+        }
+    }
+    if (!ok) {
+        appendEventLog(logPath, { status: "failed_read_after_write", event: ev, ts: new Date().toISOString(), message: "refs.paths missing after retries" });
+        return "failed_read_after_write";
+    }
+    // handle
+    if (opts.onHandle) {
+        await opts.onHandle(ev);
+    }
+    dedup.markProcessed(ev, now);
+    appendEventLog(logPath, { status: "handled", event: ev, ts: new Date().toISOString() });
+    return "handled";
+}

package/build/mcp/events/replay.d.ts

@@ -0,0 +1,6 @@
+import type { EventRecord } from "./types.js";
+/**
+ * Read events from events.jsonl (best-effort).
+ * Skips malformed/partial lines.
+ */
+export declare function readEventLogEvents(logPath: string): EventRecord[];

package/build/mcp/events/replay.js

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+/**
+ * Read events from events.jsonl (best-effort).
+ * Skips malformed/partial lines.
+ */
+export function readEventLogEvents(logPath) {
+    if (!fs.existsSync(logPath))
+        return [];
+    const raw = fs.readFileSync(logPath, "utf-8");
+    const lines = raw.split(/\n+/);
+    const events = [];
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const ev = parsed?.event ?? parsed;
+            if (ev?.schema_version === "event.v1" && Array.isArray(ev?.refs?.paths)) {
+                events.push(ev);
+            }
+        }
+        catch {
+            // ignore malformed line
+        }
+    }
+    return events;
+}