syncstaff-mcp 0.2.3

package/README.md

@@ -0,0 +1,86 @@
+# Syncstaff MCP adapter
+
+`syncstaff-mcp` connects an MCP-capable coding agent to a hosted Syncstaff
+server. It contains only the local adapter; the Syncstaff API server, PostgreSQL
+driver, and arbiter SDK are not part of this package.
+
+## Login
+
+Run this from the repository you want your agent to edit:
+
+```bash
+npx -y syncstaff-mcp@0.2.3 setup
+```
+
+It uses the folder name as the project and defaults to the hosted server, so
+you can accept every prompt. Approving in the browser creates your workspace
+and project if you don't have them yet — **you do not need an account first.**
+
+No sign-in yet? The approval page is where you get one: it asks you to
+continue with GitHub, then finishes the connection.
+
+<https://www.syncstaff.ai>
+
+It asks for the Syncstaff server, project, and agent vendor, completes device login,
+and writes the repo-local `.mcp.json` configuration. Restart the coding agent
+when it finishes.
+
+From the repository the agent will edit, start a device login:
+
+```bash
+npx -y syncstaff-mcp@0.2.3 login \
+  --server https://api.syncstaff.ai \
+  --project your-project \
+  --vendor codex
+```
+
+Open the displayed link, approve the short code, and leave the command running
+until it confirms the connection. Syncstaff stores the returned credential in
+`.keel/config.json` with owner-only permissions and never prints the token.
+The repository's `.keel/` directory should remain ignored by Git.
+
+## MCP configuration
+
+Run the adapter from the repository the agent will edit so Syncstaff can inspect
+that checkout for call sites and unleased writes:
+
+```json
+{
+  "mcpServers": {
+    "sync": {
+      "command": "npx",
+      "args": ["-y", "syncstaff-mcp@0.2.3"]
+    }
+  }
+}
+```
+
+Node.js 22.5 or newer is required. The adapter communicates over stdio and
+registers with the configured Syncstaff server on its first tool call.
+Values supplied through `SYNCSTAFF_URL`, `SYNCSTAFF_PROJECT`, `SYNCSTAFF_TOKEN`, or
+`SYNCSTAFF_VENDOR` override the saved login when an explicit per-client setting is
+needed.
+
+Version 0.2.3 and newer bind every agent registration to the coding client's
+task/session id. If a client cannot expose that id automatically, call
+`sync_get(session_id="<the id shown by the client>")` once at session start.
+The adapter will not create an anonymous agent record, because an agent that
+cannot be correlated cannot be represented reliably in Workforce.
+
+Every HTTP request carries the adapter package version and an independent
+protocol version. A server that knows the protocol is incompatible answers
+with `426` and the protocol it supports, instead of letting a stale adapter
+silently call a changed route. Headerless web and legacy clients remain valid
+so the server and adapter can be deployed in either order.
+
+## Release verification
+
+From `keel/`, run:
+
+```bash
+npm run test:mcp-package
+```
+
+The smoke test builds only the adapter's TypeScript dependency graph, packs
+the exact npm artifact, installs it into a new temporary directory, and starts
+the installed `syncstaff-mcp` executable through an MCP initialize exchange.

package/dist/lib/agent-state.js

