syncstaff-mcp 0.2.3

package/dist/mcp/index.js

@@ -0,0 +1,1151 @@
+#!/usr/bin/env node
+/**
+ * keel-mcp — MCP adapter exposing the coordination tool surface (§6.4).
+ *
+ * Connection settings come from KEEL_URL / KEEL_PROJECT / KEEL_VENDOR /
+ * KEEL_TOKEN first, then the repo-local config written by `keel login`.
+ * KEEL_URL defaults to http://localhost:7377. Set
+ * KEEL_BLAST_INCLUDE_CONTEXT=0 to omit source snippets from client-side
+ * call-site reports. Retrieval rollout is local and fail-closed: use
+ * KEEL_RETRIEVAL_MODE=stable (default), candidate, or shadow. Set
+ * KEEL_RETRIEVAL_VOCABULARY=1 only for candidate/shadow testing of the
+ * bounded parser-derived lexical vocabulary; stable mode ignores it. Set
+ * KEEL_RETRIEVAL_ROUTING=1 to test candidate-only intent-specific query
+ * routing; stable mode ignores it.
+ * KEEL_RETRIEVAL_VERIFY=1 to run the local TypeScript checker against
+ * candidate-mode results and promote only candidates with call-site evidence;
+ * stable mode ignores it. Verification is budgeted and degrades to the
+ * unverified ranking when the checkout cannot be checked.
+ * KEEL_API_TIMEOUT_SECONDS (default 45, 0 disables) bounds every HTTP call
+ * this adapter makes to the Sync server, so a stalled request fails with a
+ * clear error instead of hanging for as long as the calling harness allows.
+ * KEEL_MCP_DAEMON=1 shares the local graph index (sync_impact /
+ * sync_context_card / sync_retrieve) across every agent CLI on this checkout
+ * through one background process instead of one per adapter process. Off by
+ * default — unset, this adapter's behavior is unchanged from before daemon
+ * mode existed. See daemon.ts for KEEL_MCP_DAEMON_IDLE_MINUTES (default 15)
+ * and KEEL_MCP_DAEMON_TIMEOUT_SECONDS (default 20).
+ *
+ * The agent is registered lazily on the first tool call. When a lifecycle
+ * hook registered the session first, the MCP process adopts that same id so
+ * lease checks and lease acquisition refer to one agent.
+ */
+// FIRST import, deliberately: it aliases KEEL_* ⇄ CHARTER_* on load, and the
+// module-scope reads below (and in agent-state) would otherwise run first and
+// see whichever prefix the caller happened not to set.
+import "../lib/env-compat.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { McpServer } from "@modelcontextprotocol/server";
+import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { loadAgentState, repoRoot, resolveStateFile, saveAgentState, stateFile, vendorSessionId, } from "../lib/agent-state.js";
+import { attachClientCallSiteReports } from "../lib/blast.js";
+import { discoverFiles } from "../lib/index/discovery.js";
+import { loadClientConfig } from "../lib/client-config.js";
+import { PROTOCOL_INSTRUCTIONS } from "../lib/protocol.js";
+import { globMatches, isGlob, pathsOverlap } from "../lib/globs.js";
+import { declaredPathWarnings } from "../lib/path-warnings.js";
+import { BOARD_KINDS, BOARD_STATUSES } from "../lib/types.js";
+import { adapterRequestHeaders, KEEL_ADAPTER_PROTOCOL_VERSION, KEEL_RELEASE_VERSION, } from "../lib/version.js";
+import { DEFAULT_IGNORES, findUnleasedWrites, fingerprintWrites, listWorktreeChanges, listWorktreeChangesStrict, upstreamLandingReport, } from "../lib/worktree.js";
+import { createApprovalGate } from "./approval.js";
+import { runLogin } from "./login.js";
+import { runSetup } from "./setup.js";
+import { waitForEscalation } from "./escalation-waiter.js";
+import { startCloudConnector } from "./cloud-connector.js";
+import { buildLocalGraph, runContextCard, runImpact, runRetrieve } from "./graph-ops.js";
+import { ensureDaemonSpawned, tryDaemon } from "./daemon-client.js";
+import { boardWriteReceipt, compactBoardItem, compactCharter, compactDeclaration, compactIntent, compactLeaseGrant, } from "../lib/mcp-compaction.js";
+const LOGIN_MODE = process.argv[2] === "login";
+const SETUP_MODE = process.argv[2] === "setup";
+const TEST_IMPORT_MODE = process.argv[2] === "__test_import__";
+const CLIENT_CONFIG = LOGIN_MODE ? null : loadClientConfig(repoRoot());
+const SERVER = process.env.KEEL_URL ?? CLIENT_CONFIG?.server ?? "http://localhost:7377";
+const PROJECT = process.env.KEEL_PROJECT ?? CLIENT_CONFIG?.project;
+const VENDOR = process.env.KEEL_VENDOR ?? CLIENT_CONFIG?.vendor ?? "other";
+const TOKEN = process.env.KEEL_TOKEN?.trim() ||
+    (CLIENT_CONFIG?.server.replace(/\/+$/, "") === SERVER.replace(/\/+$/, "")
+        ? CLIENT_CONFIG.token
+        : undefined);
+/**
+ * The MCP heartbeat makes an agent online, but Board Auto is driven by the
+ * repository CLI's separate runner. Starting it here closes the gap for MCP-
+ * only registrations; the runner's state-file lock makes repeated starts
+ * harmless when a lifecycle hook already launched it.
+ */
+export function localAutoRunnerCommand(root, statePath) {
+    const candidates = [
+        join(root, "keel", "dist", "src", "cli", "keel-cli.js"),
+        join(root, "dist", "src", "cli", "keel-cli.js"),
+    ];
+    const cli = candidates.find((candidate) => existsSync(candidate));
+    return cli ? { command: process.execPath, args: [cli, "auto-run", "--state-file", statePath] } : null;
+}
+function ensureLocalAutoRunner(root, statePath) {
+    const invocation = localAutoRunnerCommand(root, statePath);
+    if (!invocation)
+        return false;
+    const child = spawn(invocation.command, invocation.args, {
+        cwd: root,
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: { ...process.env, KEEL_VENDOR: VENDOR },
+    });
+    child.unref();
+    return true;
+}
+function envFlag(name, fallback) {
+    const value = process.env[name]?.trim().toLowerCase();
+    if (value === undefined)
+        return fallback;
+    return !["0", "false", "off", "no"].includes(value);
+}
+function envSeconds(name, fallback) {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function stateBelongsToAdapter(state, root, expectedProjectId, expectedSessionId) {
+    return Boolean(state &&
+        state.server.replace(/\/+$/, "") === SERVER.replace(/\/+$/, "") &&
+        state.project_id === expectedProjectId &&
+        state.repo_root === root &&
+        // Only adopt an identity this same client registered. Adopting another
+        // client's agent id would collapse two agents into one, and one agent
+        // cannot collide with itself — they would stop seeing each other.
+        state.vendor === VENDOR &&
+        // The same reasoning one level down, and the half that went unenforced:
+        // two sessions of one client collapse into a single agent just as
+        // completely as two clients do. A state file that records no session is
+        // pre-migration and adoptable once — that is the only way an in-flight
+        // session keeps its identity across this change. A file that records a
+        // *different* session is another live agent's, and adopting it is the
+        // bug this guard exists to prevent.
+        (state.session_id === undefined || state.session_id === expectedSessionId));
+}
+function apiHeaders() {
+    const headers = {
+        "content-type": "application/json",
+        ...adapterRequestHeaders(),
+    };
+    if (TOKEN)
+        headers.authorization = `Bearer ${TOKEN}`;
+    return headers;
+}
+/**
+ * Every call here used to be unbounded — plain `fetch` with no timeout of its
+ * own, so a stalled request rode whatever ceiling the calling harness
+ * happened to enforce. That ceiling has been observed at 1800s (see
+ * tsk_01M0SWY731SRA8NM83PEZC1PB3): a client blocked that long with "no
+ * response or progress" and nothing to act on, no matter which of the 30+
+ * routes this function serves was the one that stalled. The arbiter got the
+ * same bound for the same reason (commit 47ca50c) — this is the client-side
+ * half of the same fix, one level up the call chain.
+ *
+ * A generous default: legitimate calls finish in low seconds even with the
+ * arbiter in the loop. `KEEL_API_TIMEOUT_SECONDS=0` disables it for a slow
+ * link where 45s is provably too tight, rather than editing this file.
+ */
+const API_TIMEOUT_MS = envSeconds("KEEL_API_TIMEOUT_SECONDS", 45) * 1000;
+async function api(method, path, body, extraHeaders = {}) {
+    const controller = new AbortController();
+    const timer = API_TIMEOUT_MS > 0 ? setTimeout(() => controller.abort(), API_TIMEOUT_MS) : undefined;
+    let res;
+    try {
+        res = await fetch(`${SERVER}${path}`, {
+            method,
+            headers: { ...apiHeaders(), ...extraHeaders },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (e) {
+        if (controller.signal.aborted) {
+            // The request may still have landed server-side — an abort here only
+            // means this client gave up waiting, not that nothing happened. See
+            // tsk_01M0SWY731SRA8NM83PEZC1PB3 for the discovery path: check
+            // intent_list_active (or the relevant list tool) for what this call
+            // was trying to create before retrying, and reuse an idempotency_key
+            // where the tool accepts one rather than declaring blind.
+            throw new Error(`${method} ${path} timed out after ${API_TIMEOUT_MS / 1000}s with no response. ` +
+                `It may still have landed server-side — check before retrying blind ` +
+                `(e.g. intent_list_active for an intents call). Raise KEEL_API_TIMEOUT_SECONDS ` +
+                `if this route is legitimately slower than that.`);
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+        // 401 has exactly one cause worth naming: this machine has no usable
+        // token. It is the first thing a new collaborator hits — the MCP config
+        // is committed, so the server and project resolve fine and only the
+        // credential is missing — and the raw envelope gives them nothing to act
+        // on. Everything else keeps the literal response.
+        if (res.status === 401) {
+            throw new Error(`${method} ${path} -> 401: this machine has no valid Sync credential.\n` +
+                `Run:  npm --prefix keel run login -- --server ${SERVER}` +
+                (PROJECT ? ` --project ${PROJECT}` : "") +
+                ` --vendor ${VENDOR}\n` +
+                `Then run:  node keel/dist/src/cli/keel-cli.js doctor`);
+        }
+        throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(data)}`);
+    }
+    return data;
+}
+/**
+ * Like `api()`, but for a route that answers with raw bytes rather than
+ * JSON — the org-document download route is the only caller today. Kept
+ * separate rather than teaching `api()` a content-type branch: every other
+ * route on this server is JSON, and `api()`'s error handling (the 401
+ * message in particular) is written assuming a parseable body.
+ */
+async function apiRaw(path) {
+    const controller = new AbortController();
+    const timer = API_TIMEOUT_MS > 0 ? setTimeout(() => controller.abort(), API_TIMEOUT_MS) : undefined;
+    let res;
+    try {
+        res = await fetch(`${SERVER}${path}`, { headers: apiHeaders(), signal: controller.signal });
+    }
+    catch (e) {
+        if (controller.signal.aborted) {
+            throw new Error(`GET ${path} timed out after ${API_TIMEOUT_MS / 1000}s with no response.`);
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`GET ${path} -> ${res.status}: ${body}`);
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    return { contentType: res.headers.get("content-type") ?? "application/octet-stream", buffer };
+}
+/** Where each vendor wires its hooks, relative to the repo root. */
+const HOOK_CONFIGS = {
+    codex: [join(".codex", "hooks.json")],
+    claude_code: [join(".claude", "settings.json"), join(".claude", "settings.local.json")],
+};
+/**
+ * Does this checkout enforce leases through a preflight hook?
+ *
+ * If it does, the adapter must be *told* which session it serves, because it
+ * cannot work that out for itself and being wrong is silent. The adapter is a
+ * long-lived child process: it reads the client's session id from its own
+ * environment once, at spawn. When the client starts a new session in the same
+ * process tree — `/clear` in Claude Code, a new thread in Codex — the
+ * SessionStart hook registers a fresh agent under the *new* session id while
+ * the adapter keeps serving under the old one. Nothing errors. The two halves
+ * of one session simply hold two agent identities, and since the preflight
+ * hook checks leases against the hook's identity and every lease is taken
+ * under the adapter's, the agent is refused every edit it correctly leased —
+ * with its own intent quoted back to it as the blocking one.
+ *
+ * That failure is worse than a refusal to start: it punishes the agent that
+ * followed the protocol, and it looks like a coordination conflict rather than
+ * a misconfiguration, so it is diagnosed as the former.
+ *
+ * This was enforced for Codex alone, which is why only Codex was immune.
+ * The requirement never had anything to do with Codex — it follows from the
+ * hook, so it is asked of whichever vendor wires one.
+ */
+function hookBindingRequired(root) {
+    for (const relative of HOOK_CONFIGS[VENDOR] ?? []) {
+        try {
+            const config = readFileSync(join(root, relative), "utf8");
+            // Either binary name. The rename briefly broke this: the check looked for
+            // "keel-cli" while the config still said "charter-cli", so it returned
+            // false and Codex's session-binding requirement silently stopped being
+            // enforced — a guard that fails open reads exactly like a guard that passes.
+            const wired = config.includes("keel-cli") || config.includes("charter-cli");
+            if (wired && config.includes("preflight"))
+                return true;
+        }
+        catch {
+            // A vendor may wire only one of its config files; keep looking.
+        }
+    }
+    return false;
+}
+/**
+ * Serialise a tool result.
+ *
+ * Compact, not pretty-printed. Nothing reads this but a model, and indentation
+ * measured 20% of the bytes across the tool responses in 40 sessions' worth of
+ * transcripts — roughly 100k tokens of leading spaces and newlines for a
+ * readability nobody was consuming. JSON.stringify with no spacer is still
+ * valid JSON; a human debugging a response can pipe it through `jq`.
+ */
+function text(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+}
+// `instructions` reaches every MCP client at connect time. This is what makes
+// the experience uniform: a client with no hook support and no repo-local doc
+// file (Cursor, Gemini CLI, a homegrown agent) still gets the full protocol
+// before its first tool call.
+/**
+ * Report working-tree files changed without a lease.
+ *
+ * Runs where the checkout is, so it covers every client the same way —
+ * including ones that cannot block writes at the tool level, and shell
+ * writes (redirects, sed -i) that bypass tool hooks everywhere.
+ *
+ * This reports what the *worktree* looks like, which in a shared checkout
+ * includes other agents' edits. It deliberately does not claim authorship —
+ * the server decides whether this agent can be named. Content hashes travel
+ * with the report so the server can suppress a file that is merely still
+ * dirty while still alerting when it changes again; calling this often is
+ * therefore cheap.
+ */
+async function reportUnleasedWrites(projectId, agent) {
+    try {
+        const root = repoRoot();
+        const changes = listWorktreeChanges(root);
+        if (changes.length === 0)
+            return [];
+        const held = (await api("GET", `/leases?project_id=${projectId}`));
+        const allLeased = held.flatMap((l) => [...(l.paths ?? []), ...(l.secondary_paths ?? [])]);
+        const unleased = findUnleasedWrites(changes, allLeased);
+        if (unleased.length === 0)
+            return [];
+        const writes = fingerprintWrites(root, unleased);
+        // `paths` is sent alongside for a server that predates fingerprinting.
+        const res = await api("POST", "/unleased-writes", {
+            agent_id: agent,
+            writes,
+            paths: writes.map((w) => w.path),
+        });
+        return (res.alerted ?? []);
+    }
+    catch {
+        // detection is best-effort: never break a tool call over it
+        return [];
+    }
+}
+/**
+ * Opt-in retry safety (§11). A call whose response never arrived may still
+ * have committed; passing the same key on the retry returns the first
+ * attempt's answer with `replayed: true` rather than creating a second thing.
+ */
+const IDEMPOTENCY_KEY = z
+    .string()
+    .min(8)
+    .optional()
+    .describe("Pass the same value when retrying a call whose response you never saw, so the retry " +
+    "returns the original answer instead of creating a duplicate.");
+const interfaceSchema = z.object({
+    kind: z.enum(["function", "export", "class", "method", "route", "schema", "config", "env_var", "constant", "dependency"]),
+    name: z.string(),
+    change: z.enum(["none", "signature", "added", "removed", "behavior"]),
+});
+function withLocalCallSites(subjects, analyzeChanges) {
+    const contextSetting = process.env.KEEL_BLAST_INCLUDE_CONTEXT?.toLowerCase();
+    const includeContext = !["0", "false", "off", "no"].includes(contextSetting ?? "");
+    return attachClientCallSiteReports(repoRoot(), subjects, {
+        includeContext,
+        analyzeChanges,
+    });
+}
+export function createSyncMcpServer(requestContext) {
+    async function ensureAgent(extra, sessionIdFromArg) {
+        if (!PROJECT)
+            throw new Error("KEEL_PROJECT env var is required");
+        const root = repoRoot();
+        if (!requestContext)
+            requestContext = {};
+        const metaSessionId = extra?._meta?.session_id;
+        if (sessionIdFromArg)
+            requestContext.boundSessionId = sessionIdFromArg;
+        // Resolved for EVERY vendor, not just Codex. The `VENDOR === "codex"`
+        // gate that used to be here handed every other client a null session id,
+        // which drops the session segment from the state path — so all sessions of
+        // that client in one checkout shared a file, an agent id, and a lease
+        // holder. `vendorSessionId()` is the general form of the Codex thread id
+        // and needs no cooperation from the agent: every client exports its
+        // session to child processes, and the adapter is one.
+        //
+        // Told, versus inferred. Only the first three are the client speaking; the
+        // environment is the adapter guessing from the session it was spawned in,
+        // and that guess is what goes stale when the client starts a new session
+        // without restarting the adapter. Keeping the two apart is what lets a
+        // hook-enforced checkout insist on being told (see hookBindingRequired) —
+        // a check against the merged value cannot fire, because the stale guess is
+        // never absent.
+        const boundSessionId = metaSessionId ?? sessionIdFromArg ?? requestContext.boundSessionId ?? null;
+        const requestedSessionId = boundSessionId ?? vendorSessionId() ?? null;
+        if (!requestedSessionId) {
+            throw new Error("Syncstaff needs this coding task's session id before it can track the agent. " +
+                "Call sync_get(session_id=\"<this task's id>\") once, using the id shown by your coding client.");
+        }
+        if (hookBindingRequired(root) && !boundSessionId) {
+            throw new Error(`Sync session binding required: call sync_get(session_id="<this session's id>") before any other Sync tool.\n` +
+                "The SessionStart hook prints the id. This checkout enforces leases through a preflight hook, " +
+                "and an adapter that guesses its session from the environment can outlive the session it guessed — " +
+                "which hands one session two agent identities and refuses the agent its own leases.");
+        }
+        // Written session-scoped, read with a fallback to any pre-migration file,
+        // so a session already running when this shipped is not locked out.
+        const sessionStatePath = stateFile(root, requestedSessionId, VENDOR);
+        const sharedStateFile = resolveStateFile(root, requestedSessionId, VENDOR);
+        const cachedState = loadAgentState(sharedStateFile);
+        if (requestContext.projectId &&
+            requestContext.agentId &&
+            stateBelongsToAdapter(cachedState, root, requestContext.projectId, requestedSessionId) &&
+            cachedState.agent_id === requestContext.agentId) {
+            return { projectId: requestContext.projectId, agentId: requestContext.agentId };
+        }
+        const project = await api("GET", `/projects?name=${encodeURIComponent(PROJECT)}`);
+        const projectId = project.id;
+        let agentId = null;
+        const shared = loadAgentState(sharedStateFile);
+        if (stateBelongsToAdapter(shared, root, projectId, requestedSessionId)) {
+            try {
+                await api("POST", `/agents/${shared.agent_id}/heartbeat`, {
+                    vendor_session_id: requestedSessionId,
+                });
+                agentId = shared.agent_id;
+            }
+            catch { }
+        }
+        if (!agentId) {
+            const agent = await api("POST", "/agents", {
+                project_id: projectId,
+                vendor: VENDOR,
+                vendor_session_id: requestedSessionId,
+                human_owner: process.env.KEEL_HUMAN ?? process.env.USER ?? "unknown",
+                machine_id: hostname(),
+                checkout_path: root,
+                enforcement_level: "advisory",
+            });
+            agentId = agent.id;
+            saveAgentState({
+                server: SERVER,
+                project_id: projectId,
+                agent_id: agentId,
+                repo_root: root,
+                vendor: VENDOR,
+                ...(requestedSessionId ? { session_id: requestedSessionId } : {}),
+            }, 
+            // The scoped path, never the one a legacy fallback may have read from:
+            // writing back to the shared file is what would re-merge the identities.
+            sessionStatePath);
+        }
+        requestContext.projectId = projectId;
+        requestContext.agentId = agentId;
+        // Keep the resolved identity in the request context. Heartbeats must not
+        // depend on re-reading a process environment that may be absent or may
+        // change after the client reconnects.
+        requestContext.boundSessionId = requestedSessionId;
+        if (!requestContext.autoRunnerStarted) {
+            requestContext.autoRunnerStarted = true;
+            ensureLocalAutoRunner(root, existsSync(sessionStatePath) ? sessionStatePath : sharedStateFile);
+        }
+        if (!requestContext.heartbeatStarted) {
+            const hb = setInterval(() => {
+                const id = requestContext.agentId;
+                const pid = requestContext.projectId;
+                if (!id || !pid)
+                    return;
+                void api("POST", `/agents/${id}/heartbeat`, {
+                    vendor_session_id: requestContext.boundSessionId ?? vendorSessionId() ?? null,
+                }).catch(() => { });
+                void reportUnleasedWrites(pid, id);
+            }, 30000);
+            hb.unref();
+            requestContext.heartbeatStarted = true;
+        }
+        if (!requestContext.cloudConnectorStarted) {
+            requestContext.cloudConnectorStarted = true;
+            requestContext.cloudConnector = startCloudConnector({
+                api,
+                projectId,
+                machineId: hostname(),
+                displayName: hostname(),
+                clientVersion: KEEL_RELEASE_VERSION,
+                protocolVersion: String(KEEL_ADAPTER_PROTOCOL_VERSION),
+                platform: `${process.platform}-${process.arch}`,
+            });
+        }
+        return { projectId, agentId };
+    }
+    /**
+     * Human approval, backed by the escalation row rather than by this process.
+     *
+     * Declared before the server so the server can hand `requestState.verify` to
+     * the SDK seam: an echoed state is verified before the handler is entered,
+     * so a tool never sees an unverified one. See approval.ts for why the
+     * escalation id is the only thing that travels.
+     */
+    const approval = createApprovalGate({
+        api,
+        project: PROJECT ?? "",
+        repoRoot: repoRoot(),
+        token: TOKEN,
+        key: process.env.KEEL_REQUEST_STATE_KEY,
+        resolvedBy: process.env.KEEL_HUMAN ?? process.env.USER ?? "unknown",
+        // The era belongs to the connection, and `serveStdio` puts it on the
+        // context it builds this server with — there is no accessor on the server
+        // itself because a modern instance and a legacy one are different
+        // instances, not two modes of one.
+        era: () => requestContext?.era,
+    });
+    const mcp = new McpServer({ name: "sync", version: KEEL_RELEASE_VERSION }, {
+        instructions: PROTOCOL_INSTRUCTIONS,
+        requestState: { verify: approval.verify },
+    });
+    const registerGet = (name) => {
+        mcp.registerTool(name, {
+            description: "Fetch the project charter (purpose, non-goals, binding invariants). Call at session start, passing the session_id supplied by the Codex SessionStart hook when present. Re-read after any charter.amended event. If this fails, do not start work.",
+            inputSchema: z.object({
+                session_id: z
+                    .string()
+                    .optional()
+                    .describe("Codex session id printed by the SessionStart hook."),
+            })
+        }, async (args, extra) => {
+            const { session_id } = args;
+            const { projectId } = await ensureAgent(extra, session_id);
+            return text(compactCharter(await api("GET", `/charter?project_id=${projectId}`)));
+        });
+    };
+    registerGet("sync_get");
+    const registerWhoami = (name) => {
+        mcp.registerTool(name, {
+            description: "Report your agent id, the git repository root, and the project you are registered to. Call this if you are unsure what a path should be relative to — every path you pass to a Sync tool is relative to the repo_root returned here.",
+            inputSchema: z.object({})
+        }, async (_args, extra) => {
+            const { projectId, agentId } = await ensureAgent(extra);
+            return text({
+                agent_id: agentId,
+                project_id: projectId,
+                repo_root: repoRoot(),
+                vendor: VENDOR,
+                human_owner: process.env.NAIB_HUMAN ?? process.env.KEEL_HUMAN ?? process.env.USER ?? "unknown",
+                path_convention: "All paths are relative to repo_root, never to your cwd.",
+            });
+        });
+    };
+    registerWhoami("sync_whoami");
+    mcp.registerTool("token_usage_report", {
+        description: "Report one hourly token-usage period for this agent. Submit exact provider totals when available; set exact=false only when the host can provide an estimate. Send a final partial-period report when work finishes.",
+        inputSchema: z.object({
+            provider: z.string().describe("Model provider, for example openai, anthropic, or google."),
+            model: z.string().optional(),
+            period_start: z.string().describe("ISO-8601 start of this reporting period."),
+            period_end: z.string().describe("ISO-8601 end of this reporting period."),
+            input_tokens: z.number().int().nonnegative(),
+            output_tokens: z.number().int().nonnegative(),
+            cached_tokens: z.number().int().nonnegative().default(0),
+            reasoning_tokens: z.number().int().nonnegative().default(0),
+            intent_id: z.string().optional(),
+            task_id: z.string().optional(),
+            exact: z.boolean().default(true),
+        }),
+    }, async (args, extra) => {
+        const { agentId } = await ensureAgent(extra);
+        return text(await api("POST", "/token-usage", { ...args, agent_id: agentId }));
+    });
+    mcp.registerTool("lease_check", { description: "Check whether you currently hold a lease covering a specific file, BEFORE writing to it. Returns covered=true/false, and when false, names any other agent holding it. Some clients block unleased edits automatically; if yours does not, call this as your own preflight.", inputSchema: z.object({ path: z.string().describe("Path relative to the git repository root.") }) }, async (args, extra) => {
+        const { path } = args;
+        const { agentId } = await ensureAgent(extra);
+        const result = await api("GET", `/leases/check?agent_id=${agentId}&path=${encodeURIComponent(path)}`);
+        return text(result.covered
+            ? result
+            : {
+                ...result,
+                next_step: result.held_by_others?.length > 0
+                    ? "Another agent holds this path. Re-scope, take a partial grant, or pick a different task — do not edit it."
+                    : "You hold no lease on this path. Call intent_declare then lease_acquire before editing.",
+            });
+    });
+    const handleProposeAmendment = async (args, extra) => {
+        const { projectId, agentId } = await ensureAgent(extra);
+        // Round two: the client's human already answered. The escalation id
+        // came back sealed in requestState and was verified by the seam, so
+        // reaching here means it is the decision this server asked about.
+        const pending = await extra?.mcpReq?.requestState?.();
+        if (pending)
+            return text(await approval.answer(extra?.mcpReq?.inputResponses, pending));
+        const proposed = await api("POST", "/charter/propose", {
+            project_id: projectId,
+            agent_id: agentId,
+            ...args,
+        });
+        // The escalation is now durable whatever happens next. Everything
+        // below is about who gets asked, not about whether the decision
+        // exists — a process that dies here leaves a proposal a human can
+        // still answer on the web.
+        if (!approval.available(extra))
+            return text(proposed);
+        const escalations = (await api("GET", `/escalations?project_id=${encodeURIComponent(projectId)}`).catch(() => []));
+        const record = escalations.find((row) => row.id === proposed.escalation_id);
+        const options = (record?.options ?? []).map((option) => ({
+            id: String(option.id),
+            label: String(option.label),
+        }));
+        if (options.length === 0)
+            return text(proposed);
+        return approval.ask(extra, proposed.escalation_id, projectId, options, `Charter amendment proposed (${args.kind}):\n\n${args.text}\n\n` +
+            `Why: ${args.rationale ?? "(none)"}\n\nRatifying changes the binding document every agent reads.`);
+    };
+    const proposeAmendmentSchema = z.object({
+        kind: z.enum(["purpose", "non_goal_add", "invariant_add", "invariant_change", "invariant_remove"]),
+        text: z.string(),
+        rationale: z.string().optional(),
+        invariant_id: z.string().optional(),
+        task_id: z.string().optional(),
+    });
+    const proposeAmendmentDesc = "Propose a charter change when a task requires violating an invariant or the charter is silent on a decision you are about to make. Blocks THIS decision path until a human ratifies — continue other work while waiting.";
+    mcp.registerTool("sync_propose_amendment", { description: proposeAmendmentDesc, inputSchema: proposeAmendmentSchema }, handleProposeAmendment);
+    /**
+     * Do the declared paths exist? Answered here, in the checkout being edited.
+     *
+     * inv_01KYRCZX78VK0YYMHC4FYEHR5W says every path is git-root-relative, and
+     * nothing enforced it: a lease on `keel/src/server/db.ts` when the file is at
+     * `keel/src/lib/db.ts` is granted, renewed and released without complaint
+     * while the agent edits a file no lease covers.
+     *
+     * The server used to answer this from its own `repo_path`, which is a
+     * different checkout at a different commit and, on a second instance, may not
+     * exist at all — so the same declaration warned or stayed silent depending on
+     * which process picked it up. This machine has the only copy whose answer is
+     * about the files actually being changed.
+     *
+     * `null` rather than `[]` when the walk finds nothing: "could not look" and
+     * "looked, all fine" must stay distinguishable, or the check becomes a machine
+     * for crying wolf the first time a path is misconfigured.
+     */
+    function localPathWarnings(paths) {
+        if (paths.length === 0)
+            return [];
+        try {
+            // `declaredPathWarnings` returns null for an empty file list, which is the
+            // "could not look" case; a throw here is the same answer by another route.
+            return declaredPathWarnings(paths, discoverFiles(repoRoot()));
+        }
+        catch {
+            return null;
+        }
+    }
+    mcp.registerTool("intent_declare", { description: "Declare what you are about to do BEFORE editing any file: a one-sentence summary, the paths you will touch, and every interface you will add/remove/change. Returns an arbiter verdict and blast radius. If the coordinator escalates the declaration, this call waits briefly (KEEL_ESCALATION_WAIT_SECONDS, default 60) in case the decision is fast or already automated, then returns either way with the escalation_id. On a timeout the escalation is already durable — run `node keel/scripts/await-escalation.mjs <escalation_id>` in the background to keep watching it while you do something else, rather than re-declaring or retrying this call.", inputSchema: z.object({
+            summary: z.string(),
+            paths: z.array(z.string()),
+            interfaces_touched: z.array(interfaceSchema).default([]),
+            idempotency_key: IDEMPOTENCY_KEY,
+            task_id: z.string().optional(),
+        }) }, async (args, extra) => {
+        const { agentId, projectId } = await ensureAgent(extra);
+        const interfaces = withLocalCallSites(args.interfaces_touched);
+        // reportUnleasedWrites reads only project/agent state — never this
+        // call's own result — so it doesn't need to wait for the declare to
+        // land first. Run both concurrently rather than paying two sequential
+        // round trips on every intent_declare call.
+        //
+        // The heartbeat interval already runs this same check every 30s, but
+        // fire-and-forget and its result goes nowhere — so an agent starting
+        // work has no way to see, right now, that this checkout already has
+        // someone else's uncommitted, unleased changes sitting in it. The
+        // server dedupes by content hash, so calling it again here is cheap
+        // and never re-alerts on a file that was already reported stale.
+        const [declared, foreignWrites] = await Promise.all([
+            api("POST", "/intents", {
+                agent_id: agentId,
+                ...args,
+                interfaces_touched: interfaces,
+                path_warnings: localPathWarnings(args.paths ?? []),
+            }),
+            reportUnleasedWrites(projectId, agentId),
+        ]);
+        if (foreignWrites.length > 0) {
+            declared.checkout_warning =
+                `${foreignWrites.length} file${foreignWrites.length === 1 ? "" : "s"} in this checkout ` +
+                    `${foreignWrites.length === 1 ? "has" : "have"} uncommitted changes not covered by any lease — ` +
+                    `likely another agent sharing this checkout, not your own in-progress work: ` +
+                    `${foreignWrites.slice(0, 8).join(", ")}${foreignWrites.length > 8 ? `, +${foreignWrites.length - 8} more` : ""}. ` +
+                    `Only stage and commit the paths you actually declared.`;
+        }
+        if (!declared.escalation_id || !envFlag("KEEL_AUTO_WAIT_ESCALATIONS", true)) {
+            return text(compactDeclaration(declared));
+        }
+        const waited = await waitForEscalation({
+            escalationId: String(declared.escalation_id),
+            projectId,
+            server: SERVER,
+            headers: apiHeaders(),
+            fetchEscalations: async () => (await api("GET", `/escalations?project_id=${encodeURIComponent(projectId)}`)),
+            // Was 30*60: a human decision in this system typically takes minutes,
+            // not seconds, so the old default meant every escalated declaration
+            // surprise-blocked the caller for up to half an hour on the common
+            // case, not the rare one. 60s still catches a fast or already-
+            // automated resolution inline; anything slower should be watched with
+            // scripts/await-escalation.mjs instead of held open here. See
+            // tsk_01M17NJ3KKTEVTYEVGPCN957D7.
+            timeoutMs: envSeconds("KEEL_ESCALATION_WAIT_SECONDS", 60) * 1000,
+        });
+        return text({
+            ...compactDeclaration(declared),
+            escalation_wait: waited,
+            next_step: waited.status === "resolved"
+                ? "The durable human decision is applied. Continue based on escalation_wait.resolution and escalation_wait.changes."
+                : `The human decision did not arrive within the wait. The escalation is durable — run in the background: node keel/scripts/await-escalation.mjs ${declared.escalation_id}. Do not re-declare the same intent to keep waiting; that creates a duplicate.`,
+        });
+    });
+    /**
+     * Leased paths still uncommitted in this checkout.
+     *
+     * Reported at completion so the next agent to lease these files learns the
+     * work is here but not in git. A released lease otherwise makes a dirty file
+     * indistinguishable from a clean one. Runs client-side, where the checkout is.
+     */
+    async function dirtyLeasedPaths(projectId, agent, intentId) {
+        try {
+            const changes = listWorktreeChangesStrict(repoRoot());
+            if (changes.length === 0)
+                return [];
+            const held = (await api("GET", `/leases?project_id=${projectId}`));
+            const mine = held
+                .filter((l) => l.agent_id === agent && l.intent_id === intentId)
+                .flatMap((l) => [...(l.paths ?? []), ...(l.secondary_paths ?? [])]);
+            if (mine.length === 0)
+                return [];
+            return [
+                ...new Set(changes
+                    .filter((c) => !DEFAULT_IGNORES.some((i) => i.endsWith("/") ? c.path.startsWith(i) : c.path === i))
+                    .filter((c) => mine.some((p) => (isGlob(p) ? globMatches(p, c.path) : pathsOverlap(p, c.path))))
+                    .map((c) => c.path)),
+            ];
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`Refusing to complete ${intentId}: Sync could not verify that its leased paths are committed. ` +
+                `Restore git/worktree access and retry. (${detail})`);
+        }
+    }
+    mcp.registerTool("intent_complete", { description: "Mark your declared intent as landed. Commit first, then call AFTER surface_delta_publish and BEFORE lease_release. Completion fails while any leased path is uncommitted, when git cannot verify the checkout, or when blocking contract breaks remain. A successful completion reports a non-blocking warning when HEAD is ahead of its configured upstream or upstream status cannot be verified.", inputSchema: z.object({ intent_id: z.string() }) }, async (args, extra) => {
+        const { intent_id } = args;
+        const { projectId, agentId } = await ensureAgent(extra);
+        const dirty = await dirtyLeasedPaths(projectId, agentId, intent_id);
+        const completed = await api("POST", `/intents/${intent_id}/complete`, {
+            dirty_paths: dirty,
+        });
+        return text({ ...completed, ...upstreamLandingReport(repoRoot()) });
+    });
+    mcp.registerTool("intent_withdraw", { description: "Withdraw an intent you declared and are not going to act on — after a conflict or escalate verdict, or when you change plan. Releases any leases it holds. Do this instead of walking away: an intent left open is what the arbiter compares the NEXT agent's declaration against, so abandoning one silently blocks whoever declares near your paths later. Only your own intents, and only before they complete.", inputSchema: z.object({
+            intent_id: z.string(),
+            reason: z.string().optional(),
+        }) }, async (args, extra) => {
+        const { agentId } = await ensureAgent(extra);
+        return text(await api("POST", `/intents/${args.intent_id}/withdraw`, {
+            agent_id: agentId,
+            reason: args.reason,
+        }));
+    });
+    mcp.registerTool("intent_list_active", { description: "List every intent currently in flight across all agents. Use to understand what others are doing before planning. Call site reports are summarised to their file set and counts; intent_get returns one intent with every call site quoted.", inputSchema: z.object({}) }, async (_args, extra) => {
+        const { projectId } = await ensureAgent(extra);
+        // One call for both statuses: GET /intents accepts a comma-separated
+        // status list, so this used to be two sequential round trips for what
+        // is really one question ("what's in flight").
+        const inFlight = await api("GET", `/intents?project_id=${projectId}&status=active,declared`);
+        return text(inFlight.map(compactIntent));
+    });
+    mcp.registerTool("intent_get", { description: "Read one intent in full, including every call site behind each declared interface change. intent_list_active summarises those to a file set; call this when you need the exact lines — for example before changing a symbol another agent has already declared.", inputSchema: z.object({ intent_id: z.string() }) }, async (args, extra) => {
+        const { intent_id } = args;
+        await ensureAgent(extra);
+        return text(await api("GET", `/intents/${intent_id}`));
+    });
+    mcp.registerTool("lease_acquire", { description: "Acquire an advisory lease on the paths from your declared intent. If denied, the response names the blocking agent's intent — take the partial grant, re-scope, or claim a different task. NEVER edit a path you were denied.", inputSchema: z.object({
+            intent_id: z.string(),
+            paths: z.array(z.string()).optional(),
+            ttl_seconds: z.number().optional(),
+            idempotency_key: IDEMPOTENCY_KEY,
+        }) }, async (args, extra) => {
+        await ensureAgent(extra);
+        return text(compactLeaseGrant(await api("POST", "/leases", args)));
+    });
+    mcp.registerTool("lease_renew", { description: "Renew a held lease, optionally choosing a fresh TTL. Leases expire; call this for long tasks (or rely on heartbeats).", inputSchema: z.object({ lease_id: z.string(), ttl_seconds: z.number().positive().optional() }) }, async (args, extra) => {
+        const { lease_id, ttl_seconds } = args;
+        await ensureAgent(extra);
+        return text(await api("POST", `/leases/${lease_id}/renew`, {
+            ...(ttl_seconds === undefined ? {} : { ttl_seconds }),
+        }));
+    });
+    mcp.registerTool("lease_release", { description: "Release your lease when the work is done. Call AFTER surface_delta_publish and intent_complete. Do not release while leaving known-broken call sites behind.", inputSchema: z.object({ lease_id: z.string() }) }, async (args, extra) => {
+        const { lease_id } = args;
+        await ensureAgent(extra);
+        return text(await api("POST", `/leases/${lease_id}/release`, {}));
+    });
+    mcp.registerTool("lease_list", { description: "List leases currently held on a project, so you can see what is taken before planning.", inputSchema: z.object({}) }, async (_args, extra) => {
+        const { projectId } = await ensureAgent(extra);
+        return text(await api("GET", `/leases?project_id=${projectId}`));
+    });
+    mcp.registerTool("task_find_work", { description: "Ask the coordinator for the best next task instead of inventing one — prefers tasks whose file footprint avoids currently-held leases. Call when idle or after your task completes.", inputSchema: z.object({}) }, async (_args, extra) => {
+        const { agentId } = await ensureAgent(extra);
+        return text(await api("POST", "/tasks/find-work", { agent_id: agentId }));
+    });
+    mcp.registerTool("task_claim", { description: "Atomically claim a task. Two agents cannot claim the same one. If claimed=false, check held_by_you first: true means you already hold it (your earlier claim landed and you are retrying), so carry on with the work. Only call task_find_work again when held_by_you is false.", inputSchema: z.object({ task_id: z.string() }) }, async (args, extra) => {
+        const { task_id } = args;
+        const { agentId } = await ensureAgent(extra);
+        return text(await api("POST", `/tasks/${task_id}/claim`, { agent_id: agentId }));
+    });
+    mcp.registerTool("auto_mode_next", { description: "Continue an operator-enabled Auto mode loop safely. Call this after completing and releasing the current task, before ending your turn. It checks this session's Auto mode switch, finds eligible board work, and atomically claims one item. If continue=true, work that returned task through the normal intent/lease/commit/surface-delta/completion protocol, then call auto_mode_next again. Stop and report the returned reason when continue=false; never bypass a human decision, permission boundary, or protocol gate.", inputSchema: z.object({}) }, async (_args, extra) => {
+        const { agentId } = await ensureAgent(extra);
+        const mode = await api("GET", `/agents/${agentId}/auto-mode`);
+        if (!mode.enabled || !mode.connected) {
+            return text({ continue: false, reason: mode.connected ? "auto_mode_off" : "agent_disconnected" });
+        }
+        // A claim is the concurrency boundary. If another agent wins between
+        // find-work and claim, retry a bounded number of times rather than
+        // handing the model work it does not own or looping forever.
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const found = await api("POST", "/tasks/find-work", { agent_id: agentId });
+            if (!found.task)
+                return text({ continue: false, reason: "no_eligible_work" });
+            const claim = await api("POST", `/tasks/${found.task.id}/claim`, { agent_id: agentId });
+            if (claim.claimed || claim.held_by_you) {
+                return text({
+                    continue: true,
+                    task: claim.task ?? found.task,
+                    estimated_lease_collisions: found.estimated_lease_collisions,
+                    resumed_existing_claim: Boolean(claim.held_by_you),
+                });
+            }
+        }
+        return text({ continue: false, reason: "claim_contention", retry_later: true });
+    });
+    mcp.registerTool("task_create", { description: "Add a task to the shared DAG — e.g. follow-up work you discovered but should not do inside your current lease (fixing another agent's call sites, deferred refactors).", inputSchema: z.object({
+            title: z.string(),
+            detail: z.string().optional(),
+            depends_on: z.array(z.string()).default([]),
+            estimated_paths: z.array(z.string()).default([]),
+            idempotency_key: IDEMPOTENCY_KEY,
+        }) }, async (args, extra) => {
+        const { projectId, agentId } = await ensureAgent(extra);
+        return text(await api("POST", "/tasks", { project_id: projectId, created_by: agentId, ...args }));
+    });
+    mcp.registerTool("task_complete", { description: "Mark a claimed task as completed so dependent tasks unblock.", inputSchema: z.object({ task_id: z.string() }) }, async (args, extra) => {
+        const { task_id } = args;
+        await ensureAgent(extra);
+        return text(await api("POST", `/tasks/${task_id}/complete`, {}));
+    });
+    // ---------------------------------------------------------------------------
+    // M9b — the board (§9). Project-scoped: a board item belongs to one project,
+    // and the project comes from this adapter's own registration rather than from
+    // a caller-supplied id it could get wrong.
+    // ---------------------------------------------------------------------------
+    const boardStatusEnum = z.enum([...BOARD_STATUSES]);
+    const boardKindEnum = z.enum([...BOARD_KINDS]);
+    const boardPrincipal = z.object({
+        type: z.enum(["vendor", "account"]),
+        id: z.string(),
+    });
+    mcp.registerTool("board_list", { description: "List board items for this project — phases, work items, debt, decisions and findings. Returns summaries (title, status, owners, an excerpt) rather than full bodies, so listing a large board stays cheap. Filter by status or kind; call board_get for the body of one item.", inputSchema: z.object({
+            status: boardStatusEnum.optional().describe("Only items in this status."),
+            kind: boardKindEnum.optional().describe("Only items of this kind."),
+            parent_id: z.string().optional().describe("Only this item's children. Pass 'root' for top-level items only."),
+            flag: z
+                .string()
+                .optional()
+                .describe("Only items carrying this flag. Matched whole, not as a prefix — 'token' does not match 'token saver'."),
+            q: z
+                .string()
+                .optional()
+                .describe("Substring search over title and body, case-insensitive, title matches ranked first. Prefer this over listing and reading: it is how you find one item without paying for the rest. Searching includes completed items by default, because that is where finished decisions are recorded."),
+            include_done: z
+                .boolean()
+                .optional()
+                .describe("Include completed and abandoned items. Defaults to false for a plain listing — you are usually deciding what to work on next — and to true when q is given. An explicit status filter overrides this."),
+            limit: z.number().int().min(1).max(500).optional(),
+            full: z
+                .boolean()
+                .default(false)
+                .describe("Return complete bodies instead of excerpts. Expensive on a large board — leave false unless you need every body at once."),
+        }) }, async (args, extra) => {
+        const { status, kind, parent_id, flag, q, include_done, limit, full } = args;
+        const { projectId } = await ensureAgent(extra);
+        const params = new URLSearchParams();
+        if (status)
+            params.set("status", status);
+        if (kind)
+            params.set("kind", kind);
+        if (parent_id)
+            params.set("parent", parent_id);
+        if (flag)
+            params.set("flag", flag);
+        if (q)
+            params.set("q", q);
+        // The HTTP route defaults to including finished work, because the web
+        // dashboard renders its history from the same endpoint. An agent
+        // listing the board is choosing what to do next, so the tool opts out
+        // unless it is searching — a search is usually looking for a decision
+        // that has already been made.
+        const wantDone = include_done ?? Boolean(q);
+        params.set("include_done", wantDone ? "1" : "0");
+        if (limit !== undefined)
+            params.set("limit", String(limit));
+        if (full)
+            params.set("full", "1");
+        const suffix = params.toString() ? `?${params}` : "";
+        const board = await api("GET", `/projects/${projectId}/board${suffix}`);
+        return text(Array.isArray(board?.items)
+            ? { ...board, items: board.items.map(compactBoardItem) }
+            : board);
+    });
+    mcp.registerTool("board_get", { description: "Read one board item in full, including its markdown body and its `etag`. You must pass that etag to board_update — it is what proves you edited the version you actually read.", inputSchema: z.object({ item_id: z.string() }) }, async (args, extra) => {
+        const { item_id } = args;
+        const { projectId } = await ensureAgent(extra);
+        return text(await api("GET", `/projects/${projectId}/board/${item_id}`));
+    });
+    mcp.registerTool("board_create", { description: "Add an item to the project board: a work item, a piece of debt, a decision that needs making, or a finding worth keeping. Use this for durable project state — task_create is for the coordination DAG you claim work from.", inputSchema: z.object({
+            title: z.string(),
+            detail: z.string().optional().describe("Markdown body."),
+            kind: boardKindEnum.default("item"),
+            status: boardStatusEnum.default("available"),
+            owners: z
+                .array(boardPrincipal)
+                .default([])
+                .describe("Typed principals, e.g. [{type:'vendor',id:'claude_code'},{type:'account',id:'acc_…'}]. Joint ownership is normal."),
+            depends_on: z.array(z.string()).default([]),
+            estimated_paths: z.array(z.string()).default([]),
+            flags: z
+                .array(z.string())
+                .optional()
+                .describe("Short labels for cross-cutting concerns that are not status, kind, or owner — e.g. [\"token saver\"]. Canonicalised to lowercase with collapsed whitespace; letters, digits, spaces and _ . / - only, starting with a letter or digit. Max 16 flags, 48 characters each."),
+            parent_id: z.string().optional().describe("Nest under this item — e.g. the phase this step belongs to."),
+            position: z.number().int().optional().describe("Explicit order among siblings. Omit for unordered."),
+        }) }, async (args, extra) => {
+        const { projectId, agentId } = await ensureAgent(extra);
+        return text(boardWriteReceipt(await api("POST", `/projects/${projectId}/board`, { agent_id: agentId, ...args })));
+    });
+    mcp.registerTool("board_update", { description: "Update a board item. `expected_version` is mandatory and must be the `version` you read from board_get: if anyone changed the item in between you get a 412 with the current version, and you must re-read and reapply rather than overwrite. Send only the fields you are changing.", inputSchema: z.object({
+            item_id: z.string(),
+            expected_version: z
+                .number()
+                .int()
+                .describe("The version you read. A stale value is refused with 412 rather than silently overwriting."),
+            title: z.string().optional(),
+            detail: z.string().nullable().optional(),
+            kind: boardKindEnum.optional(),
+            status: boardStatusEnum.optional(),
+            owners: z.array(boardPrincipal).optional(),
+            depends_on: z.array(z.string()).optional(),
+            estimated_paths: z.array(z.string()).optional(),
+            flags: z
+                .array(z.string())
+                .optional()
+                .describe("Short labels for cross-cutting concerns that are not status, kind, or owner — e.g. [\"token saver\"]. Canonicalised to lowercase with collapsed whitespace; letters, digits, spaces and _ . / - only, starting with a letter or digit. Max 16 flags, 48 characters each." + " Replaces the whole list; pass [] to clear."),
+            parent_id: z.string().nullable().optional().describe("Re-parent, or null to move to the top level. A cycle is refused."),
+            position: z.number().int().nullable().optional(),
+        }) }, async (args, extra) => {
+        const { item_id, expected_version, ...patch } = args;
+        const { projectId, agentId } = await ensureAgent(extra);
+        // Only send keys the caller actually set: the route treats key *presence*
+        // as "change this field", so forwarding undefined would blank things.
+        const body = { agent_id: agentId };
+        for (const [key, value] of Object.entries(patch)) {
+            if (value !== undefined)
+                body[key] = value;
+        }
+        return text(boardWriteReceipt(await api("PATCH", `/projects/${projectId}/board/${item_id}`, body, {
+            "if-match": `"${expected_version}"`,
+        })));
+    });
+    mcp.registerTool("board_history", { description: "Read the revision history of a board item — every version, who changed it, when, and a complete snapshot of what it said at the time. Use this to answer 'what did this say when that decision was made' rather than guessing from the current text.", inputSchema: z.object({ item_id: z.string(), limit: z.number().int().min(1).max(500).optional() }) }, async (args, extra) => {
+        const { item_id, limit } = args;
+        const { projectId } = await ensureAgent(extra);
+        const suffix = limit === undefined ? "" : `?limit=${limit}`;
+        return text(await api("GET", `/projects/${projectId}/board/${item_id}/history${suffix}`));
+    });
+    mcp.registerTool("document_list", { description: "List reference documents uploaded to this project's Organization page — specs, style guides, and other material every agent on the project can read. Returns metadata only (filename, content type, size, who uploaded it, when); call document_read for one file's actual content.", inputSchema: z.object({}) }, async (_args, extra) => {
+        const { projectId } = await ensureAgent(extra);
+        return text(await api("GET", `/projects/${projectId}/documents`));
+    });
+    mcp.registerTool("document_read", { description: "Read one uploaded reference document's content, by id from document_list. Text-like content (markdown, plain text, JSON, code, etc.) is returned inline; anything else is reported by name, type and size only — a binary blob is not useful as tool output.", inputSchema: z.object({ document_id: z.string() }) }, async (args, extra) => {
+        const { document_id } = args;
+        const { projectId } = await ensureAgent(extra);
+        const { contentType, buffer } = await apiRaw(`/projects/${projectId}/documents/${document_id}`);
+        const isText = /^text\//.test(contentType) || /json|xml|yaml|markdown|csv/.test(contentType);
+        return text(isText
+            ? { content_type: contentType, size_bytes: buffer.length, content: buffer.toString("utf8") }
+            : { content_type: contentType, size_bytes: buffer.length, content: null, note: "Binary content is not returned as tool text." });
+    });
+    mcp.registerTool("surface_delta_publish", { description: "Publish every exported symbol, route, schema, config key, env var, or dependency you changed — BEFORE releasing your lease. Other agents depend on this to avoid building against a stale picture of your code. Changes of kind signature/removed trigger contract verification against other agents' in-flight work.", inputSchema: z.object({
+            intent_id: z.string(),
+            changes: z.array(z.object({
+                kind: z.string(),
+                path: z.string(),
+                name: z.string(),
+                change: z.string(),
+                before: z.string().nullable().default(null),
+                after: z.string().nullable().default(null),
+            })),
+            commit_sha: z.string().optional(),
+        }) }, async (args, extra) => {
+        await ensureAgent(extra);
+        const changes = withLocalCallSites(args.changes, ["signature", "removed"]);
+        return text(await api("POST", "/surface-deltas", { ...args, changes }));
+    });
+    mcp.registerTool("surface_delta_recent", { description: "List surface deltas other agents have published (optionally since an ISO timestamp). Check before building against any interface you have not read this session.", inputSchema: z.object({ since: z.string().optional() }) }, async (args, extra) => {
+        const { since } = args;
+        const { projectId } = await ensureAgent(extra);
+        const q = since ? `&since=${encodeURIComponent(since)}` : "";
+        return text(await api("GET", `/surface-deltas?project_id=${projectId}${q}`));
+    });
+    mcp.registerTool("blast_radius_preview", { description: "Preview the cost of an interface change while planning, before committing to an intent: how many call sites, and whose leases they sit in. Cheap — call freely.", inputSchema: z.object({ interfaces_touched: z.array(interfaceSchema), paths: z.array(z.string()).default([]) }) }, async (args, extra) => {
+        const { agentId } = await ensureAgent(extra);
+        const interfaces = withLocalCallSites(args.interfaces_touched);
+        // A declare with no lease acquisition is a preview; abandon it right after.
+        const declared = await api("POST", "/intents", {
+            agent_id: agentId,
+            summary: "[blast radius preview]",
+            paths: args.paths,
+            interfaces_touched: interfaces,
+        });
+        return text({ call_sites: declared.blast_radius, verdict: declared.blast_radius?.verdict });
+    });
+    mcp.registerTool("contract_acknowledge", { description: "Acknowledge a contract.broken event AFTER fixing the named call sites. Blocking-severity breaks prevent intent_complete until acknowledged.", inputSchema: z.object({ break_id: z.string(), resolution: z.string().default("fixed") }) }, async (args, extra) => {
+        const { break_id, resolution } = args;
+        await ensureAgent(extra);
+        return text(await api("POST", `/contract-breaks/${break_id}/ack`, { resolution }));
+    });
+    mcp.registerTool("contract_breaks_pending", { description: "List unacknowledged contract breaks targeted at YOU — call sites another agent's change broke in your in-flight work. Fix these before completing your intent.", inputSchema: z.object({}) }, async (_args, extra) => {
+        const { projectId, agentId } = await ensureAgent(extra);
+        return text(await api("GET", `/contract-breaks?project_id=${projectId}&target_agent=${agentId}&open=1`));
+    });
+    // ---------------------------------------------------------------------------
+    // Local graph tools
+    //
+    // These answer from the index built beside the checkout, per ADR 002 and
+    // inv_01KZWPAM9QCZ0DD7789N55X647: parsing and traversal happen here and the
+    // server never sees code. Both are read-only, take no lease, and cost one
+    // index build per process, cached thereafter.
+    //
+    // They exist because an agent currently answers "what does this change reach"
+    // by grepping and then opening every file that matched. The graph answers from
+    // bindings — a call resolves only where the name is defined in the calling
+    // file or imported into it — and states what it could not see.
+    // ---------------------------------------------------------------------------
+    /**
+     * One index per process, keyed by root. Rebuilding per call would be absurd
+     * — and so, at N agent CLIs sharing one checkout, is N processes each
+     * holding their own copy. `KEEL_MCP_DAEMON=1` moves that copy into one
+     * shared background process (daemon.ts); `daemonEnabled()` off (the
+     * default) or the daemon being unreachable both fall through to exactly
+     * this process's own build, unchanged from before daemon mode existed.
+     */
+    let graphCache = null;
+    async function localGraph() {
+        const root = repoRoot();
+        if (graphCache && graphCache.root === root)
+            return graphCache;
+        graphCache = await buildLocalGraph(root);
+        return graphCache;
+    }
+    /**
+     * Answer one local-graph operation from the daemon if one is reachable and
+     * on-protocol; otherwise from this process's own (possibly newly built)
+     * copy. Every caller below is the same three lines: try the daemon, spawn
+     * one for next time if it wasn't there, fall back.
+     */
+    async function viaDaemonOrLocal(op, args, runLocal) {
+        const root = repoRoot();
+        const fromDaemon = await tryDaemon(root, op, args);
+        if (fromDaemon !== null)
+            return fromDaemon;
+        ensureDaemonSpawned(root);
+        return runLocal(await localGraph());
+    }
+    const handleImpact = async (args, _extra) => {
+        const impactArgs = { paths: args.paths, max_distance: args.max_distance };
+        return text(await viaDaemonOrLocal("impact", impactArgs, (local) => runImpact(local, impactArgs)));
+    };
+    const impactDesc = "Which files must you edit if you change these? Returns affected paths each with a CHECKABLE reason (\"handler() calls query() at line 41\"), plus what the graph could not see. Resolved from real import and call bindings rather than name matching, so a comment mentioning a symbol never appears. Read-only, no lease. Prefer this over grepping for callers.";
+    const impactSchema = z.object({
+        paths: z.array(z.string()).describe("Repo-root-relative paths you intend to change."),
+        max_distance: z
+            .number()
+            .int()
+            .min(1)
+            .max(6)
+            .default(1)
+            .describe("1 (default) = files that directly reference these, which is what must be edited. " +
+            "Higher follows the chain further: 2 includes callers of those callers, and so on. " +
+            "Raise it only to ask what might behave differently downstream, not what must change."),
+    });
+    mcp.registerTool("sync_impact", { description: impactDesc, inputSchema: impactSchema }, handleImpact);
+    const handleContextCard = async (args, _extra) => {
+        const cardArgs = { path: args.path, max_callers: args.max_callers, include_skeleton: args.include_skeleton };
+        return text(await viaDaemonOrLocal("context_card", cardArgs, (local) => runContextCard(local, cardArgs)));
+    };
+    const contextCardDesc = "Everything worth knowing before editing one file: exports, imports, callers with reasons, callees, and a signature skeleton, in one bounded response instead of a read-then-grep-then-read loop. Local only — the card is never transmitted to the server. Read-only, no lease.";
+    const contextCardSchema = z.object({
+        path: z.string().describe("Repo-root-relative path of the file you are about to edit."),
+        max_callers: z.number().int().min(1).max(100).default(20),
+        include_skeleton: z.boolean().default(true),
+    });
+    mcp.registerTool("sync_context_card", { description: contextCardDesc, inputSchema: contextCardSchema }, handleContextCard);
+    const handleRetrieve = async (args, extra) => {
+        // Identity and lease state are per-agent and never the shared daemon's to
+        // know — resolved here, client-side, exactly as before daemon mode, and
+        // handed to whichever side (daemon or local) actually runs the query.
+        const { projectId, agentId } = await ensureAgent(extra);
+        const leases = (await api("GET", `/leases?project_id=${projectId}`));
+        const leasedPaths = leases
+            .filter((lease) => lease.agent_id !== agentId)
+            .flatMap((lease) => [...(lease.paths ?? []), ...(lease.secondary_paths ?? [])]);
+        const retrieveArgs = {
+            question: args.question,
+            limit: args.limit,
+            offset: args.offset,
+            exclude_paths: args.exclude_paths,
+            refinement: args.refinement,
+            leasedPaths,
+        };
+        return text(await viaDaemonOrLocal("retrieve", retrieveArgs, (local) => runRetrieve(local, retrieveArgs)));
+    };
+    const retrieveDesc = "Search local derived retrieval pages; supports stateless follow-up refinement, pagination, and exclusions, and returns ranked files, quoted facts, reasons, leg ranks, agreement, continuation metadata, and lease warnings. Source pages never cross the coordination server.";
+    const retrieveSchema = z.object({
+        question: z.string().min(1),
+        limit: z.number().int().min(1).max(50).default(10),
+        offset: z.number().int().min(0).max(100).default(0),
+        exclude_paths: z.array(z.string().min(1)).max(100).default([]),
+        refinement: z.string().max(2000).optional(),
+    });
+    mcp.registerTool("sync_retrieve", { description: retrieveDesc, inputSchema: retrieveSchema }, handleRetrieve);
+    return mcp;
+}
+if (TEST_IMPORT_MODE) {
+    // Imported by focused unit tests; registering tools must not start a stdio
+    // transport or keep the test process alive.
+}
+else if (SETUP_MODE) {
+    await runSetup(process.argv.slice(3));
+}
+else if (LOGIN_MODE) {
+    await runLogin(process.argv.slice(3));
+}
+else {
+    // A piped stdin data listener is not a referenced event-loop handle on every
+    // supported Node build. Without an explicit lifetime handle the adapter can
+    // connect and then exit(0) before Claude Code sends `initialize`, surfacing as
+    // the opaque MCP -32000 "Connection closed" error. Keep the process alive
+    // until its client closes stdin; do not leave a heartbeat timer behind after
+    // the transport is gone.
+    const stdioLifetime = setInterval(() => { }, 24 * 60 * 60 * 1000);
+    const endStdioLifetime = () => clearInterval(stdioLifetime);
+    process.stdin.resume();
+    process.stdin.once("end", endStdioLifetime);
+    try {
+        serveStdio((requestContext) => createSyncMcpServer(requestContext));
+    }
+    catch (error) {
+        endStdioLifetime();
+        throw error;
+    }
+}