huddle-cli 0.1.0 → 0.1.3

package/dist/orchestrator/radar.js

@@ -0,0 +1,719 @@
+// Integration radar: catch "claude named it XYZ, codex named it ABC" while
+// they work, not at merge time.
+//
+// Every tick it snapshots each in-flight worktree into a throwaway WIP commit
+// (a temp index, so the agent's own index and files are never touched), then
+// for every pair of agents:
+//   overlap  — `git merge-tree` of the two WIPs: the files/lines the merge
+//              would conflict on, told to both while they can still agree;
+//   mismatch — B imports name N from module M, A is changing M and A's M
+//              doesn't define N: told to both, with A's closest export.
+// Findings are deduped (re-alerted only after 3 unresolved ticks) and capped
+// at 2 messages per agent per tick. Never runs tests; skips unchanged
+// snapshots; anything that fails just means no finding this tick.
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Re-alert an unresolved finding after this many ticks. */
+export const REALERT_TICKS = 3;
+/** Messages one agent gets from the radar per tick, at most. */
+export const MAX_MSGS_PER_TICK = 2;
+const MAX_FILES = 150; // changed files parsed per agent per tick
+const MAX_BLOB = 200_000; // bytes of one file we bother parsing
+const MAX_TOTAL = 2_000_000; // bytes parsed per agent per tick
+/**
+ * HUDDLE_RADAR_SEC: seconds between ticks; "off" or 0 = no radar (null).
+ * Default 20s: found live (capstone round 4), tasks took 40s-2m, so at 45s a
+ * short task could start and land between two ticks without being looked at.
+ */
+export function radarIntervalFromEnv() {
+    const raw = (process.env.HUDDLE_RADAR_SEC ?? "").trim().toLowerCase();
+    if (raw === "off" || raw === "0")
+        return null;
+    const s = Number(raw);
+    return raw && Number.isFinite(s) && s > 0 ? s * 1000 : 20_000;
+}
+function run(cwd, args, env) {
+    return new Promise((resolve) => {
+        execFile("git", args, 
+        // No optional locks: a status-style refresh must never take the agent's index lock.
+        { cwd, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", ...env } }, (err, stdout) => resolve({ code: err ? (typeof err.code === "number" ? err.code : 128) : 0, out: String(stdout ?? "") }));
+    });
+}
+async function git(cwd, args, env) {
+    const r = await run(cwd, args, env);
+    return r.code === 0 ? r.out.trim() : null;
+}
+/**
+ * `git cat-file --batch(-check)` over many `rev:path` specs in one process:
+ * sizes (check) or utf8 contents, null for a missing object; null if git failed.
+ */
+function catBatch(cwd, specs, check) {
+    if (!specs.length)
+        return Promise.resolve([]);
+    return new Promise((resolve) => {
+        const child = execFile("git", ["cat-file", check ? "--batch-check=%(objecttype) %(objectsize)" : "--batch"], { cwd, encoding: "buffer", maxBuffer: 2 * MAX_TOTAL + 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } }, (err, stdout) => {
+            if (err)
+                return resolve(null);
+            const buf = stdout;
+            const out = [];
+            let at = 0;
+            for (let i = 0; i < specs.length; i++) {
+                const nl = buf.indexOf(10, at);
+                if (nl < 0)
+                    return resolve(null);
+                const head = buf.subarray(at, nl).toString("utf8");
+                at = nl + 1;
+                const m = head.match(/(\S+) (\d+)$/);
+                if (!m || head.endsWith(" missing") || head.endsWith(" ambiguous")) {
+                    out.push(null);
+                    continue;
+                }
+                if (check) {
+                    out.push(m[1] === "blob" ? m[2] : null);
+                    continue;
+                }
+                const size = Number(m[2]);
+                out.push(m[1] === "blob" ? buf.subarray(at, at + size).toString("utf8") : null);
+                at += size + 1; // the content, then a newline
+            }
+            resolve(out);
+        });
+        child.stdin?.on("error", () => { }); // git gone early: the callback reports it
+        child.stdin?.end(specs.join("\n") + "\n");
+    });
+}
+const IDENT = {
+    GIT_AUTHOR_NAME: "huddle-radar",
+    GIT_AUTHOR_EMAIL: "radar@huddle.local",
+    GIT_COMMITTER_NAME: "huddle-radar",
+    GIT_COMMITTER_EMAIL: "radar@huddle.local",
+};
+/**
+ * The worktree's files as a WIP commit, via a separate index — git add -A
+ * respects .gitignore; the Plug wiring is left out like the merge commit does.
+ * `indexFile` is kept between ticks so unchanged files aren't re-hashed; it
+ * starts as a copy of the agent's index (its stat cache), never the original.
+ */
+export async function snapshot(wt, mainSha, excludes = [], indexFile) {
+    if (!fs.existsSync(wt))
+        return null;
+    const head = await git(wt, ["rev-parse", "HEAD"]);
+    if (!head)
+        return null;
+    // Mid-merge/rebase (a resolver at work): the markers would be noise.
+    for (const p of ["MERGE_HEAD", "rebase-merge", "rebase-apply"]) {
+        const gp = await git(wt, ["rev-parse", "--path-format=absolute", "--git-path", p]);
+        if (gp && fs.existsSync(gp))
+            return null;
+    }
+    const dir = indexFile ? null : fs.mkdtempSync(path.join(os.tmpdir(), "huddle-radar-"));
+    const tmpIndex = indexFile ?? path.join(dir, "index");
+    try {
+        if (!fs.existsSync(tmpIndex)) {
+            const idx = await git(wt, ["rev-parse", "--path-format=absolute", "--git-path", "index"]);
+            if (idx && fs.existsSync(idx)) {
+                fs.copyFileSync(idx, tmpIndex);
+                // Keep the original's mtime: git trusts an entry's stat data only if the
+                // file is older than the index, so a fresh mtime on the copy would hide
+                // an edit made in the same second the agent's index was written.
+                const st = fs.statSync(idx);
+                fs.utimesSync(tmpIndex, st.atime, st.mtime);
+            }
+        }
+        const env = { GIT_INDEX_FILE: tmpIndex };
+        let live = excludes.filter((e) => e && !e.includes("..") && !path.isAbsolute(e));
+        // Excluding a path git already ignores makes `git add` fail outright
+        // (see prepareMerge): those are left out by .gitignore anyway.
+        if (live.length) {
+            const ignored = new Set(((await run(wt, ["check-ignore", "-z", "--", ...live])).out).split("\0").filter(Boolean));
+            live = live.filter((e) => !ignored.has(e));
+        }
+        // --ignore-errors: one unreadable file or a nested repo without commits
+        // (create-next-app before its first commit) mustn't blind the radar.
+        const add = await run(wt, ["add", "-A", "--ignore-errors", "--", ".", ...live.map((e) => `:!${e}`)], env);
+        if (add.code !== 0 && add.code !== 1)
+            return null;
+        const tree = await git(wt, ["write-tree"], env);
+        if (!tree)
+            return null;
+        // Deterministic dates: the same tree on the same head is the same commit sha.
+        const wip = await git(wt, ["commit-tree", tree, "-p", head, "-m", "huddle radar wip"], {
+            ...IDENT,
+            GIT_AUTHOR_DATE: "1700000000 +0000",
+            GIT_COMMITTER_DATE: "1700000000 +0000",
+        });
+        if (!wip)
+            return null;
+        const base = (await git(wt, ["merge-base", wip, mainSha])) ?? head;
+        return { head, tree, wip, base };
+    }
+    finally {
+        if (dir)
+            fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+// ---- parsing ---------------------------------------------------------------
+const JS = /\.(m|c)?(j|t)sx?$/;
+const PY = /\.py$/;
+const codeFile = (f) => JS.test(f) || PY.test(f);
+/** Names a file defines/exports; null = can't tell (export *, from x import *). */
+export function definedNames(file, text) {
+    const out = new Set();
+    if (PY.test(file)) {
+        for (const m of text.matchAll(/^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/gm))
+            out.add(m[1]);
+        for (const m of text.matchAll(/^([A-Za-z_]\w*)\s*(?::[^=\n]+)?=(?!=)/gm))
+            out.add(m[1]);
+        if (/^from\s+\S+\s+import\s+\*/m.test(text))
+            return null;
+        // Top-level imports are names in the module too (re-exports).
+        for (const m of text.matchAll(/^from\s+\S+\s+import\s+(\([^)]*\)|[^\n]+)/gm))
+            for (const n of splitNames(m[1]))
+                out.add(n.alias ?? n.name);
+        for (const m of text.matchAll(/^import\s+([^\n]+)/gm))
+            for (const part of m[1].split(",")) {
+                const mm = part.trim().match(/^([\w.]+)(?:\s+as\s+(\w+))?/);
+                if (mm)
+                    out.add(mm[2] ?? mm[1].split(".")[0]);
+            }
+        return out;
+    }
+    if (/^\s*export\s+\*\s+from/m.test(text))
+        return null;
+    for (const m of text.matchAll(/^\s*export\s+(?:declare\s+)?(?:default\s+)?(?:async\s+)?(?:abstract\s+)?(?:function\*?|const|let|var|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/gm))
+        out.add(m[1]);
+    if (/^\s*export\s+default\b/m.test(text))
+        out.add("default");
+    for (const m of text.matchAll(/^\s*export\s+(?:type\s+)?\{([^}]*)\}/gm))
+        for (const n of splitNames(m[1]))
+            out.add(n.alias ?? n.name);
+    // CommonJS
+    for (const m of text.matchAll(/(?:module\.)?exports\.([A-Za-z_$][\w$]*)\s*=/g))
+        out.add(m[1]);
+    for (const m of text.matchAll(/module\.exports\s*=\s*\{([^}]*)\}/g))
+        for (const part of m[1].split(",")) {
+            const k = part.trim().match(/^(?:async\s+)?([A-Za-z_$][\w$]*)/);
+            if (k)
+                out.add(k[1]);
+        }
+    if (/module\.exports\s*=(?!\s*\{)/.test(text))
+        return null; // module.exports = someObject: opaque
+    return out;
+}
+function splitNames(list) {
+    return list
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/(\/\/|#)[^\n]*/g, "")
+        .replace(/[()]/g, "")
+        .split(",")
+        .map((s) => s.trim().replace(/^type\s+/, ""))
+        .filter(Boolean)
+        .map((s) => {
+        const m = s.match(/^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+        return m ? { name: m[1], alias: m[2] } : null;
+    })
+        .filter((x) => !!x);
+}
+/** Named imports from local modules (relative JS specs, any Python from-import). */
+export function importedNames(file, text) {
+    const out = [];
+    if (PY.test(file)) {
+        for (const m of text.matchAll(/^\s*from\s+([.\w]+)\s+import\s+(\([^)]*\)|[^\n]+)/gm)) {
+            const names = splitNames(m[2]).map((n) => n.name);
+            if (names.length)
+                out.push({ module: m[1], names });
+        }
+        return out;
+    }
+    for (const m of text.matchAll(/import\s+(?:type\s+)?(?:[A-Za-z_$][\w$]*\s*,\s*)?\{([^}]*)\}\s*from\s*["']([^"']+)["']/g))
+        if (m[2].startsWith("."))
+            out.push({ module: m[2], names: splitNames(m[1]).map((n) => n.name) });
+    for (const m of text.matchAll(/\{([^}]*)\}\s*=\s*require\(\s*["']([^"']+)["']\s*\)/g))
+        if (m[2].startsWith("."))
+            out.push({
+                module: m[2],
+                names: m[1]
+                    .split(",")
+                    .map((s) => s.trim().split(/\s*:\s*/)[0])
+                    .filter((s) => /^[A-Za-z_$][\w$]*$/.test(s)),
+            });
+    return out.filter((r) => r.names.length);
+}
+/** Repo paths a module spec could mean, imported from `fromFile`. */
+export function candidatesFor(fromFile, spec) {
+    const dir = path.posix.dirname(fromFile);
+    if (PY.test(fromFile)) {
+        const lead = spec.match(/^\.*/)[0].length;
+        const rest = spec.slice(lead).split(".").filter(Boolean).join("/");
+        const roots = lead ? [path.posix.join(dir, ...Array(Math.max(0, lead - 1)).fill(".."))] : [".", dir];
+        return roots.flatMap((r) => (rest ? [path.posix.join(r, rest + ".py"), path.posix.join(r, rest, "__init__.py")] : [path.posix.join(r, "__init__.py")]));
+    }
+    const p = path.posix.normalize(path.posix.join(dir, spec));
+    const stem = p.replace(/\.(m|c)?(j|t)sx?$/, "");
+    const exts = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"];
+    return [p, ...exts.map((e) => stem + e), ...exts.map((e) => `${p}/index${e}`)];
+}
+export function editDistance(a, b) {
+    const d = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = d[0];
+        d[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const t = d[j];
+            d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = t;
+        }
+    }
+    return d[b.length];
+}
+/** The defined name closest to `n` (case-insensitive match first), if any is close-ish. */
+export function nearest(n, names) {
+    let best = null;
+    let score = Infinity;
+    const lo = n.toLowerCase();
+    for (const c of names) {
+        if (c === "default")
+            continue;
+        const s = c.toLowerCase() === lo ? 0 : editDistance(lo, c.toLowerCase());
+        if (s < score)
+            [best, score] = [c, s];
+    }
+    return best !== null && score <= Math.max(3, Math.ceil(n.length / 2)) ? best : null;
+}
+/** The function/class a line sits in, looking upward. */
+function symbolAt(lines, i) {
+    const decl = /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?\s+([A-Za-z_$][\w$]*)|class\s+([A-Za-z_$][\w$]*)|(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=|def\s+([A-Za-z_]\w*)|(?:interface|type)\s+([A-Za-z_$][\w$]*))/;
+    // The conflict may start on the declaration itself (both rewrote the signature).
+    for (let j = i + 1; j < Math.min(lines.length, i + 4) && !/^(=======|\|\|\|\|\|\|\|)/.test(lines[j]); j++) {
+        const m = lines[j].match(decl);
+        if (m)
+            return m.slice(1).find(Boolean) ?? null;
+    }
+    for (let j = i - 1; j >= 0 && j > i - 200; j--) {
+        if (/^(<<<<<<<|=======|>>>>>>>)/.test(lines[j]))
+            continue;
+        const m = lines[j].match(decl);
+        if (m)
+            return m.slice(1).find(Boolean) ?? null;
+    }
+    return null;
+}
+/**
+ * Every identifier in a file outside comments. A name that's in there at all
+ * (`export const { a, b } = x`, a try/except import, `module.exports = obj`)
+ * is too unclear to call missing: the radar stays quiet rather than send an
+ * agent off renaming working code.
+ */
+export function wordsIn(file, text) {
+    const bare = PY.test(file) ? text.replace(/#[^\n]*/g, "") : text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:\\])\/\/[^\n]*/g, "$1");
+    return new Set(bare.match(/[A-Za-z_$][\w$]*/g) ?? []);
+}
+// Temp index dirs of radars not stopped yet: removed if the process exits first.
+const liveDirs = new Set();
+function rmLiveDirs() {
+    for (const d of liveDirs)
+        fs.rmSync(d, { recursive: true, force: true });
+    liveDirs.clear();
+}
+export function createRadar(o) {
+    const agents = new Map(); // agent id -> last analysis
+    const pairCache = new Map();
+    const seen = new Map(); // finding key -> when last sent
+    let tickNo = 0;
+    // What it did, for the record (radar.stats): found live, "0 findings" couldn't tell a quiet radar from one that never looked.
+    const stats = { ticks: 0, looks: 0, pairs: 0, findings: 0 };
+    let busy = false;
+    let stopped = false;
+    // One index per worktree, kept across ticks (stat cache); removed on stop.
+    let indexDir = null;
+    const indexFor = (wt) => {
+        if (!indexDir) {
+            indexDir = fs.mkdtempSync(path.join(os.tmpdir(), "huddle-radar-"));
+            if (!liveDirs.size)
+                process.once("exit", rmLiveDirs); // one listener however many radars
+            liveDirs.add(indexDir);
+        }
+        return path.join(indexDir, wt.replace(/[^\w.-]/g, "_").slice(-120) + ".index");
+    };
+    const cleanup = () => {
+        if (!indexDir)
+            return;
+        fs.rmSync(indexDir, { recursive: true, force: true });
+        liveDirs.delete(indexDir);
+        indexDir = null;
+        if (!liveDirs.size)
+            process.off("exit", rmLiveDirs);
+    };
+    const analyze = async (a, mainSha) => {
+        const snap = await snapshot(a.worktree, mainSha, a.excludes, indexFor(a.worktree));
+        if (!snap)
+            return null;
+        const prev = agents.get(a.agentId);
+        if (prev && prev.snap.wip === snap.wip && prev.snap.base === snap.base)
+            return prev; // unchanged: no re-parse
+        const names = (await run(a.worktree, ["diff", "--name-only", "--no-renames", "-z", snap.base, snap.wip])).out;
+        const changed = names.split("\0").filter((f) => f && codeFile(f)).slice(0, MAX_FILES);
+        const st = { snap, changed, defs: new Map(), words: new Map(), imports: new Map() };
+        // Two git processes for all files (sizes, then contents), not two per file.
+        const files = changed.filter((f) => !f.includes("\n"));
+        const sizes = await catBatch(a.worktree, files.map((f) => `${snap.wip}:${f}`), true);
+        if (!sizes || stopped)
+            return null;
+        const want = [];
+        let total = 0;
+        files.forEach((f, i) => {
+            const size = sizes[i] === null ? 0 : Number(sizes[i]);
+            if (!(size > 0))
+                st.defs.set(f, new Set()); // deleted in this WIP: defines nothing
+            else if (size > MAX_BLOB || total + size > MAX_TOTAL)
+                st.defs.set(f, null); // too big to read: unknown
+            else {
+                total += size;
+                want.push(f);
+            }
+        });
+        const texts = await catBatch(a.worktree, want.map((f) => `${snap.wip}:${f}`), false);
+        if (!texts)
+            return null;
+        want.forEach((f, i) => {
+            const text = texts[i];
+            if (text === null)
+                return void st.defs.set(f, null);
+            st.defs.set(f, definedNames(f, text));
+            st.words.set(f, wordsIn(f, text));
+            st.imports.set(f, importedNames(f, text));
+        });
+        return st;
+    };
+    const owner = (file, a, b, ca, cb) => {
+        try {
+            const claim = o.db
+                .listClaims()
+                .find((c) => (c.path === file || c.path.startsWith(file + "::")) && (c.held_by === a.agentId || c.held_by === b.agentId));
+            if (claim)
+                return claim.held_by === a.agentId ? a : b;
+        }
+        catch {
+            /* no claims: fall through */
+        }
+        return cb > ca ? b : a; // whoever changed more of it
+    };
+    const linesChanged = async (s, wt, file) => {
+        const r = await git(wt, ["diff", "--numstat", s.snap.base, s.snap.wip, "--", file]);
+        const m = r?.match(/^(\d+)\s+(\d+)/);
+        return m ? Number(m[1]) + Number(m[2]) : 0;
+    };
+    const overlaps = async (a, sa, b, sb) => {
+        // -z: paths with spaces or non-ASCII come back as-is, not C-quoted.
+        const r = await run(o.repoRoot, ["merge-tree", "--write-tree", "--name-only", "--no-messages", "-z", sa.snap.wip, sb.snap.wip]);
+        if (r.code !== 1)
+            return []; // 0 = clean; anything else = couldn't tell
+        const [tree, ...files] = r.out.split("\0").filter(Boolean);
+        const out = [];
+        for (const file of [...new Set(files)].slice(0, 5)) {
+            const merged = (await run(o.repoRoot, ["cat-file", "blob", `${tree}:${file}`])).out;
+            const lines = merged.split("\n");
+            const hunks = [];
+            let extra = 0; // marker + other-side lines before this point, so line numbers match the file
+            for (let i = 0, side = 0; i < lines.length; i++) {
+                if (lines[i].startsWith("<<<<<<<")) {
+                    hunks.push({ line: i + 1 - extra, sym: symbolAt(lines, i) });
+                    side = 1;
+                    extra++;
+                }
+                else if (side && /^(\|\|\|\|\|\|\||=======)/.test(lines[i])) {
+                    side = 2;
+                    extra++;
+                }
+                else if (side && lines[i].startsWith(">>>>>>>")) {
+                    side = 0;
+                    extra++;
+                }
+                else if (side === 2)
+                    extra++;
+            }
+            const syms = [...new Set(hunks.map((h) => h.sym).filter(Boolean))];
+            const where = hunks.length
+                ? `${file} ${syms.length ? syms.join(", ") + " " : ""}(line${hunks.length > 1 ? "s" : ""} ${hunks.map((h) => h.line).join(", ")})`
+                : file;
+            const own = owner(file, a, b, await linesChanged(sa, a.worktree, file), await linesChanged(sb, b.worktree, file));
+            const msg = (me, them) => `Huddle radar: ${them.agentId} (task ${them.taskId}) and you both changed ${where} — that would conflict at merge. ` +
+                `${own.agentId === me.agentId ? "You" : own.agentId} should own it; agree now via huddle_send(to="${them.agentId}") and the other side builds on it.`;
+            out.push({
+                kind: "overlap",
+                key: `overlap|${[a.agentId, b.agentId].sort().join("+")}|${file}|${syms.join(",")}`,
+                agent: a.agentId,
+                with: b.agentId,
+                task: a.taskId,
+                detail: `${where} (owner: ${own.agentId})`,
+                messages: { [a.agentId]: msg(a, b), [b.agentId]: msg(b, a) },
+            });
+        }
+        return out;
+    };
+    /** A Python package's submodule (`from . import store`) is not a name its __init__ must define. */
+    const isSubmodule = async (target, n, wips) => {
+        if (!/(^|\/)__init__\.py$/.test(target))
+            return false;
+        const dir = path.posix.dirname(target);
+        const paths = [`${n}.py`, `${n}/__init__.py`].map((p) => (dir === "." ? p : `${dir}/${p}`));
+        for (const w of wips)
+            for (const p of paths)
+                if ((await run(o.repoRoot, ["cat-file", "-e", `${w}:${p}`])).code === 0)
+                    return true;
+        return false;
+    };
+    /** importer's imports against definer's changed modules. */
+    const mismatches = async (imp, si, def, sd) => {
+        const out = [];
+        const theirs = new Set(sd.changed);
+        for (const [file, refs] of si.imports)
+            for (const ref of refs) {
+                const target = candidatesFor(file, ref.module).find((c) => theirs.has(c));
+                if (!target)
+                    continue;
+                const names = sd.defs.get(target);
+                if (!names || !names.size)
+                    continue; // unknown/opaque, or they deleted it: not a naming question
+                // The importer also edited that module and defines the name there itself: the merge carries it.
+                const mine = si.defs.get(target);
+                const words = sd.words.get(target);
+                for (const n of ref.names) {
+                    if (names.has(n) || mine?.has(n) || words?.has(n))
+                        continue;
+                    if (await isSubmodule(target, n, [sd.snap.wip, si.snap.wip]))
+                        continue;
+                    const near = nearest(n, names);
+                    const has = near ? `exports ${near}` : `exports ${[...names].filter((x) => x !== "default").slice(0, 3).join(", ") || "no such name"}`;
+                    const fix = near ? `one of you rename now (${n} or ${near}) and tell the other via huddle_send` : `agree on the name now via huddle_send`;
+                    const msg = (them) => `Huddle radar: ${imp.agentId} imports ${n} from ${target}, but ${def.agentId}'s ${target} ${has} — ${fix}${them ? ` (to="${them}")` : ""}.`;
+                    out.push({
+                        kind: "mismatch",
+                        key: `mismatch|${imp.agentId}|${def.agentId}|${target}|${n}`,
+                        agent: imp.agentId,
+                        with: def.agentId,
+                        task: imp.taskId,
+                        detail: `${imp.agentId} imports ${n} from ${target}; ${def.agentId}'s ${target} ${has}`,
+                        messages: { [imp.agentId]: msg(def.agentId), [def.agentId]: msg(imp.agentId) },
+                    });
+                }
+            }
+        return out;
+    };
+    /**
+     * A defined name that's a near-miss of a contract name (case, or a typo on
+     * a 5+ letter name) while the contract's spelling appears nowhere in the
+     * agent's work: told to that agent only. Short names need an exact
+     * case-fold match (id vs ID, not id vs ix). Worded as a question — it may
+     * be a separate helper — so nobody renames on the radar's say-so alone.
+     */
+    const contractDrift = (a, s, contract) => {
+        if (!contract.length)
+            return [];
+        const out = [];
+        const everywhere = new Set();
+        for (const w of s.words.values())
+            for (const x of w)
+                everywhere.add(x);
+        const close = (x, n) => {
+            const [lx, ln] = [x.toLowerCase(), n.toLowerCase()];
+            if (lx === ln)
+                return true;
+            const d = editDistance(lx, ln);
+            return (Math.min(x.length, n.length) >= 5 && d === 1) || (Math.min(x.length, n.length) >= 10 && d === 2);
+        };
+        for (const [file, names] of s.defs) {
+            if (!names)
+                continue;
+            for (const n of names) {
+                if (n === "default" || contract.includes(n))
+                    continue;
+                const c = contract.find((x) => close(x, n));
+                if (!c || everywhere.has(c))
+                    continue;
+                out.push({
+                    kind: "mismatch",
+                    key: `contract|${a.agentId}|${file}|${n}|${c}`,
+                    agent: a.agentId,
+                    with: "contract",
+                    task: a.taskId,
+                    detail: `${file} defines ${n}; the contract says ${c}`,
+                    messages: { [a.agentId]: `Huddle radar: your ${file} defines ${n}, but the shared contract names it ${c} — if it's meant to be the contract's ${c}, rename it now (or amend the contract) so the others' code matches.` },
+                });
+            }
+        }
+        return out;
+    };
+    /** One pass; returns the findings sent (or re-sent) this tick. */
+    const tick = async () => {
+        if (busy || stopped)
+            return [];
+        busy = true;
+        try {
+            tickNo++;
+            let raw = [];
+            try {
+                raw = o.inFlight() ?? [];
+            }
+            catch {
+                /* the board's state mid-change: try next tick */
+            }
+            const fly = raw.filter((x, i, all) => x && x.agentId && x.worktree && all.findIndex((y) => y?.agentId === x.agentId) === i);
+            for (const id of agents.keys())
+                if (!fly.some((f) => f.agentId === id))
+                    agents.delete(id);
+            for (const pk of pairCache.keys())
+                if (!pk.split("|").every((id) => fly.some((f) => f.agentId === id)))
+                    pairCache.delete(pk);
+            stats.ticks++;
+            if (fly.length < 2)
+                return [];
+            const mainSha = await git(o.repoRoot, ["rev-parse", "HEAD"]);
+            if (!mainSha)
+                return [];
+            const live = [];
+            for (const f of fly) {
+                if (stopped)
+                    return [];
+                const s = await analyze(f, mainSha).catch(() => null);
+                if (s) {
+                    agents.set(f.agentId, s);
+                    live.push({ f, s });
+                }
+            }
+            if (live.length >= 2) {
+                stats.looks++;
+                stats.pairs += (live.length * (live.length - 1)) / 2;
+            }
+            const found = [];
+            for (let i = 0; i < live.length; i++)
+                for (let j = i + 1; j < live.length; j++) {
+                    if (stopped)
+                        return [];
+                    const [A, B] = [live[i], live[j]];
+                    const pk = `${A.f.agentId}|${B.f.agentId}`;
+                    const sig = `${A.s.snap.wip}:${A.s.snap.base}|${B.s.snap.wip}:${B.s.snap.base}`;
+                    let c = pairCache.get(pk);
+                    if (!c || c.sig !== sig) {
+                        const fresh = [
+                            ...(await overlaps(A.f, A.s, B.f, B.s).catch(() => [])),
+                            ...(await mismatches(A.f, A.s, B.f, B.s).catch(() => [])),
+                            ...(await mismatches(B.f, B.s, A.f, A.s).catch(() => [])),
+                        ];
+                        c = { sig, findings: fresh };
+                        pairCache.set(pk, c);
+                    }
+                    found.push(...c.findings);
+                }
+            let contract = [];
+            try {
+                const names = o.contractNames?.();
+                contract = Array.isArray(names) ? names.filter((x) => typeof x === "string" && /^[A-Za-z_$][\w$]*$/.test(x)) : [];
+            }
+            catch {
+                /* no contract */
+            }
+            for (const { f, s } of live)
+                found.push(...contractDrift(f, s, contract));
+            // Resolved findings are forgotten, so a later reappearance is news again —
+            // but only when both sides were looked at: a snapshot that failed this
+            // tick (an agent mid-rebase) says nothing about whether it's fixed.
+            const now = new Set(found.map((x) => x.key));
+            const looked = new Set(["contract", ...live.map((l) => l.f.agentId)]);
+            const keyAgents = (k) => {
+                const [kind, x, y] = k.split("|");
+                return kind === "overlap" ? x.split("+") : kind === "contract" ? [x] : [x, y];
+            };
+            for (const k of seen.keys())
+                if (!now.has(k) && keyAgents(k).every((id) => looked.has(id))) {
+                    seen.delete(k);
+                    try {
+                        o.resolved?.(k);
+                    }
+                    catch {
+                        /* a bookkeeping error never stops the radar */
+                    }
+                }
+            if (stopped)
+                return []; // the board finished mid-tick: say nothing
+            const quota = new Map();
+            const sent = [];
+            // New findings before reminders, overlaps before mismatches.
+            const rank = (x) => (seen.has(x.key) ? 2 : 0) + (x.kind === "overlap" ? 0 : 1);
+            const order = [...found].sort((x, y) => rank(x) - rank(y));
+            for (const fd of order) {
+                const s = seen.get(fd.key);
+                if (s && tickNo - s.sentTick < REALERT_TICKS)
+                    continue;
+                const to = Object.keys(fd.messages);
+                if (to.some((r) => (quota.get(r) ?? 0) >= MAX_MSGS_PER_TICK))
+                    continue; // next tick
+                for (const r of to) {
+                    quota.set(r, (quota.get(r) ?? 0) + 1);
+                    try {
+                        o.notify(r, fd.messages[r], fd.key);
+                    }
+                    catch {
+                        /* an unreachable inbox never breaks a run */
+                    }
+                }
+                if (!s) {
+                    stats.findings++;
+                    const ev = { type: "radar", agent: fd.agent, with: fd.with, task: fd.task, kind: fd.kind, detail: fd.detail };
+                    try {
+                        o.db.publish("radar.finding", { agent_id: fd.agent, task_id: fd.task, payload: { ...ev, key: fd.key } });
+                    }
+                    catch {
+                        /* closed db */
+                    }
+                    try {
+                        o.onEvent(ev);
+                    }
+                    catch {
+                        /* a renderer bug never stops the radar */
+                    }
+                }
+                seen.set(fd.key, { sentTick: tickNo });
+                sent.push(fd);
+            }
+            return sent;
+        }
+        finally {
+            busy = false;
+            if (stopped)
+                cleanup();
+        }
+    };
+    return {
+        tick,
+        /** Ticks run, ticks that compared 2+ agents' work, pairs compared, findings sent. */
+        stats: () => ({ ...stats }),
+        stop: () => {
+            stopped = true;
+            if (!busy)
+                cleanup(); // else the running tick cleans up as it ends
+        },
+    };
+}
+/** Start the radar on an interval; returns stop. With <2 agents in flight a tick does nothing. */
+export function startRadar(o) {
+    const ms = o.intervalMs === undefined ? radarIntervalFromEnv() : o.intervalMs;
+    if (ms === null || !Number.isFinite(ms) || ms <= 0)
+        return () => { };
+    const r = createRadar(o);
+    const t = setInterval(() => void r.tick().catch(() => { }), Math.max(50, ms));
+    t.unref();
+    return () => {
+        clearInterval(t);
+        r.stop();
+        try {
+            o.db.publish("radar.stats", { payload: { ...r.stats(), interval_ms: ms } });
+        }
+        catch {
+            /* closed db */
+        }
+    };
+}
+//# sourceMappingURL=radar.js.map