@@ -0,0 +1,119 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { keelEnv } from "./env-compat.js";
+/** Resolve the git root used by both the MCP process and lifecycle hooks. */
+export function repoRoot(cwd = process.cwd()) {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return resolve(cwd);
+    }
+}
+const slug = (s) => s.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 160);
+/**
+ * The session id of the client this process belongs to, or undefined.
+ *
+ * Every supported client exports one to its child processes, which is what
+ * lets a hook process and an MCP process for the *same* session agree on an
+ * identity without either being told: they read the same variable. The
+ * generic `CHARTER_SESSION_ID` wins so a harness can pin one explicitly.
+ *
+ * This must be consulted for **every** vendor. It previously read only
+ * `CODEX_THREAD_ID`, which is why Codex was the only client whose parallel
+ * sessions were ever isolated — see the note on `stateFile`.
+ */
+export function vendorSessionId() {
+    return (process.env.CHARTER_SESSION_ID ||
+        process.env.CODEX_THREAD_ID ||
+        process.env.CLAUDE_CODE_SESSION_ID ||
+        undefined);
+}
+/**
+ * Where a session's agent identity lives.
+ *
+ * Scoped by `vendor` **and** session, because a hook process and an MCP
+ * process for the *same session* must share one identity, while any two
+ * sessions must not — whether they are different clients or two windows of
+ * the same one. Sharing gives them a single agent id, and two agents with one
+ * id cannot collide, so coordination between them silently stops working.
+ *
+ * That second half went unenforced until 2026-08-20. The session segment was
+ * populated from `CODEX_THREAD_ID` alone, so every non-Codex client dropped it
+ * and every session of that client in a checkout shared one file, one agent id,
+ * and therefore one lease-holder. Two Claude Code sessions could take leases on
+ * the same path and each be told it was free. `sessionId` reaching here as
+ * null or undefined is what that bug looked like, so prefer
+ * :func:`vendorSessionId` over passing nothing.
+ */
+export function stateFile(root = repoRoot(), sessionId = vendorSessionId(), vendor = process.env.CHARTER_VENDOR) {
+    const explicit = keelEnv("STATE_FILE");
+    if (explicit)
+        return explicit;
+    const parts = ["state"];
+    if (vendor)
+        parts.push(slug(vendor));
+    if (sessionId)
+        parts.push(slug(sessionId));
+    return join(root, ".keel", `${parts.join("-")}.json`);
+}
+/**
+ * The state file to *read*, tolerating identities written before sessions were
+ * scoped.
+ *
+ * Writes always go to the session-scoped path from :func:`stateFile`. Reads
+ * come through here, which falls back to the legacy vendor-only path **only
+ * when this process cannot name its own session** — there is nothing more
+ * specific to prefer, so the pre-migration file is the best available guess.
+ *
+ * When a session id IS known, the scoped path is returned even if it does not
+ * exist yet on disk, and the legacy file is never consulted. That used to be
+ * a fallback for the boot-order case too — the scoped file for a real session
+ * genuinely not existing yet, indistinguishable on disk from a pre-migration
+ * checkout. In practice that made the fallback adoptable repeatedly and
+ * indefinitely: any process that starts before its own session-scoped file is
+ * written (an MCP server racing the SessionStart hook that creates it) picks
+ * up whichever *other* session last left a legacy file, caches that identity,
+ * and never notices the mismatch — two live sessions collapse onto one agent
+ * id, which is exactly the isolation failure session-scoping exists to
+ * prevent. A missing scoped file now simply means "not registered under this
+ * session yet"; the caller re-registers, which is cheap and correct.
+ */
+export function resolveStateFile(root = repoRoot(), sessionId = vendorSessionId(), vendor = process.env.CHARTER_VENDOR) {
+    const explicit = keelEnv("STATE_FILE");
+    if (explicit)
+        return explicit;
+    const scoped = stateFile(root, sessionId, vendor);
+    if (existsSync(scoped) || sessionId)
+        return scoped;
+    const legacy = stateFile(root, null, vendor);
+    return existsSync(legacy) ? legacy : scoped;
+}
+export function loadAgentState(file = stateFile()) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const state = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof state.server !== "string" ||
+            typeof state.project_id !== "string" ||
+            typeof state.agent_id !== "string" ||
+            typeof state.repo_root !== "string") {
+            return null;
+        }
+        return state;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveAgentState(state, file = stateFile()) {
+    mkdirSync(dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, file);
+}

package/dist/lib/blast.js

