mnemos-capture 1.6.1 → 1.8.0

package/dist/cli/git-hook.js

@@ -0,0 +1,170 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+import { execFileSync } from "child_process";
+import { callMcp, initializeMcp } from "./hooks.js";
+import { syncCodeMap } from "./code-map.js";
+import { currentRepo } from "./session-start.js";
+import { getCurrentVersion } from "./version-check.js";
+/**
+ * Links commits to the captures they apply, with any coding agent or none.
+ * The commit message carries one `xkg-capture: <filename>` trailer per
+ * capture; a git post-commit hook reports each one to apply_capture with the
+ * commit sha and the repo. The server counts a capture and commit once, so an
+ * agent that also calls apply_capture itself does not double count. A
+ * `git revert` of such a commit is reported as reverted, with no agent.
+ *
+ * The same hooks, plus post-merge and post-checkout, keep the repo's code map
+ * (code-map.ts) fresh, so every agent gets it through git alone.
+ */
+const PACKAGE = "@xmu-labs/xkg";
+const MARKER = "# xkg";
+/** The MCP client name the hook's reports carry, so the server counts them by agent. */
+export const HOOK_CLIENT = "xkg-git-hook";
+function git(cwd, ...args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+/** `xkg-capture` values from the commit message's trailer block only (as git parses it), once each. */
+export function captureTrailers(message) {
+    let trailers;
+    try {
+        trailers = execFileSync("git", ["interpret-trailers", "--parse"], { input: message, encoding: "utf-8", timeout: 5000 });
+    }
+    catch {
+        return [];
+    }
+    const found = [...trailers.matchAll(/^xkg-capture:[ \t]*(\S+)[ \t]*$/gim)].map((m) => m[1]);
+    return [...new Set(found)];
+}
+/** Writes `line` as xkg's only line in a shell hook, keeping the user's own lines. */
+function installHookLine(hooksDir, name, line, isOurs) {
+    const path = join(hooksDir, name);
+    const existing = existsSync(path) ? readFileSync(path, "utf-8") : "#!/bin/sh\n";
+    if (!/^#!\s*\S*\b(?:env\s+)?(?:sh|bash|zsh|dash|ksh)\b/.test(existing.split("\n")[0] ?? "")) {
+        throw new Error(`${path} is not a shell script; add this line to it yourself:\n${line}`);
+    }
+    const kept = existing.split("\n").filter((l) => !(l.endsWith(MARKER) && isOurs(l)));
+    const body = kept.join("\n").replace(/\n*$/, "\n");
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(path, `${body}${line}\n`);
+    chmodSync(path, 0o755);
+    return path;
+}
+function hooksDirOf(cwd) {
+    return resolve(cwd, git(cwd, "rev-parse", "--git-path", "hooks"));
+}
+function runner(version) {
+    return `npx -y ${PACKAGE}@${version === "0.0.0" ? "latest" : version}`;
+}
+/**
+ * Installs or updates xkg's line in the repo's post-commit hook and returns the hook's path.
+ * The line holds no credential (the hooks directory may be tracked); the key comes from
+ * `xkg config` at run time. It reads the sha before going to the background, so a quick
+ * next commit can't be reported in its place. It runs the CLI version that installed it, so
+ * a new release reaches a repo only when the hook is installed again.
+ */
+export function installPostCommitHook(cwd = process.cwd(), version = getCurrentVersion()) {
+    const line = `xkg_sha=$(git rev-parse HEAD); ${runner(version)} post-commit --sha "$xkg_sha" >/dev/null 2>&1 & ${MARKER}`;
+    return installHookLine(hooksDirOf(cwd), "post-commit", line, (l) => l.includes(" post-commit "));
+}
+/** Where an agent writes a handoff spec in the code repo. Kept out of git locally, never committed. */
+const LOCAL_DIR = ".xkg/";
+/** Adds `.xkg/` to the repo's local exclude file (not .gitignore, which is shared), once. */
+export function excludeLocalDir(cwd) {
+    const path = resolve(cwd, git(cwd, "rev-parse", "--git-path", "info/exclude"));
+    const current = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    if (current.split("\n").some((l) => l.trim() === LOCAL_DIR || l.trim() === "/.xkg/"))
+        return;
+    mkdirSync(resolve(path, ".."), { recursive: true });
+    writeFileSync(path, `${current.replace(/\n*$/, current ? "\n" : "")}${LOCAL_DIR}\n`);
+}
+/**
+ * Installs the post-commit hook, plus post-merge and post-checkout lines that sync the
+ * code map after a pull or a branch switch (not after a checkout of single files),
+ * and keeps `.xkg/` out of git. Returns the three hooks' paths.
+ */
+export function installGitHooks(cwd = process.cwd(), version = getCurrentVersion()) {
+    excludeLocalDir(cwd);
+    const commit = installPostCommitHook(cwd, version);
+    const dir = hooksDirOf(cwd);
+    const sync = `${runner(version)} sync-map >/dev/null 2>&1 & ${MARKER}`;
+    const isSync = (l) => l.includes(" sync-map ");
+    return [
+        commit,
+        installHookLine(dir, "post-merge", sync, isSync),
+        installHookLine(dir, "post-checkout", `[ "$3" = "1" ] && ${sync}`, isSync),
+    ];
+}
+/**
+ * Runs after each commit: reports every `xkg-capture:` trailer of `sha` to apply_capture
+ * (and, for a revert, the trailers of the commit it undid), then syncs the code map if it
+ * changed. Never throws.
+ */
+export async function postCommit(apiKey, sha, cwd = process.cwd()) {
+    // The map first: the server keeps only an apply's files that are in it, so a file the commit added must be there
+    await syncCodeMap(apiKey, cwd);
+    await reportTrailers(apiKey, sha, cwd);
+}
+/** Changed files sent per report; the server keeps those in the repo's code map. */
+const MAX_FILES = 20;
+/** The commit a `git revert` undid, from git's own message ("This reverts commit <sha>."). */
+export function revertedCommit(message) {
+    return message.match(/^This reverts commit ([0-9a-f]{7,40})\b/m)?.[1] ?? null;
+}
+async function reportTrailers(apiKey, sha, cwd) {
+    try {
+        const full = git(cwd, "rev-parse", "--verify", `${sha}^{commit}`);
+        const message = git(cwd, "log", "-1", "--format=%B", full);
+        const repo = currentRepo(cwd);
+        const inRepo = repo ? { repo } : {};
+        const reports = [];
+        const trailers = captureTrailers(message);
+        if (trailers.length) {
+            // NUL-separated, so paths come as they are and not as git quotes them ("caf\303\251.ts")
+            const files = git(cwd, "diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "-z", full).split("\0").filter(Boolean);
+            const target = files.slice(0, 5).join(", ") + (files.length > 5 ? ` and ${files.length - 5} more` : "");
+            for (const filename of trailers)
+                reports.push({ filename, commit_sha: full, target_file: target, files: files.slice(0, MAX_FILES), ...inRepo });
+        }
+        // A revert of a commit that applied captures undoes those applies
+        const undone = revertedCommit(message);
+        if (undone) {
+            try {
+                const original = git(cwd, "rev-parse", "--verify", `${undone}^{commit}`);
+                for (const filename of captureTrailers(git(cwd, "log", "-1", "--format=%B", original))) {
+                    reports.push({ filename, commit_sha: original, outcome: "reverted", ...inRepo });
+                }
+            }
+            catch {
+                // The reverted commit isn't in this clone
+            }
+        }
+        if (reports.length === 0)
+            return;
+        // One session for all of this commit's reports. Without one they still count, as "unknown".
+        const session = await initializeMcp(apiKey, HOOK_CLIENT, 10000)
+            .then((res) => (res.ok ? res.headers.get("mcp-session-id") : null))
+            .catch(() => null);
+        for (const args of reports) {
+            await callMcp(apiKey, "apply_capture", args, 10000, session).catch(() => null);
+        }
+    }
+    catch {
+        // Never disturb a commit
+    }
+}
+/** Checks that the hook can reach xkg with this key. Reports no capture. */
+export async function checkHookConnection(apiKey) {
+    let res;
+    try {
+        res = await initializeMcp(apiKey, HOOK_CLIENT, 10000);
+    }
+    catch (err) {
+        return { ok: false, reason: `Could not reach xkg: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (res.status === 401) {
+        return { ok: false, reason: `xkg rejected the API key (HTTP 401). Run setup-git-hook again with a current key.` };
+    }
+    if (!res.ok)
+        return { ok: false, reason: `xkg answered HTTP ${res.status}.` };
+    return { ok: true };
+}

package/dist/cli/hooks.js

@@ -102,8 +102,12 @@ export function setupHooks(apiKey, opts = {}) {
     // skipIfExists (serve-mcp auto-install): preserve user-configured hooks but
     // silently migrate hooks that pin a version or use the old package name.
     if (existingCmd && opts.skipIfExists) {
-        if (isCurrentHook(existingCmd))
+        if (isCurrentHook(existingCmd)) {
+            // A vault hook left under the old PreToolCall key never ran; move it.
+            if (findVaultHook(hooks.PreToolCall ?? []))
+                setupPreToolHook(apiKey, { silent: opts.silent, skipIfExists: true });
             return;
+        }
         // Migration: preserve the existing --briefing flag when upgrading to @latest
         opts = { ...opts, briefing: existingCmd.includes("--briefing") };
     }
@@ -130,41 +134,57 @@ export function setupHooks(apiKey, opts = {}) {
             console.log("At the start of each Claude Code session you'll see your inbox count.");
         }
     }
-    if (opts.vault) {
+    if (opts.vault || findVaultHook(hooks.PreToolCall ?? [])) {
         setupPreToolHook(apiKey, { silent: opts.silent, skipIfExists: opts.skipIfExists });
     }
 }
-export function setupPreToolHook(apiKey, opts = {}) {
-    const settings = readSettings();
-    const hooks = settings.hooks ?? {};
-    const preToolCall = hooks.PreToolCall ?? [];
-    let existingCmd = null;
-    for (const group of preToolCall) {
-        for (const h of group.hooks ?? []) {
-            if (typeof h.command === "string" && isXkgPreToolHook(h.command)) {
-                existingCmd = h.command;
-                break;
-            }
-        }
-        if (existingCmd)
-            break;
-    }
-    if (existingCmd && opts.skipIfExists) {
-        if (isCurrentHook(existingCmd))
-            return;
-    }
-    const command = `npx -y ${PACKAGE}@latest vault-check --key ${apiKey}`;
-    const filtered = preToolCall
+/** Tools whose edits trigger a vault scan. Also the PreToolUse matcher. */
+const EDITING_TOOLS = ["Edit", "Write", "MultiEdit"];
+/** Removes xkg vault hooks from one hook event's groups, dropping groups left empty. */
+function withoutVaultHook(groups) {
+    return groups
         .map((group) => ({
         ...group,
         hooks: (group.hooks ?? []).filter((h) => !(typeof h.command === "string" && isXkgPreToolHook(h.command))),
     }))
         .filter((group) => (group.hooks ?? []).length > 0);
-    filtered.push({ hooks: [{ type: "command", command }] });
-    settings.hooks = { ...hooks, PreToolCall: filtered };
+}
+function findVaultHook(groups) {
+    for (const group of groups) {
+        for (const h of group.hooks ?? []) {
+            if (typeof h.command === "string" && isXkgPreToolHook(h.command))
+                return h.command;
+        }
+    }
+    return null;
+}
+/**
+ * Installs the vault hook on PreToolUse for file edits.
+ *
+ * Earlier versions wrote it under `PreToolCall`, which Claude Code has no such
+ * event for, so it never ran. Any hook left there is moved to PreToolUse.
+ */
+export function setupPreToolHook(apiKey, opts = {}) {
+    const settings = readSettings();
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const legacy = hooks.PreToolCall ?? [];
+    const existingCmd = findVaultHook(preToolUse);
+    if (existingCmd && opts.skipIfExists && isCurrentHook(existingCmd) && !findVaultHook(legacy))
+        return;
+    const command = `npx -y ${PACKAGE}@latest vault-check --key ${apiKey}`;
+    const filtered = withoutVaultHook(preToolUse);
+    filtered.push({ matcher: EDITING_TOOLS.join("|"), hooks: [{ type: "command", command }] });
+    const next = { ...hooks, PreToolUse: filtered };
+    const legacyLeft = withoutVaultHook(legacy);
+    if (legacyLeft.length > 0)
+        next.PreToolCall = legacyLeft;
+    else
+        delete next.PreToolCall;
+    settings.hooks = next;
     writeSettings(settings);
     if (!opts.silent) {
-        console.log("xkg vault hook installed (PreToolCall).");
+        console.log("xkg vault hook installed (PreToolUse).");
         console.log("Your knowledge vault will surface relevant captures as you edit files.");
     }
 }
@@ -203,13 +223,31 @@ function detectProjectContext() {
     // Local agent instructions may contain private maintainer notes; do not upload them.
     return parts.length > 0 ? parts.join("\n\n") : "current project";
 }
-export async function callMcp(apiKey, toolName, toolArgs, timeoutMs = 15000) {
+/**
+ * Opens an MCP session that names the caller, so the server can tell which
+ * agent made the calls on it. Returns the raw reply; callers read the status
+ * or the Mcp-Session-Id header.
+ */
+export async function initializeMcp(apiKey, client, timeoutMs = 15000) {
+    return fetch(HOSTED_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "initialize",
+            params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: client } },
+            id: 1,
+        }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+}
+export async function callMcp(apiKey, toolName, toolArgs, timeoutMs = 15000, sessionId) {
+    const headers = { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` };
+    if (sessionId)
+        headers["Mcp-Session-Id"] = sessionId;
     const res = await fetch(HOSTED_URL, {
         method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${apiKey}`,
-        },
+        headers,
         body: JSON.stringify({
             jsonrpc: "2.0",
             method: "tools/call",
@@ -236,8 +274,7 @@ export async function vaultCheck(apiKey) {
             return;
         }
         // Only act on file-editing tool calls
-        const editingTools = ["Edit", "Write", "MultiEdit"];
-        if (!hookData.tool_name || !editingTools.includes(hookData.tool_name))
+        if (!hookData.tool_name || !EDITING_TOOLS.includes(hookData.tool_name))
             return;
         const filePath = hookData.tool_input?.["file_path"] ??
             hookData.tool_input?.["path"];
@@ -256,7 +293,11 @@ export async function vaultCheck(apiKey) {
         const filenameMatches = text.match(/(?:inbox|applied|archived)\/[\w-]+\.md/g) ?? [];
         if (filenameMatches.length > 0)
             appendSessionSurfaced(filenameMatches);
-        process.stdout.write(text.trim() + "\n");
+        // Plain stdout from a PreToolUse hook only reaches the debug log; the agent
+        // reads it only as additionalContext.
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: text.trim() },
+        }) + "\n");
     }
     catch {
         // Silent fail — never interrupt a tool call
@@ -286,7 +327,9 @@ export async function inboxCheck(apiKey, opts = {}) {
             if (applyNow.length > 0) {
                 const filenames = applyNow.map((s) => `'${s.filename}'`).join(", ");
                 process.stdout.write(`\n---\nxkg: ${applyNow.length} insight${applyNow.length === 1 ? "" : "s"} ready to apply now.\n` +
-                    `Run generate_plan with selected_captures: [${filenames}] to get a full implementation plan.\n`);
+                    `Run generate_plan with selected_captures: [${filenames}] to get a full implementation plan.\n` +
+                    `When you commit a change that applies one, add a trailer per capture to the commit message (e.g. xkg-capture: ${applyNow[0].filename}), ` +
+                    `then call apply_capture with its filename and the commit sha (git rev-parse HEAD). xkg counts each capture and commit once.\n`);
             }
             return;
         }

package/dist/cli/index.js

@@ -41,23 +41,117 @@ async function main() {
         await vaultCheck(apiKey);
         return;
     }
+    if (command === "setup-git-hook") {
+        const { installGitHooks, checkHookConnection } = await import("./git-hook.js");
+        const { syncCodeMap } = await import("./code-map.js");
+        const { readConfig, setConfigField } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const keyArg = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
+        // The hook file may be tracked in git, so the key lives in ~/.xkg/config.json instead
+        if (keyArg)
+            setConfigField("key", keyArg);
+        if (!readConfig().key) {
+            console.error("Usage: npx @xmu-labs/xkg setup-git-hook --key YOUR_API_KEY (run inside the repo)");
+            process.exit(1);
+        }
+        try {
+            const paths = installGitHooks();
+            console.log(`xkg git hooks installed: ${paths.join(", ")}`);
+            console.log("Commits with an `xkg-capture: <filename>` trailer are now recorded as applied.");
+            console.log("Commits, pulls and branch switches keep this repo's code map (file and function names, never code) up to date.");
+        }
+        catch (err) {
+            console.error(err instanceof Error && err.message.includes("not a shell script")
+                ? err.message
+                : "Not a git repository. Run this inside the repo you code in.");
+            process.exit(1);
+        }
+        // The hook runs in the background with its output discarded, so check now that it can report.
+        const check = await checkHookConnection(readConfig().key);
+        if (check.ok) {
+            console.log("Checked: the hook reached xkg with your key.");
+        }
+        else {
+            console.error(`The hook is installed but can't report yet: ${check.reason}`);
+            process.exit(1);
+        }
+        console.log(syncMessage(await syncCodeMap(readConfig().key, process.cwd(), { force: true })));
+        return;
+    }
+    if (command === "map") {
+        const { syncCodeMap } = await import("./code-map.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        if (!apiKey) {
+            console.error("No API key. Pass --key YOUR_KEY or store it: xkg config set key YOUR_KEY");
+            process.exit(1);
+        }
+        const result = await syncCodeMap(apiKey, process.cwd(), { force: true });
+        if (result.status === "synced") {
+            console.log(syncMessage(result));
+        }
+        else {
+            console.error(syncMessage(result));
+            process.exit(1);
+        }
+        return;
+    }
+    if (command === "sync-map") {
+        const { syncCodeMap } = await import("./code-map.js");
+        const { readConfig } = await import("./config.js");
+        const apiKey = readConfig().key;
+        if (!apiKey)
+            process.exit(0); // silent fail in hook context
+        await syncCodeMap(apiKey);
+        return;
+    }
+    if (command === "session-start") {
+        const { sessionStart } = await import("./session-start.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        const agentIdx = args.indexOf("--agent");
+        const agent = agentIdx !== -1 ? args[agentIdx + 1] : undefined;
+        if (!apiKey)
+            return process.exit(0); // silent fail in hook context
+        await sessionStart(apiKey, { agent });
+        return;
+    }
+    if (command === "post-commit") {
+        const { postCommit } = await import("./git-hook.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        const shaIdx = args.indexOf("--sha");
+        const sha = shaIdx !== -1 ? args[shaIdx + 1] : "HEAD";
+        if (!apiKey || !sha)
+            process.exit(0); // silent fail in hook context
+        await postCommit(apiKey, sha);
+        return;
+    }
     if (command === "config") {
         const { runConfigCommand } = await import("./config.js");
         runConfigCommand(args.slice(1));
         return;
     }
-    if (command === "kos") {
-        const { kos } = await import("./kos.js");
+    if (command === "agent" || command === "kos") {
+        const { runAgent, RENAMED_NOTE } = await import("./agent.js");
+        if (command === "kos")
+            console.error(RENAMED_NOTE);
         const { readConfig } = await import("./config.js");
         const keyIdx = args.indexOf("--key");
         const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
-        if (!apiKey) {
+        const specIdx = args.indexOf("--spec");
+        const spec = specIdx !== -1 ? args[specIdx + 1] : undefined;
+        // A local spec is read from disk, so it needs no key
+        if (!apiKey && !spec) {
             console.error("No API key. Pass --key YOUR_KEY or store it: xkg config set key YOUR_KEY");
             process.exit(1);
         }
         const planIdx = args.indexOf("--plan");
         const plan = planIdx !== -1 ? args[planIdx + 1] : undefined;
-        await kos(apiKey, { plan });
+        await runAgent(apiKey ?? "", { plan, spec });
         return;
     }
     // Default: open the hosted app
@@ -75,6 +169,13 @@ async function main() {
     const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
     exec(`${openCmd} ${HOSTED_URL}`);
 }
+function syncMessage(result) {
+    if (result.status === "synced" || result.status === "unchanged")
+        return `Synced ${result.repo}: ${result.files} files`;
+    if (result.status === "skipped")
+        return `Code map not synced: ${result.reason}`;
+    return `Code map not synced${result.repo ? ` for ${result.repo}` : ""}: ${result.reason} Run \`xkg map\` to try again.`;
+}
 function printHelp() {
     console.log(`
   xkg — A knowledge graph for your AI workers
@@ -84,10 +185,16 @@ function printHelp() {
     xkg serve-mcp --key KEY                                    Start the MCP server for your AI worker
     xkg setup-hooks --key KEY                                  Install inbox count hook (fast)
     xkg setup-hooks --key KEY --briefing                       Install full briefing hook (uses LLM)
-    xkg setup-hooks --key KEY --vault                          Install vault hook (PreToolCall)
+    xkg setup-hooks --key KEY --vault                          Install vault hook (PreToolUse)
     xkg setup-hooks --key KEY --briefing --vault               Install both hooks
-    xkg config set agent "claude -p"                           Set which AI worker kos drives
-    xkg kos --key KEY [--plan FILE]                            Implement a plan in an isolated worktree
+    xkg setup-git-hook --key KEY                               Record commits with an xkg-capture trailer and keep the code map fresh (any agent);
+                                                               keeps .xkg/ (handoff specs) out of git
+    xkg map [--key KEY]                                        Send this repo's code map now (file paths and exported names, never code)
+    xkg session-start [--agent NAME]                           For an agent's session-start hook: offer captures waiting for this repo, else new ones
+                                                               (NAME: claude, codex, gemini, copilot, cursor; else plain text)
+    xkg config set agent "claude -p"                           Set which AI worker xkg agent drives
+    xkg agent --key KEY [--plan FILE]                          Implement a plan in an isolated worktree
+    xkg agent --spec PATH                                      Apply a handoff spec your agent wrote (.xkg/handoffs/) in an isolated worktree
     xkg help                                                   Show this help
 
     npx -y @xmu-labs/xkg@latest …                              Same CLI, via the published package
@@ -97,14 +204,15 @@ function printHelp() {
     generate_plan     — Turn selected captures into a full implementation plan
     list_plans        — List or read saved implementation plans
     vault_scan        — Scan all captures for relevance to current activity
+    apply_stats       — Captures applied per week, and how many came with a commit
     curate            — Validate URLs and flag stale captures
 
-  kos — implement plans with your own AI worker (model-agnostic):
+  xkg agent — implement plans with your own AI worker (model-agnostic):
     1. Tell xkg which assistant to drive (once):
          xkg config set agent "claude -p"      # or "codex exec", "aider --yes --message"
     2. Generate a plan via the generate_plan MCP tool.
-    3. Run: xkg kos --key YOUR_KEY
-       kos creates an isolated git worktree, hands the plan to your assistant,
+    3. Run: xkg agent --key YOUR_KEY
+       It creates an isolated git worktree, hands the plan to your assistant,
        and reports the branch + the plan's Verification Checklist when done.
 
   Get started:

package/dist/cli/mcp-server.js

@@ -11,25 +11,8 @@ const pending = new Set();
 function rpcError(id, message) {
     sendMessage({ jsonrpc: "2.0", id, error: { code: -32603, message } });
 }
-async function proxyToHosted(apiKey, msg) {
-    let res;
-    try {
-        res = await fetch(HOSTED_URL, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${apiKey}`,
-            },
-            body: JSON.stringify(msg),
-        });
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : "unknown error";
-        rpcError(msg.id, `Could not reach xkg at ${HOSTED_URL}: ${detail}`);
-        return;
-    }
-    const body = await res.text().catch(() => "");
-    const result = interpretResponse(res.status, res.headers.get("content-type"), body);
+async function proxyToHosted(hosted, msg) {
+    const result = await hosted.send(msg);
     if ("error" in result) {
         rpcError(msg.id, result.error);
         return;
@@ -61,6 +44,47 @@ export function interpretResponse(status, contentType, body) {
         return { error: `xkg returned malformed JSON (HTTP ${status}).` };
     }
 }
+/**
+ * The connection to the hosted server. It keeps the Mcp-Session-Id that
+ * `initialize` returns and sends it on every later call, so the server knows
+ * which agent is calling. When the session expires (404), it replays the
+ * client's `initialize` for a new one and retries the call once.
+ */
+export function createHostedSession(apiKey, url, fetchFn = fetch) {
+    let sessionId = null;
+    let initializeMsg = null;
+    async function post(msg) {
+        const headers = { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` };
+        if (sessionId && msg.method !== "initialize")
+            headers["Mcp-Session-Id"] = sessionId;
+        let res;
+        try {
+            res = await fetchFn(url, { method: "POST", headers, body: JSON.stringify(msg) });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : "unknown error";
+            return { error: `Could not reach xkg at ${url}: ${detail}` };
+        }
+        if (msg.method === "initialize")
+            sessionId = res.headers.get("mcp-session-id") ?? sessionId;
+        const body = await res.text().catch(() => "");
+        return { ...interpretResponse(res.status, res.headers.get("content-type"), body), status: res.status };
+    }
+    return {
+        async send(msg) {
+            if (msg.method === "initialize")
+                initializeMsg = msg;
+            const hadSession = sessionId !== null && msg.method !== "initialize";
+            let { status, ...reply } = await post(msg);
+            if (status === 404 && hadSession && initializeMsg) {
+                sessionId = null;
+                await post(initializeMsg);
+                ({ status, ...reply } = await post(msg));
+            }
+            return reply;
+        },
+    };
+}
 /** Track a proxied request so shutdown can await it. */
 function track(p) {
     pending.add(p);
@@ -98,6 +122,7 @@ export async function serveMcp() {
         // Non-fatal — hook setup should never block the MCP server from starting
     }
     process.stderr.write("xkg MCP server starting (proxying to hosted instance)...\n");
+    const hosted = createHostedSession(apiKey, HOSTED_URL);
     let buffer = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
@@ -113,7 +138,7 @@ export async function serveMcp() {
                 // Handle notifications/initialized locally (no response needed)
                 if (msg.method === "notifications/initialized")
                     continue;
-                track(proxyToHosted(apiKey, msg));
+                track(proxyToHosted(hosted, msg));
             }
             catch {
                 process.stderr.write(`Failed to parse: ${line}\n`);