relaybrain 0.0.0-stage → 0.2.1

package/backend/lib/deps.js

@@ -0,0 +1,46 @@
+const fs = require("fs");
+const path = require("path");
+
+const IMPORT_RE =
+  /(?:import\s+(?:[\s\S]*?)\s+from\s+|require\s*\(|from\s+)['"]([^'"]+)['"]/g;
+
+function normalizeRel(fromFile, spec) {
+  if (!spec.startsWith(".")) return null;
+  const dir = path.posix.dirname(fromFile.replace(/\\/g, "/"));
+  let resolved = path.posix.normalize(path.posix.join(dir, spec)).replace(/^\.\//, "");
+  return resolved.replace(/\\/g, "/");
+}
+
+function parseImports(source, fromFile) {
+  const out = [];
+  let m;
+  const re = new RegExp(IMPORT_RE);
+  while ((m = re.exec(source))) {
+    const rel = normalizeRel(fromFile, m[1]);
+    if (rel) out.push(rel);
+  }
+  return out;
+}
+
+function resolveExisting(workspacePath, rel) {
+  const bases = [rel, `${rel}.ts`, `${rel}.tsx`, `${rel}.js`, `${rel}.jsx`, path.posix.join(rel, "index.ts")];
+  for (const b of bases) {
+    const abs = path.join(workspacePath, b);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return b.replace(/\\/g, "/");
+  }
+  return rel;
+}
+
+function dependsOn(workspacePath, filePath) {
+  try {
+    const rel = filePath.replace(/\\/g, "/").replace(/^\.?\//, "");
+    const abs = path.join(workspacePath, rel);
+    if (!fs.existsSync(abs)) return [];
+    const src = fs.readFileSync(abs, "utf8");
+    return parseImports(src, rel).map((d) => resolveExisting(workspacePath, d));
+  } catch {
+    return [];
+  }
+}
+
+module.exports = { dependsOn, parseImports };

package/backend/lib/dirtyFiles.js

@@ -0,0 +1,33 @@
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const SKIP = /(^|\/)(\.git|\.relay|node_modules|\.next|dist|out)(\/|$)/i;
+
+function dirtyFiles(workspacePath) {
+  if (!workspacePath) return [];
+  let out = "";
+  try {
+    out = execFileSync("git", ["-C", workspacePath, "status", "--porcelain", "-uall"], {
+      encoding: "utf8",
+      timeout: 4000,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const line of out.split("\n")) {
+    if (!line.trim()) continue;
+    const raw = line.slice(3).replace(/.* -> /, "").trim().replace(/\\/g, "/");
+    if (!raw || SKIP.test(raw)) continue;
+    files.push(raw);
+  }
+  return [...new Set(files)];
+}
+
+function resolveRel(workspacePath, file) {
+  return path.join(workspacePath, file);
+}
+
+module.exports = { dirtyFiles, resolveRel };

package/backend/lib/editMatchers.js

@@ -0,0 +1,55 @@
+/**
+ * Single source of truth for write-tool hook matchers (PreToolUse + PostToolUse)
+ * and transcript edit detection. Keep pre/post identical per product or flush
+ * never runs after a successful claim.
+ *
+ * Sources (2025–2026):
+ * - Cursor hooks: preToolUse/postToolUse match tool_name (Write, Edit, Delete, …)
+ * - Claude Code hooks: PostToolUse matcher = tool name (Edit|Write|NotebookEdit, …)
+ * - Codex hooks: apply_patch|Edit|Write (+ runtime names in transcripts)
+ * - Copilot CLI: postToolUse matcher = toolName regex (edit|create|apply_patch)
+ * - Antigravity: PreToolUse/PostToolUse matcher on toolCall.name
+ */
+
+function matcherToSet(matcher) {
+  return new Set(
+    String(matcher || "")
+      .split("|")
+      .map((s) => s.trim())
+      .filter(Boolean)
+  );
+}
+
+const EDIT = {
+  // code.claude.com/docs/en/hooks — PostToolUse matcher on tool name
+  claude: "Edit|Write|NotebookEdit|MultiEdit|Replace",
+  // cursor.com/docs/hooks — postToolUse matcher on tool_name; StrReplace/ApplyPatch
+  // appear in agent transcripts but are under-documented in the matcher list.
+  cursor: "Write|Edit|Delete|StrReplace|ApplyPatch|EditNotebook|search_replace",
+  // Codex hook config + session transcript tool names
+  codex: "apply_patch|Edit|Write|write|edit_file|create_file|patch_file",
+  // docs.github.com/copilot/reference/hooks-reference — CLI toolName edit|create, plus the
+  // VS Code Copilot agent's names. replace_string_in_file is its most common edit, and
+  // "edit|create" alone never matched it.
+  copilot: "edit|create|apply_patch|create_file|replace_string_in_file|multi_replace_string_in_file|insert_edit_into_file|edit_file",
+  // Antigravity write tools (TargetFile on toolCall.args)
+  antigravity: "write_to_file|replace_file_content|multi_replace_file_content|edit_file|create_file",
+};
+
+const READ = {
+  claude: "Read|Grep|Glob",
+  cursor: "Read|Grep",
+  codex: null,
+  copilot: "view|grep|glob",
+  antigravity: "view_file|grep_search|list_dir|find_by_name",
+};
+
+const EDIT_TOOL_SETS = {
+  cursor: matcherToSet(EDIT.cursor),
+  claude: matcherToSet(EDIT.claude),
+  codex: matcherToSet(EDIT.codex),
+  copilot: matcherToSet(EDIT.copilot),
+  antigravity: matcherToSet(EDIT.antigravity),
+};
+
+module.exports = { EDIT, READ, EDIT_TOOL_SETS, matcherToSet };

package/backend/lib/falkor/analytics.js

@@ -0,0 +1,228 @@
+// Debounced per-project job: overlaps, projections, FalkorDB graph algorithms.
+// Never inline with ingest; results land as properties so reads stay one hop.
+const { bus } = require("./bus");
+const keys = require("./keys");
+const { each } = require("./write");
+
+const DEBOUNCE_MS = 15_000;
+const MIN_INTERVAL_MS = 30_000;
+const OVERLAP_WINDOW_MS = 5 * 60 * 1000;
+const MAX_FILES_PER_SESSION = 50;
+
+let api = null;
+const timers = new Map();
+const lastRun = new Map();
+const running = new Set();
+
+const OVERLAP_CANDIDATES = `
+MATCH (e1:Edit)-[:MODIFIED]->(f:File)<-[:MODIFIED]-(e2:Edit)
+WHERE e1.key < e2.key AND abs(e1.ts - e2.ts) <= $window
+  AND NOT (e1)-[:SAME_CHANGE]->() AND NOT (e2)-[:SAME_CHANGE]->()
+MATCH (e1)-[:BY]->(a1:Agent), (e2)-[:BY]->(a2:Agent)
+WHERE a1.key <> a2.key
+RETURN f.key AS fileKey, e1.key AS k1, e2.key AS k2, e1.ts AS t1, e2.ts AS t2,
+       coalesce(e1.tsSynthetic, false) OR coalesce(e2.tsSynthetic, false) AS synthetic`;
+
+const OVERLAP_WRITE = `
+UNWIND $rows AS r
+MATCH (e1:Edit {key: r.k1})
+MATCH (e2:Edit {key: r.k2})
+MATCH (f:File {key: r.fileKey})
+MERGE (o:Overlap {key: r.key})
+  ON CREATE SET o.ts = r.ts, o.gapMs = r.gap, o.windowMs = $window, o.confidence = r.confidence
+MERGE (o)-[:ON]->(f)
+MERGE (o)-[:BETWEEN]->(e1)
+MERGE (o)-[:BETWEEN]->(e2)
+RETURN count(o) AS n`;
+
+const SESSION_FILES = `
+MATCH (s:Session)-[:MADE]->(:Edit)-[:MODIFIED]->(f:File)
+WITH s, collect(DISTINCT f.key) AS files
+WHERE size(files) > 1 AND size(files) <= $max
+RETURN files`;
+
+const SESSION_FILES_INCREMENTAL = `
+MATCH (s:Session)-[:MADE]->(e:Edit)
+WHERE e.ts >= $since
+WITH DISTINCT s
+MATCH (s)-[:MADE]->(:Edit)-[:MODIFIED]->(f:File)
+WITH s, collect(DISTINCT f.key) AS files
+WHERE size(files) > 1 AND size(files) <= $max
+RETURN s.key AS sessionKey, files`;
+
+const AGENT_OVERLAPS = `
+MATCH (o:Overlap)-[:BETWEEN]->(e:Edit)-[:BY]->(a:Agent)
+WITH o, collect(DISTINCT a.key) AS agents, max(o.ts) AS ts
+WHERE size(agents) = 2
+RETURN agents, ts`;
+
+const CLEAR = (rel) => `MATCH ()-[r:${rel}]->() DELETE r RETURN count(r) AS n`;
+
+const CO_EDITED_WRITE = `
+UNWIND $rows AS r
+MATCH (a:File {key: r.a})
+MATCH (b:File {key: r.b})
+MERGE (a)-[x:CO_EDITED]->(b) SET x.weight = r.w
+MERGE (b)-[y:CO_EDITED]->(a) SET y.weight = r.w
+RETURN count(x) AS n`;
+
+const CO_EDITED_SESSION_INCREMENTAL = `
+UNWIND $rows AS r
+MATCH (a:File {key: r.a})
+MATCH (b:File {key: r.b})
+MERGE (a)-[x:CO_EDITED]->(b)
+  ON CREATE SET x.sessions = []
+FOREACH (_ IN CASE WHEN r.s IN x.sessions THEN [] ELSE [1] END |
+  SET x.sessions = x.sessions + r.s)
+SET x.weight = size(x.sessions)
+MERGE (b)-[y:CO_EDITED]->(a)
+  ON CREATE SET y.sessions = []
+FOREACH (_ IN CASE WHEN r.s IN y.sessions THEN [] ELSE [1] END |
+  SET y.sessions = y.sessions + r.s)
+SET y.weight = size(y.sessions)
+RETURN count(x) AS n`;
+
+const PRUNE_TURN_TEXT = `
+MATCH (t:Turn)
+WHERE t.ts < $cutoff AND t.text IS NOT NULL
+SET t.text = NULL, t.prunedAt = $now
+RETURN count(t) AS n`;
+
+const PRUNE_EDIT_DIFF = `
+MATCH (e:Edit)
+WHERE e.ts < $cutoff AND e.diffHead IS NOT NULL
+SET e.diffHead = NULL, e.prunedAt = $now
+RETURN count(e) AS n`;
+
+const OVERLAPS_WITH_WRITE = `
+UNWIND $rows AS r
+MATCH (a:Agent {key: r.a})
+MATCH (b:Agent {key: r.b})
+MERGE (a)-[x:OVERLAPS_WITH]->(b) SET x.weight = r.w, x.lastAt = r.lastAt
+MERGE (b)-[y:OVERLAPS_WITH]->(a) SET y.weight = r.w, y.lastAt = r.lastAt
+RETURN count(x) AS n`;
+
+const FILE_RANK = `CALL algo.pageRank('File', 'CO_EDITED') YIELD node, score SET node.rank = score RETURN count(node) AS n`;
+const FILE_COMMUNITY = `CALL algo.labelPropagation({nodeLabels: ['File'], relationshipTypes: ['CO_EDITED']}) YIELD node, communityId
+SET node.community = communityId RETURN count(node) AS n`;
+const AGENT_RANK = `CALL algo.pageRank('Agent', 'OVERLAPS_WITH') YIELD node, score SET node.entanglement = score RETURN count(node) AS n`;
+
+/**
+ * Prunes Turn.text and Edit.diffHead older than `days` while preserving all nodes,
+ * edges, timestamps, and metadata (#18).
+ */
+async function pruneText(client, projectId, days = 90, now = Date.now()) {
+  if (!Number.isFinite(days) || days <= 0) return { turnsPruned: 0, editsPruned: 0 };
+  const cutoff = now - days * 24 * 60 * 60 * 1000;
+  const tRes = await client.write(projectId, PRUNE_TURN_TEXT, { cutoff, now });
+  const eRes = await client.write(projectId, PRUNE_EDIT_DIFF, { cutoff, now });
+  return {
+    turnsPruned: Number(tRes[0]?.n || 0),
+    editsPruned: Number(eRes[0]?.n || 0),
+  };
+}
+
+async function run(projectId, opts = {}) {
+  const { client } = api;
+  const t = Date.now();
+  await api.ensureProject(projectId);
+
+  const metaRows = await client.read(projectId, "MATCH (m:Meta {key:'meta'}) RETURN coalesce(m.lastAnalyticsAt, 0) AS since");
+  const since = opts.full ? 0 : Number(metaRows[0]?.since || 0);
+
+  const candidates = await client.read(projectId, OVERLAP_CANDIDATES, { window: OVERLAP_WINDOW_MS });
+  const overlaps = candidates.map((c) => ({
+    key: keys.overlapKey(c.fileKey, c.k1, c.k2),
+    k1: c.k1,
+    k2: c.k2,
+    fileKey: c.fileKey,
+    ts: Math.max(c.t1, c.t2),
+    gap: Math.abs(c.t1 - c.t2),
+    confidence: c.synthetic ? "low" : "high",
+  }));
+  if (overlaps.length) await each(client, projectId, OVERLAP_WRITE, overlaps, { window: OVERLAP_WINDOW_MS });
+
+  // Incremental CO_EDITED projection (#18): only scan sessions that received edits since
+  // Meta.lastAnalyticsAt (or all sessions on cold start / opts.full). Each CO_EDITED edge
+  // tracks the set of session keys that co-edited the pair so weight = size(sessions) is
+  // idempotent across incremental runs.
+  const touchedSessions = await client.read(projectId, SESSION_FILES_INCREMENTAL, { since, max: MAX_FILES_PER_SESSION });
+  if (since === 0) await client.write(projectId, CLEAR("CO_EDITED"));
+  const incRows = [];
+  for (const { sessionKey, files } of touchedSessions) {
+    const sorted = [...files].sort();
+    for (let i = 0; i < sorted.length; i++) {
+      for (let j = i + 1; j < sorted.length; j++) {
+        incRows.push({ a: sorted[i], b: sorted[j], s: sessionKey });
+      }
+    }
+  }
+  if (incRows.length) await each(client, projectId, CO_EDITED_SESSION_INCREMENTAL, incRows);
+  const coCountRows = await client.read(projectId, "MATCH ()-[r:CO_EDITED]->() RETURN count(r) / 2 AS n");
+  const coEditedCount = Number(coCountRows[0]?.n || 0);
+
+  const agentPairs = new Map();
+  for (const { agents, ts } of await client.read(projectId, AGENT_OVERLAPS)) {
+    const [a, b] = [...agents].sort();
+    const row = agentPairs.get(`${a}|${b}`) || { a, b, w: 0, lastAt: 0 };
+    row.w += 1;
+    row.lastAt = Math.max(row.lastAt, ts);
+    agentPairs.set(`${a}|${b}`, row);
+  }
+  await client.write(projectId, CLEAR("OVERLAPS_WITH"));
+  if (agentPairs.size) await each(client, projectId, OVERLAPS_WITH_WRITE, [...agentPairs.values()]);
+
+  await client.write(projectId, FILE_RANK);
+  await client.write(projectId, FILE_COMMUNITY).catch(() => undefined);
+  await client.write(projectId, AGENT_RANK).catch(() => undefined);
+
+  const retentionDays = api.state?.cfg?.textRetentionDays ?? 90;
+  const pruned = await pruneText(client, projectId, retentionDays, t).catch(() => ({ turnsPruned: 0, editsPruned: 0 }));
+
+  await client.write(projectId, "MATCH (m:Meta {key:'meta'}) SET m.lastAnalyticsAt = $now RETURN 1", { now: t });
+
+  const summary = {
+    overlaps: overlaps.length,
+    coEdited: coEditedCount,
+    incrementalSessions: touchedSessions.length,
+    agentPairs: agentPairs.size,
+    turnsPruned: pruned.turnsPruned,
+    editsPruned: pruned.editsPruned,
+    ms: Date.now() - t,
+  };
+  api.projectStats(projectId).lastAnalytics = summary;
+  console.log(`[relay-falkor] ${projectId}: analytics ${JSON.stringify(summary)}`);
+  api.state.deps.sse?.emit?.("graph", { workspaceId: projectId, at: Date.now(), analytics: summary });
+  return summary;
+}
+
+function schedule(projectId) {
+  clearTimeout(timers.get(projectId));
+  const wait = Math.max(DEBOUNCE_MS, MIN_INTERVAL_MS - (Date.now() - (lastRun.get(projectId) || 0)));
+  const timer = setTimeout(async () => {
+    timers.delete(projectId);
+    if (running.has(projectId) || !api.client.available()) return;
+    running.add(projectId);
+    lastRun.set(projectId, Date.now());
+    try {
+      await run(projectId);
+    } catch (err) {
+      api.projectStats(projectId).lastError = `analytics: ${err.message || err}`;
+    } finally {
+      running.delete(projectId);
+    }
+  }, wait);
+  if (timer.unref) timer.unref();
+  timers.set(projectId, timer);
+}
+
+function start(falkor) {
+  api = { ...falkor, client: falkor.state.client, state: falkor.state };
+  bus.on("graph-written", ({ projectId }) => projectId && schedule(projectId));
+}
+
+function configure(falkor) {
+  api = { ...falkor, client: falkor.state.client, state: falkor.state };
+}
+
+module.exports = { start, configure, run, schedule, pruneText };

package/backend/lib/falkor/bus.js

@@ -0,0 +1,16 @@
+const { EventEmitter } = require("events");
+
+// Taps in existing modules emit here; the falkor module subscribes only when enabled.
+const bus = new EventEmitter();
+bus.setMaxListeners(50);
+
+function emit(type, payload) {
+  if (!bus.listenerCount(type)) return;
+  try {
+    bus.emit(type, payload);
+  } catch (err) {
+    console.warn(`[relay-falkor] ${type} listener failed: ${err.message || err}`);
+  }
+}
+
+module.exports = { bus, emit };

package/backend/lib/falkor/central.js

@@ -0,0 +1,281 @@
+// Decisions & tasks. MCP stdio processes append to the Central JSONL log themselves;
+// relay serve (the only graph writer) tails those files into the graph.
+const fs = require("fs");
+const path = require("path");
+const keys = require("./keys");
+const { storedText } = require("./redact");
+const { each } = require("./write");
+const { eventsPath } = require("../centralStore");
+const { loadRegistry, loadSession, projectDir } = require("../store");
+
+const POLL_MS = 5000;
+const DURING_WINDOW_MS = 10 * 60 * 1000;
+const MENTION = /(?:[\w.-]+[\\/])*[\w-]+\.[A-Za-z][A-Za-z0-9]{0,5}\b/g;
+
+let api = null;
+const fileState = new Map();
+
+function cursorFile(projectId) {
+  return path.join(projectDir(projectId), "graph-central-cursor.json");
+}
+
+function loadCursor(projectId) {
+  try {
+    return JSON.parse(fs.readFileSync(cursorFile(projectId), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveCursor(projectId, cur) {
+  const file = cursorFile(projectId);
+  fs.writeFileSync(`${file}.tmp`, JSON.stringify(cur));
+  fs.renameSync(`${file}.tmp`, file);
+}
+
+function eventsDir() {
+  return path.dirname(eventsPath("_probe"));
+}
+
+/** A Central id is usually the relay project id; otherwise a project that names it as its centralProjectId. */
+function relayProjectFor(centralId) {
+  const projects = loadRegistry().projects || [];
+  return projects.find((p) => p.id === centralId) || projects.find((p) => p.centralProjectId === centralId) || null;
+}
+
+function mentions(text) {
+  const out = new Set();
+  const s = String(text || "");
+  let m;
+  MENTION.lastIndex = 0;
+  while ((m = MENTION.exec(s))) {
+    if (s.slice(Math.max(0, m.index - 3), m.index).includes("://")) continue;
+    if (/^\d+(\.\d+)+$/.test(m[0])) continue;
+    out.add(m[0].replace(/\\/g, "/"));
+  }
+  return [...out].slice(0, 20);
+}
+
+// Same fallback /api/ingest-stop uses for transcripts, so decisions and sessions agree on who "local" is.
+function loginFor(event) {
+  const user = String(event.user || "").trim();
+  if (user && user.toLowerCase() !== "local") return user;
+  try {
+    return loadSession().login || "local";
+  } catch {
+    return "local";
+  }
+}
+
+function labelFor(event) {
+  if (event.agent_label) return String(event.agent_label);
+  const parsed = keys.parseLockAgentId(event.agent_source);
+  return ["Claude Code", "Cursor", "Codex", "Copilot", "Antigravity"].includes(parsed.label) ? parsed.label : null;
+}
+
+function toRow(event) {
+  const kind = event.kind === "decision" ? "Decision" : event.kind === "task" ? "Task" : null;
+  if (!kind) return null;
+  const idField = kind === "Decision" ? event.decision_id : event.task_id;
+  const ts = Date.parse(event.ts) || Date.now();
+  const login = loginFor(event);
+  const label = labelFor(event);
+  const explicit = (Array.isArray(event.files) ? event.files : []).map((f) => ({ fileKey: keys.fileKey(f), path: keys.displayPath(f) })).filter((f) => f.fileKey);
+  return {
+    kind,
+    key: idField ? `${kind === "Decision" ? "d" : "k"}_${String(idField).slice(0, 120)}` : `evt_${event.event_id}`,
+    eventId: Number(event.event_id) || 0,
+    content: storedText(event.content || "", 2000, api.state.cfg.storeText) ?? "",
+    status: String(event.status || "open").slice(0, 40),
+    ts,
+    login: keys.loginKey(login),
+    loginRaw: login,
+    label,
+    agentKey: label ? keys.agentKey(login, label) : null,
+    attribution: label ? (event.agent_label ? "explicit" : "inferred") : "unknown",
+    explicit,
+    mentioned: explicit.length ? [] : mentions(event.content),
+  };
+}
+
+const UPSERT = (label, textProp, rel) => `
+UNWIND $rows AS r
+MERGE (d:${label} {key: r.key})
+  ON CREATE SET d.createdAt = r.ts, d.updatedAt = r.ts, d.${textProp} = r.content, d.status = r.status,
+                d.eventIds = [], d.attribution = r.attribution
+FOREACH (_ IN CASE WHEN r.ts >= d.updatedAt THEN [1] ELSE [] END |
+  SET d.${textProp} = r.content, d.status = r.status, d.updatedAt = r.ts)
+SET d.eventIds = CASE WHEN r.eventId IN d.eventIds THEN d.eventIds ELSE d.eventIds + r.eventId END
+SET d.revisions = size(d.eventIds)
+FOREACH (_ IN CASE WHEN r.agentKey IS NULL THEN [] ELSE [1] END |
+  MERGE (p:Person {key: r.login}) ON CREATE SET p.login = r.loginRaw, p.firstSeen = r.ts
+  MERGE (a:Agent {key: r.agentKey}) ON CREATE SET a.label = r.label, a.login = r.login, a.firstSeen = r.ts
+  MERGE (p)-[:RUNS]->(a)
+  MERGE (a)-[x:${rel}]->(d)
+  SET x.ts = r.ts)
+RETURN count(d) AS n`;
+
+const ABOUT_EXPLICIT = (label) => `
+UNWIND $rows AS r
+MATCH (d:${label} {key: r.key})
+MERGE (f:File {key: r.fileKey}) ON CREATE SET f.path = r.path, f.editCount = 0
+MERGE (d)-[a:ABOUT]->(f)
+SET a.how = 'explicit'
+RETURN count(a) AS n`;
+
+const FILE_CANDIDATES = `
+UNWIND $tokens AS tok
+MATCH (f:File)
+WHERE f.key = tok OR f.key ENDS WITH ('/' + tok)
+RETURN tok, collect(f.key) AS keys`;
+
+const ABOUT_MENTIONED = (label) => `
+UNWIND $rows AS r
+MATCH (d:${label} {key: r.key})
+MATCH (f:File {key: r.fileKey})
+MERGE (d)-[a:ABOUT]->(f)
+ON CREATE SET a.how = 'mentioned'
+RETURN count(a) AS n`;
+
+// Prefer the same person's session; any session of that agent is the fallback.
+const SESSION_NEAR = `
+MATCH (s:Session)
+WHERE s.label = $label AND s.lastAt >= $from AND s.lastAt <= $to
+RETURN s.key AS key, s.login = $login AS samePerson
+ORDER BY samePerson DESC, s.lastAt DESC LIMIT 1`;
+
+const DURING = (label) => `
+UNWIND $rows AS r
+MATCH (d:${label} {key: r.key})
+MATCH (s:Session {key: r.sessionKey})
+MERGE (d)-[x:DURING]->(s)
+SET x.confidence = 'inferred'
+RETURN count(x) AS n`;
+
+async function writeRows(projectId, rows) {
+  const { client } = api;
+  for (const label of ["Decision", "Task"]) {
+    const group = rows.filter((r) => r.kind === label);
+    if (!group.length) continue;
+    await each(client, projectId, UPSERT(label, label === "Decision" ? "content" : "description", label === "Decision" ? "DECIDED" : "UPDATED"), group);
+
+    const explicit = group.flatMap((r) => r.explicit.map((f) => ({ key: r.key, ...f })));
+    if (explicit.length) await each(client, projectId, ABOUT_EXPLICIT(label), explicit);
+
+    const tokens = [...new Set(group.flatMap((r) => r.mentioned.map((m) => keys.fileKey(m)).filter(Boolean)))];
+    if (tokens.length) {
+      const found = await client.read(projectId, FILE_CANDIDATES, { tokens });
+      // A bare "index.ts" matching five files means nothing; only link unambiguous mentions.
+      const resolved = new Map(found.filter((row) => row.keys.length === 1).map((row) => [row.tok, row.keys[0]]));
+      const links = group.flatMap((r) =>
+        r.mentioned.map((m) => resolved.get(keys.fileKey(m))).filter(Boolean).map((fileKey) => ({ key: r.key, fileKey }))
+      );
+      if (links.length) await each(client, projectId, ABOUT_MENTIONED(label), links);
+    }
+
+    const during = [];
+    for (const r of group) {
+      if (!r.label) continue;
+      const near = await client.read(projectId, SESSION_NEAR, { label: r.label, login: r.login, from: r.ts - DURING_WINDOW_MS, to: r.ts + DURING_WINDOW_MS });
+      if (near[0]?.key) during.push({ key: r.key, sessionKey: near[0].key });
+    }
+    if (during.length) await each(client, projectId, DURING(label), during);
+  }
+}
+
+function readNewEvents(file, after) {
+  const out = [];
+  let text = "";
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return out;
+  }
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    try {
+      const ev = JSON.parse(line);
+      if (Number(ev.event_id) > after) out.push(ev);
+    } catch {
+      /* partial line; picked up next poll */
+    }
+  }
+  return out;
+}
+
+let scanning = false;
+
+async function scan() {
+  if (scanning) return;
+  scanning = true;
+  try {
+    await scanOnce();
+  } finally {
+    scanning = false;
+  }
+}
+
+async function scanOnce() {
+  if (!api.client.available()) return;
+  let names = [];
+  try {
+    names = fs.readdirSync(eventsDir()).filter((n) => n.endsWith(".jsonl"));
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const file = path.join(eventsDir(), name);
+    let mtime = 0;
+    try {
+      mtime = fs.statSync(file).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (fileState.get(file) === mtime) continue;
+    const centralId = name.replace(/\.jsonl$/, "");
+    const project = relayProjectFor(centralId);
+    if (!project) {
+      fileState.set(file, mtime);
+      continue;
+    }
+    const cur = loadCursor(project.id);
+    const after = Number(cur[centralId] || 0);
+    const events = readNewEvents(file, after);
+    const rows = events.map(toRow).filter(Boolean);
+    try {
+      if (rows.length) {
+        await api.ensureProject(project.id);
+        await writeRows(project.id, rows);
+        console.log(`[relay-falkor] ${project.id}: +${rows.length} decision/task event(s)`);
+        api.notify?.(project.id, { decisions: rows.length });
+      }
+      if (events.length) {
+        cur[centralId] = Math.max(after, ...events.map((e) => Number(e.event_id) || 0));
+        saveCursor(project.id, cur);
+      }
+      fileState.set(file, mtime);
+    } catch (err) {
+      api.projectStats(project.id).lastError = String(err.message || err);
+    }
+  }
+}
+
+function start(falkor) {
+  api = { ...falkor, client: falkor.state.client, state: falkor.state };
+  const tick = () => scan().catch(() => undefined);
+  const t = setInterval(tick, POLL_MS);
+  if (t.unref) t.unref();
+  try {
+    fs.mkdirSync(eventsDir(), { recursive: true });
+    fs.watch(eventsDir(), { persistent: false }, () => setTimeout(tick, 200));
+  } catch {
+    /* polling covers it */
+  }
+  setTimeout(tick, 1000);
+}
+
+function configure(falkor) {
+  api = { ...falkor, client: falkor.state.client, state: falkor.state };
+}
+
+module.exports = { start, configure, scan, toRow, mentions, writeRows };