@@ -0,0 +1,462 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { globMatches, isGlob } from "./globs.js";
+import { now } from "./ids.js";
+import { buildGraphCallSiteIndex } from "./index/call-sites.js";
+import { discoverFiles } from "./index/discovery.js";
+import { LanguageRegistry } from "./index/registry.js";
+import { createTypeScriptParser } from "./index/typescript-parser.js";
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"]);
+const ANALYZABLE_KINDS = new Set(["function", "export", "class", "method", "constant"]);
+const MAX_REPORTED_SITES = 20_000;
+const MAX_CONTEXT_CHARS = 200;
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "out", ".venv", "venv",
+    "__pycache__", ".next", ".turbo", "coverage", ".keel",
+]);
+/**
+ * Files git is tracking, for resolving call sites against.
+ *
+ * An untracked file is **not** a call site. Nothing can break against a file
+ * that is not in the index: no other agent is building on it, it appears in
+ * nobody's commit, and it is not part of the contract this repository owes
+ * anyone. Counting it is not merely noise — it actively breaks coordination.
+ *
+ * Observed 20 Aug 2026 (`int_01M0FYFA6RTM45M2GZH0CPD974`). Three spent
+ * one-shot codemods sat untracked in the tree, each mentioning the declared
+ * symbols inside regex and string literals:
+ *
+ *     content.replace(/let projectId: string \| null = null;\n/, '')
+ *     content.indexOf('async function ensureAgent(')
+ *
+ * They call nothing. They contributed 12 apparent sites out of 40, which was
+ * enough to push the verdict to `wide`, raise an escalation, and have
+ * `lease_acquire` refuse the lease with "intent is escalated; awaiting human
+ * decision". The lease was then widened onto those same files, and
+ * `intent_complete` refused because they were dirty — a file the system added
+ * on the agent's behalf, blocking the agent. Clearing it took a human.
+ *
+ * Falls back to the full walk when git cannot answer, because a wrong-but-wide
+ * radius is a slower review, while a wrongly-empty one is a missed contract
+ * break — the same asymmetry `mergeCallSites` is built around.
+ *
+ * NOT for declared-path existence warnings. Those ask "is this path really
+ * there", and an untracked file genuinely is; filtering them to tracked-only
+ * would warn about real files an agent is about to add. Use
+ * :func:`discoverFiles` for that — its `-co` view includes them.
+ */
+export function listTrackedFiles(repoPath, maxFiles = 20000) {
+    try {
+        const out = execFileSync("git", ["-C", repoPath, "ls-files", "-z", "--cached"], {
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const tracked = out.split("\0").filter(Boolean);
+        // An empty result is not proof of an empty repo — a fresh checkout with
+        // nothing staged looks identical to a directory git does not own. Only a
+        // non-empty answer is evidence, so anything else falls back.
+        if (tracked.length > 0) {
+            return tracked
+                .map((file) => file.split("\\").join("/"))
+                .filter((file) => !file.split("/").some((segment) => SKIP_DIRS.has(segment)))
+                .slice(0, maxFiles);
+        }
+    }
+    catch {
+        // Not a git repository, or git is unavailable. Fall through.
+    }
+    // `discoverFiles` carries the walk fallback for a non-git checkout, and is
+    // the one enumerator this repository keeps. Its `-co` view is wider than
+    // `--cached` — it includes untracked-but-not-ignored files — which is the
+    // right direction to fail: a wide radius costs a slower review, an empty one
+    // costs a missed contract break.
+    return discoverFiles(repoPath, { limit: maxFiles });
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function pathCoveredBy(path, patterns) {
+    return patterns.some((p) => (isGlob(p) ? globMatches(p, path) : p === path));
+}
+/**
+ * The graph-backed analyzer, built lazily and once per process.
+ *
+ * `undefined` means "not yet attempted", `null` means "attempted and
+ * unavailable" — a repository with no parseable source, or an install without
+ * typescript. The distinction matters because retrying a failed load on every
+ * intent would pay the cost repeatedly to reach the same answer.
+ *
+ * Keyed by repo path: one agent process can be asked about more than one
+ * checkout, and an index of the wrong repository is worse than none.
+ */
+const graphIndexes = new Map();
+function graphIndexFor(repoPath) {
+    const cached = graphIndexes.get(repoPath);
+    if (cached !== undefined)
+        return cached;
+    const built = buildGraphCallSiteIndex(repoPath, () => {
+        // require rather than import: this module is loaded by the server and by
+        // the published adapter, and typescript must stay optional for the latter.
+        // A missing parser degrades to grep, which is why the analyzer is named in
+        // every report.
+        try {
+            const require = createRequire(import.meta.url);
+            const ts = require("typescript");
+            return new LanguageRegistry().register(createTypeScriptParser(ts));
+        }
+        catch {
+            return null;
+        }
+    });
+    graphIndexes.set(repoPath, built);
+    return built;
+}
+/** Test seam: forget cached indexes so a fixture repo is re-read. */
+export function resetGraphCallSiteCache() {
+    graphIndexes.clear();
+}
+/**
+ * Combine graph-confirmed sites with textual ones, keeping every location and
+ * preferring the confirmed label where both found the same place.
+ *
+ * Returns null only when BOTH analyzers returned null, which means nothing
+ * could look at this repository at all — the "unknown" status the protocol
+ * already understands. An empty array is a real answer; null is not.
+ */
+export function mergeCallSites(confirmed, textual) {
+    if (confirmed === null && textual === null)
+        return null;
+    const byLocation = new Map();
+    for (const site of textual ?? []) {
+        byLocation.set(`${site.path}:${site.line}`, { ...site, confidence: "unconfirmed" });
+    }
+    for (const site of confirmed ?? []) {
+        const key = `${site.path}:${site.line}`;
+        const existing = byLocation.get(key);
+        byLocation.set(key, {
+            // The graph knows the calling function; grep knows the source line.
+            // Where both saw a location, keep grep's richer context and the graph's
+            // verdict, because the verdict is the part a reader acts on.
+            ...(existing ?? site),
+            path: site.path,
+            line: site.line,
+            symbol: site.symbol,
+            context: existing?.context || site.context,
+            confidence: "confirmed",
+        });
+    }
+    return [...byLocation.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) || a.line - b.line);
+}
+/**
+ * Deterministic reference resolution (§5.8). Grep-grade rather than
+ * language-server-grade: finds call sites of the symbol's final dotted
+ * segment across TS/JS/Python source, skipping definition lines.
+ *
+ * Retained as the fallback for languages the graph has no backend for, and
+ * for installs without a parser. It cannot tell a call from a comment — see
+ * lib/index/call-sites.ts for what that cost — so callers must label which
+ * analyzer produced a report.
+ */
+export function resolveCallSites(repoPath, symbol, repoFiles) {
+    const lastSeg = symbol.split(".").pop() ?? symbol;
+    if (!lastSeg)
+        return [];
+    const sourceFiles = repoFiles.filter((f) => SOURCE_EXTS.has(f.slice(f.lastIndexOf("."))));
+    if (sourceFiles.length === 0)
+        return null; // no supported language → unknown
+    const callRe = new RegExp(`\\b${escapeRe(lastSeg)}\\s*\\(`);
+    const defRe = new RegExp(`\\b(def|function|class)\\s+${escapeRe(lastSeg)}\\b|\\b${escapeRe(lastSeg)}\\s*[:=]\\s*(async\\s+)?(function|\\()`);
+    const sites = [];
+    for (const file of sourceFiles) {
+        let content;
+        try {
+            content = readFileSync(join(repoPath, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!content.includes(lastSeg))
+            continue;
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!callRe.test(line))
+                continue;
+            if (defRe.test(line))
+                continue; // declaration, not a call site
+            sites.push({ path: file, line: i + 1, symbol, context: line.trim().slice(0, 200) });
+        }
+    }
+    return sites;
+}
+export function attachClientCallSiteReports(repoPath, interfaces, options = {}) {
+    // Tracked files only: an untracked file cannot be a call site anyone can
+    // break against. See listTrackedFiles for what counting them cost.
+    const repoFiles = listTrackedFiles(repoPath);
+    const includeContext = options.includeContext ?? true;
+    const analyzeChanges = new Set(options.analyzeChanges ?? ["signature", "added", "removed", "behavior"]);
+    const generatedAt = now();
+    return interfaces.map((iface) => {
+        if (!analyzeChanges.has(iface.change) || !ANALYZABLE_KINDS.has(iface.kind)) {
+            return iface;
+        }
+        // Union, not replacement, and the distinction was earned the hard way.
+        //
+        // The graph binds a call only where the name is defined in the calling
+        // file or imported into it, so it cannot be fooled by a comment. Using it
+        // ALONE looked right until the fixtures failed: code that calls through an
+        // unimported global resolves to nothing, and a contract break that grep
+        // had caught stopped being caught. Trading a false positive for a missed
+        // contract break is not an improvement — it is the same error pointed the
+        // other way.
+        //
+        // So both run. Graph hits are "confirmed", textual-only hits are
+        // "unconfirmed", and nothing is discarded. Recall is at least what it was;
+        // precision now lives in the label rather than in the count, and a
+        // consumer that wants the trustworthy subset filters on it.
+        // References, not calls. The intent-time surface and the hook-time surface
+        // now resolve through one function (R12.0), because two analyzers that
+        // answer "what references this symbol" differently is how an agent learns
+        // to trust neither. Before this, declaring an intent over a constant found
+        // only what grep found — `KEEL_RELEASE_VERSION(` appears nowhere, so a
+        // change to a constant four modules read produced an empty confirmed set.
+        //
+        // Import lines are the one kind left out, and the reason is not tidiness.
+        // A file that imports a symbol is already named by whatever it imported it
+        // FOR, so counting the import as well inflates the site count — which feeds
+        // the width threshold, which escalates to a human — without naming one
+        // additional file. A file that imports and never uses is dead code. Barrels
+        // are not affected: `export { X } from "./x.js"` is a re-export, which is
+        // counted, and is exactly the file that breaks when X is removed.
+        const graph = graphIndexFor(repoPath);
+        const graphSites = graph
+            ? graph.referencesFor(iface.name).filter((site) => site.kind !== "import")
+            : null;
+        const grepSites = resolveCallSites(repoPath, iface.name, repoFiles);
+        // Only label when the graph actually looked. Labelling grep-only results
+        // "unconfirmed" would be technically true and practically harmful: the
+        // width verdict discounts unconfirmed sites, so a repository with no
+        // parser backend would have every site discounted and could never be
+        // judged wide. Absent confidence means "nobody assessed this", which the
+        // verdict treats as countable — the behaviour that existed before.
+        const sites = graphSites ? mergeCallSites(graphSites, grepSites) : grepSites;
+        const analyzer = graphSites ? `${graph.analyzer}+grep-v1` : "grep-v1";
+        const report = {
+            source: "client",
+            analyzer,
+            generated_at: generatedAt,
+            status: sites === null ? "unknown" : "resolved",
+            truncated: (sites?.length ?? 0) > MAX_REPORTED_SITES,
+            call_sites: (sites ?? []).slice(0, MAX_REPORTED_SITES).map((site) => ({
+                ...site,
+                context: includeContext ? site.context.slice(0, MAX_CONTEXT_CHARS) : "",
+            })),
+        };
+        return { ...iface, call_site_report: report };
+    });
+}
+/**
+ * Analyzers whose reports this server will read.
+ *
+ * "grep-v1" is the original. "keel-graph-v1(...)" carries a parser signature,
+ * and a union report is "keel-graph-v1(...)+grep-v1". Matching by prefix means
+ * a client with an upgraded parser is not rejected by an older server, which
+ * is the failure mode that makes an agent's analysis silently disappear.
+ */
+const KNOWN_ANALYZER_PREFIXES = ["grep-v1", "keel-graph-v1"];
+function isKnownAnalyzer(analyzer) {
+    return (typeof analyzer === "string" &&
+        KNOWN_ANALYZER_PREFIXES.some((prefix) => analyzer.startsWith(prefix)));
+}
+function reportedSites(iface) {
+    const report = iface.call_site_report;
+    // The analyzer must be one this server understands, but the check is a
+    // prefix rather than an equality: it was `!== "grep-v1"` while grep was the
+    // only analyzer, and the moment the graph started labelling its reports
+    // honestly, every client report became unrecognised. The server then fell
+    // back to resolving against a checkout it does not have, so blast radius
+    // came back "unknown" and contract-break detection silently stopped — from
+    // a string comparison, with nothing logged.
+    //
+    // Anything a client sends is still validated below, path by path. This gate
+    // is about provenance, not trust, and it must not reject a newer analyzer
+    // from a client that is simply ahead of this server.
+    if (!report || report.source !== "client" || !isKnownAnalyzer(report.analyzer)) {
+        return undefined;
+    }
+    if (report.status !== "resolved")
+        return null;
+    if (!Array.isArray(report.call_sites))
+        return null;
+    const sites = [];
+    for (const raw of report.call_sites.slice(0, MAX_REPORTED_SITES)) {
+        if (!raw || typeof raw.path !== "string")
+            continue;
+        const path = raw.path.replaceAll("\\", "/");
+        if (path.length === 0 ||
+            path.length > 1_000 ||
+            path.startsWith("/") ||
+            path.split("/").includes("..") ||
+            path.includes("\0") ||
+            !Number.isInteger(raw.line) ||
+            raw.line < 1) {
+            continue;
+        }
+        sites.push({
+            path,
+            line: raw.line,
+            symbol: iface.name,
+            context: typeof raw.context === "string" ? raw.context.slice(0, MAX_CONTEXT_CHARS) : "",
+            // Carried through, because the verdict depends on it and rebuilding the
+            // site without it silently made every client report fully countable.
+            // Only the two known values are accepted; anything else becomes absent,
+            // which the verdict counts — the conservative direction.
+            //
+            // This is client-supplied, and so is the site list it belongs to: a
+            // client that wanted to suppress a wide verdict could already report no
+            // sites at all. Accepting the label adds no capability it did not have.
+            ...(raw.confidence === "confirmed" || raw.confidence === "unconfirmed"
+                ? { confidence: raw.confidence }
+                : {}),
+        });
+    }
+    return {
+        sites,
+        truncated: report.truncated === true || report.call_sites.length > MAX_REPORTED_SITES,
+    };
+}
+/**
+ * Resolve one interface's call sites from client metadata, falling back to a
+ * server checkout only when the report is absent or unknown.
+ */
+export function resolveSubjectCallSites(subject) {
+    const clientReport = reportedSites(subject);
+    if (clientReport) {
+        return {
+            sites: clientReport.sites,
+            source: "client",
+            truncated: clientReport.truncated,
+        };
+    }
+    // No server-side fallback, and `unavailable` is the honest answer.
+    //
+    // This used to grep a checkout on the server's own disk when a client sent
+    // no report. Three things were wrong with that, in increasing order of
+    // seriousness.
+    //
+    // It read the wrong code. The server's checkout is nobody's working tree —
+    // it is a third copy, at whatever commit it last pulled — so the answer
+    // described files no agent was editing.
+    //
+    // It used the worst analyzer to do it. `resolveCallSites` is grep-v1, whose
+    // failure mode is documented at length in index/call-sites.ts: asked for a
+    // method named `check` it returned 38 sites, sixteen in an unrelated Python
+    // package, one of them a comment reading "# side of the ORPHAN check (but
+    // NOT FTS". That count tripped the width threshold and summoned a human.
+    // The agent's own report comes from the TypeScript compiler over the exact
+    // files being changed, so the fallback was strictly worse evidence carrying
+    // exactly the same weight.
+    //
+    // And it broke a ratified invariant. inv_01KZWPAM9QCZ0DD7789N55X647 holds
+    // that the central server "must not process raw code"; `resolveCallSites`
+    // reads source files and returns 200 characters of the matched line. The
+    // privacy boundary this module documents for the client was breached from
+    // inside the server.
+    //
+    // A missing report now becomes the `unknown` verdict, which the protocol
+    // already understands as "proceed, but flagged as unanalysed". An honest
+    // gap is worth more than a confident answer about the wrong tree.
+    return { sites: null, source: "unavailable", truncated: false };
+}
+/**
+ * Resolve the blast radius of a declared intent (§5.8).
+ * - clean:    all call sites in free files → widen the lease
+ * - conflict: call sites inside another agent's leased files
+ * - wide:     total call sites over threshold → human decision
+ * - unknown:  language not resolvable → proceed but flag
+ * - skipped:  no interface changes / feature disabled / no repo checkout
+ */
+export function resolveBlastRadius(opts) {
+    const base = {
+        resolved_at: now(),
+        verdict: "skipped",
+        call_sites_total: 0,
+        call_sites_in_free_files: 0,
+        call_sites_in_leased_files: 0,
+        files_added_to_lease: [],
+        conflicting_files: [],
+    };
+    const changed = opts.interfaces.filter((i) => i.change !== "none" && ANALYZABLE_KINDS.has(i.kind));
+    if (!opts.enabled || changed.length === 0)
+        return base;
+    const hasClientReport = changed.some((iface) => iface.call_site_report !== undefined);
+    // No report at all is "nobody looked", which is what `skipped` already
+    // means. It is not "nothing calls this", and the server is no longer
+    // willing to invent the difference from a checkout of its own.
+    if (!hasClientReport)
+        return base;
+    let unknown = false;
+    const allSites = [];
+    for (const iface of changed) {
+        const resolved = resolveSubjectCallSites(iface);
+        if (resolved.truncated)
+            unknown = true;
+        const sites = resolved.sites;
+        if (sites === null) {
+            unknown = true;
+            continue;
+        }
+        allSites.push(...sites);
+    }
+    if (unknown && allSites.length === 0) {
+        base.verdict = "unknown";
+        return base;
+    }
+    const widen = new Set();
+    const conflictsByFile = new Map();
+    let covered = 0;
+    for (const site of allSites) {
+        if (pathCoveredBy(site.path, opts.intentPaths)) {
+            covered++;
+            continue;
+        }
+        const holder = opts.otherHeldLeases.find((l) => pathCoveredBy(site.path, l.paths));
+        if (holder) {
+            const entry = conflictsByFile.get(site.path) ?? { held_by_agent: holder.agent_id, call_sites: [] };
+            entry.call_sites.push(site);
+            conflictsByFile.set(site.path, entry);
+        }
+        else {
+            widen.add(site.path);
+        }
+    }
+    // The width verdict counts sites the graph could stand behind, plus any it
+    // never assessed. An explicitly unconfirmed site — a textual match nobody
+    // could bind to a definition — is still reported, still visible, and no
+    // longer able to escalate an intent on its own.
+    //
+    // This is the last piece of the 13 August failure. The comment
+    // "# side of the ORPHAN check (but NOT FTS" was one of 38 sites that tripped
+    // the width threshold. It is still in the report, because dropping evidence
+    // is its own bug, but it can no longer stop an agent and summon a human.
+    const countable = allSites.filter((site) => site.confidence !== "unconfirmed");
+    const unconfirmed = allSites.length - countable.length;
+    base.call_sites_total = allSites.length;
+    base.call_sites_unconfirmed = unconfirmed;
+    base.call_sites_in_leased_files = [...conflictsByFile.values()].reduce((n, c) => n + c.call_sites.length, 0);
+    base.call_sites_in_free_files = allSites.length - base.call_sites_in_leased_files - covered;
+    base.files_added_to_lease = [...widen].sort();
+    base.conflicting_files = [...conflictsByFile.entries()].map(([path, c]) => ({ path, ...c }));
+    if (countable.length > opts.threshold)
+        base.verdict = "wide";
+    else if (base.conflicting_files.length > 0)
+        base.verdict = "conflict";
+    else if (unknown)
+        base.verdict = "unknown";
+    else
+        base.verdict = "clean";
+    return base;
+}