kith-coord 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.6 — 2026-10-23
+
+- Add optional MCP operation keys with a capability-bound durable result journal in the existing database. Lost replies replay without repeating mutations; concurrent duplicates report in-progress, and interrupted/unrecorded outcomes refuse automatic re-execution. Historical replies never revive expired/completed sessions or authorize a replacement generation.
+- Add structured operational failure codes and retryability while preserving existing result fields. Distinguish claim/mutex wait contention from command deadlines, partial effects, ownership rejection and failed integration; preserve bounded command output on cancellation/timeouts.
+- Advance protocol to 1.4 and storage schema to 3. Transactional journal migration retains schema-2 ownership and recovery data; interrupted upgrades and missing journal state fail safely. No new runtime dependency, service or editor configuration changes.
+
 ## 0.1.5 — 2026-10-22
 
 - Group read-only radar observations by checkout, distinguishing current recorded Kith leases, retained sessions, unregistered checkouts and unavailable ownership. Label counts as paths to review before integration, with full checkout/owner details and preservation guidance. Reuse the same snapshot in the optional editor view without extra status subprocesses. No ownership, recovery or cleanup behavior changes.

package/README.md

@@ -4,12 +4,13 @@
 
 <p align="center">
   <a href="https://github.com/connorhriley/kith/actions/workflows/ci.yml"><img src="https://github.com/connorhriley/kith/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/connorhriley/kith/actions/workflows/windows.yml"><img src="https://github.com/connorhriley/kith/actions/workflows/windows.yml/badge.svg" alt="Windows validation"></a>
   <a href="https://www.npmjs.com/package/kith-coord"><img src="https://img.shields.io/npm/v/kith-coord" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E" alt="MIT license"></a>
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick start</a> · <a href="#see-it-work">Demo</a> · <a href="docs/integrations.md">Integrations</a> · <a href="docs/usage.md">CLI &amp; API</a> · <a href="CONTRIBUTING.md">Contribute</a>
+  <a href="#quick-start">Quick start</a> · <a href="https://marketplace.visualstudio.com/items?itemName=kith-coord.kith">VS Code</a> · <a href="https://open-vsx.org/extension/kith-coord/kith">Cursor / Open VSX</a> · <a href="#see-it-work">Demo</a> · <a href="docs/integrations.md">Integrations</a> · <a href="docs/usage.md">CLI &amp; API</a> · <a href="CONTRIBUTING.md">Contribute</a>
 </p>
 
 **Local coordination for cooperating coding agents.**
@@ -28,7 +29,7 @@ Kith gives cooperating agents shared local state: who owns a task, which files a
 | Give agents separate working files | Git worktrees with an explicit integration step |
 | Check work before integration | Your project's verification command |
 | Share local tools | Port reservations and supervised command mutexes |
-| See what is happening | Session/task state through `kith status` and MCP |
+| See what is happening | Session/task state through CLI/MCP; optional read-only editor and worktree views |
 
 Kith fits workflows where you already launch multiple coding agents and want them to coordinate. It does not choose models, write prompts, or launch a fleet for you. Worktrees separate files; Kith adds shared ownership and resource coordination.
 
@@ -36,14 +37,43 @@ The [reliability contract](docs/reliability.md) defines ownership, verification,
 
 ## Quick start
 
-Requires **Git 2.38+** and **Node.js 22.13+ on 22.x or Node.js 24+**. Full workflows target macOS and Linux. Version 0.1.1 also validates native Windows MCP claims, worktrees, ports, integration and recovery; supervised mutex commands and shell hooks require macOS/Linux or WSL. See the [support evidence](docs/client-validation.md#native-windows).
+Requires **Git 2.38+** and **Node.js 22.13+ on 22.x or Node.js 24+**. Full workflows target macOS and Linux. Native Windows MCP checks cover claims, worktrees, ports, integration and recovery; supervised mutex commands and shell hooks require macOS/Linux or WSL. See the [support evidence](docs/client-validation.md#native-windows).
 
 Git recording and integration require a commit identity configured for the repository (`user.name` and `user.email`). Kith does not change your global Git identity.
 
+**Upgrading to 0.1.6:** Stop existing Kith connections first. Back up stopped coordination state (including SQLite sidecars) and retain worktrees; upgrade all coordinators sharing a repository together. This release migrates storage schema 2 to 3, which older binaries refuse. Existing custom launchers are preserved; review their pinned version before reconnecting. See [recovery guidance](docs/reliability.md#recovery).
+
+### VS Code or Cursor
+
+Install **Kith** (`kith-coord.kith`) from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=kith-coord.kith) or [Cursor / Open VSX](https://open-vsx.org/extension/kith-coord/kith). You can also search for `kith-coord.kith` in the editor's Extensions view.
+
+To select release **0.1.6** explicitly with an editor CLI already on your `PATH`:
+
+```sh
+code --install-extension kith-coord.kith@0.1.6
+cursor --install-extension kith-coord.kith@0.1.6
+```
+
+Use the command for your editor. A marketplace lookup can temporarily select an older version; the [extension guide](extensions/editor/README.md#install) also links the published 0.1.6 VSIX.
+
+Open a trusted local Git checkout and approve Kith's MCP server through the editor. The extension bundles the coordination server, detects Node, and preserves existing MCP entries, hooks and tool permissions. **No global npm install is needed.** Each agent still needs to use Kith's tools; installing the extension does not enforce claims on other writers.
+
+Start with a scoped task:
+
+```text
+Use Kith to begin an isolated task in this repository with a unique agent ID.
+Claim only the files this task needs, edit the returned worktree, and report edits.
+Run the project checks and complete through Kith with that verification command.
+```
+
+The [extension guide](extensions/editor/README.md) covers settings and existing configurations; [recorded editor checks](docs/client-validation.md#editor-marketplaces-and-signed-in-chats) distinguish installation, native MCP registration and signed-in task results.
+
+### CLI and other MCP clients
+
 Install the release:
 
 ```sh
-npm install --global kith-coord@0.1.5
+npm install --global kith-coord@0.1.6
 ```
 
 Choose the setup scope your client needs:
@@ -98,14 +128,15 @@ Default setup installs MCP configuration for Claude, Codex and Cursor plus agent
 
 | Client | Setup and validation |
 | --- | --- |
+| VS Code | Marketplace extension; signed-in Copilot parallel task completed on VS Code 1.143.0 |
+| Cursor | Marketplace extension and native MCP registration checked on 3.24.18; signed-in task's final retry pending after client usage limit; native CLI workflow separately validated |
 | Claude Code | MCP; optional edit hooks need shared session setup; recorded native CLI runs |
 | Codex | Project MCP configuration; recorded native CLI runs with configuration overrides |
-| Cursor | Native CLI workflow and fail-closed edit hooks validated; GUI discovery/trust unvalidated |
 | Other MCP clients | stdio server via `kith mcp`; client-specific validation required |
 
-For VS Code and Cursor, the [editor extension](extensions/editor) offers a bundled MCP server and a small read-only status indicator. Install its VSIX through **Extensions → Install from VSIX**. It preserves existing MCP entries and leaves server approval and tool permissions to the editor. No global npm installation is needed; compatible Node.js is still required.
+The [editor extension](extensions/editor/README.md) offers a bundled MCP server and a small read-only status indicator. Existing custom Kith entries take precedence, so review their launcher if a connection fails. The editor retains control of server approval and tool permissions.
 
-Native checks are version-specific. GUI discovery and persisted project trust need separate checks. See [integration setup](docs/integrations.md), [recorded validation](docs/client-validation.md), and [session ownership](docs/sessions-and-mutexes.md) before mixing hooks, CLI commands, and MCP clients.
+Native checks are version-specific; the recorded GUI task used published extension 0.1.4. Later client or extension releases need their own checks. See [integration setup](docs/integrations.md), [recorded validation](docs/client-validation.md), and [session ownership](docs/sessions-and-mutexes.md) before mixing hooks, CLI commands, and MCP clients.
 
 The npm package is **`kith-coord`**, with the command name **`kith`**. For a pinned npx MCP launcher, see [registry setup](docs/integrations.md#registry-installation). The unrelated npm package `kith` is not this project.
 
@@ -121,6 +152,17 @@ kith lock acquire --agent worker-1 --scope package.json --wait --wait-ms 30000
 
 See [dev-server launch and waiting claims](docs/usage.md#launch-a-dev-server-on-its-allocated-port) for framework flags, session setup, cancellation, and MCP usage.
 
+## Optional read-only monitoring
+
+```sh
+kith watch /path/to/workspace --once --json
+kith menubar /path/to/workspace  # macOS 12+, Intel or Apple Silicon
+```
+
+The watcher compares uncommitted paths across linked worktrees of each repository; a workspace directory can contain several repositories. The editor and macOS menu show paths to review, checkout details and recorded active versus retained sessions. Retained work may still be unfinished: keep it until reviewed.
+
+These are observations, not proof of a merge conflict or the identity of a process writing a file. Unavailable scans stay unavailable. Claims, resource coordination and verified integration remain the MCP/CLI workflow. See [observation limits](docs/usage.md#optional-read-only-worktree-observations).
+
 ## How a task moves through Kith
 
 1. **Begin through MCP.** Call `kith_begin_work` with a unique `agentId`, explicit `scopeGlobs`, and `isolateWorktree: true`. The connection retains session ownership; no shell exports are needed for this MCP-only workflow.

package/dist/cli/index.js

@@ -6,8 +6,8 @@ import path19 from "path";
 import { spawn } from "child_process";
 
 // src/version.ts
-var KITH_VERSION = "0.1.5";
-var KITH_PROTOCOL_VERSION = "1.3.0";
+var KITH_VERSION = "0.1.6";
+var KITH_PROTOCOL_VERSION = "1.4.0";
 
 // src/cli/setup-ledger.ts
 import fs2 from "fs";
@@ -343,7 +343,7 @@ var CoordDatabase = class _CoordDatabase {
     }
     if (!tables.some((table) => table.name === "meta")) throw new Error("Missing coordination schema metadata. Preserve the database before repair.");
     const row = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get();
-    if (row?.value !== "1" && row?.value !== "2") {
+    if (row?.value !== "1" && row?.value !== "2" && row?.value !== "3") {
       throw new Error(`Unsupported coordination schema version: ${String(row?.value)}. Preserve the database before upgrading or repairing it.`);
     }
     const version = Number(row.value);
@@ -358,7 +358,8 @@ var CoordDatabase = class _CoordDatabase {
       "resources",
       "quarantine",
       "events",
-      ...version === 2 ? ["agent_sessions", "mutex_waiters", "mutex_runs"] : []
+      ...version >= 2 ? ["agent_sessions", "mutex_waiters", "mutex_runs"] : [],
+      ...version >= 3 ? ["mcp_operations"] : []
     ];
     if (required.some((name) => !tables.some((table) => table.name === name))) {
       throw new Error("Incomplete coordination schema. Preserve the database before repair.");
@@ -368,11 +369,12 @@ var CoordDatabase = class _CoordDatabase {
       tasks: "status,owner_agent_id,fencing_token,scope_globs_json,depends_on_json",
       locks: "owner_agent_id,pattern,mode,fencing_token,expires_at",
       resources: "type,name,owner_agent_id,fencing_token,expires_at",
-      ...version === 2 ? {
+      ...version >= 2 ? {
         agent_sessions: "agent_id,token_hash,epoch",
         mutex_waiters: "ticket,mutex_name,request_id,owner_agent_id,session_epoch,waiter_pid,waiter_start,expires_at",
         mutex_runs: "mutex_name,run_id,owner_agent_id,session_epoch,fencing_token,supervisor_pid,supervisor_start,worker_pid,worker_start"
-      } : {}
+      } : {},
+      ...version >= 3 ? { mcp_operations: "operation_key,request_hash,agent_id,session_epoch,capability_hash,owner_pid,owner_start,result_json,created_at" } : {}
     };
     for (const [table, fields] of Object.entries(columns)) {
       try {
@@ -387,7 +389,8 @@ var CoordDatabase = class _CoordDatabase {
       "SELECT fencing_token FROM tasks",
       "SELECT fencing_token FROM resources",
       "SELECT fencing_token FROM merge_queue",
-      ...version === 2 ? ["SELECT epoch FROM agent_sessions", "SELECT session_epoch FROM mutex_waiters", "SELECT fencing_token FROM mutex_runs"] : []
+      ...version >= 2 ? ["SELECT epoch FROM agent_sessions", "SELECT session_epoch FROM mutex_waiters", "SELECT fencing_token FROM mutex_runs"] : [],
+      ...version >= 3 ? ["SELECT session_epoch FROM mcp_operations"] : []
     ];
     if (db.prepare(`SELECT 1 FROM (${tokens.join(" UNION ALL ")}) WHERE token IS NOT NULL AND (typeof(token)!='integer' OR token<0 OR token>?) LIMIT 1`).get(epoch)) {
       throw new Error("Invalid or regressed fencing counter. Preserve the database before repair.");
@@ -565,6 +568,14 @@ var CoordDatabase = class _CoordDatabase {
           worker_pid INTEGER, worker_start TEXT
         );
       `);
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS mcp_operations (
+          operation_key TEXT PRIMARY KEY, request_hash TEXT NOT NULL,
+          agent_id TEXT NOT NULL, session_epoch INTEGER NOT NULL, capability_hash TEXT NOT NULL,
+          owner_pid INTEGER NOT NULL, owner_start TEXT NOT NULL,
+          result_json TEXT, created_at INTEGER NOT NULL
+        );
+      `);
       if (version < 2) {
         this.db.exec(`
           UPDATE tasks SET status='queued', owner_agent_id=NULL, fencing_token=NULL
@@ -576,6 +587,7 @@ var CoordDatabase = class _CoordDatabase {
           UPDATE meta SET value='2' WHERE key='schema_version';
         `);
       }
+      this.db.exec("UPDATE meta SET value='3' WHERE key='schema_version'");
     });
   }
   /**
@@ -849,7 +861,7 @@ function readCoordinationState(directory = process.cwd(), options = {}) {
     if (JSON.stringify(before) !== JSON.stringify(files.map(identity))) throw new Error("Coordination state changed during snapshot; stop writers or retry");
     db = new DatabaseSync2(path4.join(scratch, "state.db"), { readOnly: true });
     db.exec("PRAGMA query_only=ON; PRAGMA busy_timeout=1000; BEGIN");
-    if (CoordDatabase.inspectSchema(db) !== 2) throw new Error("Offline observation requires schema 2; preserve state and upgrade with clients stopped");
+    if (CoordDatabase.inspectSchema(db) < 2) throw new Error("Offline observation requires schema 2 or newer; preserve state and upgrade with clients stopped");
     const all = (sql) => db.prepare(sql).all();
     const agents = all("SELECT * FROM agents ORDER BY registered_at DESC");
     if (options.ownersOnly) {
@@ -1622,10 +1634,10 @@ var LockEngine = class _LockEngine {
   static normalizePattern(repoRoot, rawPattern) {
     if (rawPattern.startsWith("file:")) return _LockEngine.literalScope(_LockEngine.normalizeFile(repoRoot, rawPattern.slice(5)));
     if (rawPattern.startsWith("symbol:")) {
-      const hash = rawPattern.indexOf("#");
-      const name = rawPattern.slice(hash + 1);
-      if (hash < 0 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) throw new Error("Symbol scope must include #symbolName");
-      const file = _LockEngine.normalizeFile(repoRoot, rawPattern.slice(7, hash));
+      const hash2 = rawPattern.indexOf("#");
+      const name = rawPattern.slice(hash2 + 1);
+      if (hash2 < 0 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) throw new Error("Symbol scope must include #symbolName");
+      const file = _LockEngine.normalizeFile(repoRoot, rawPattern.slice(7, hash2));
       return `symbol:${file}#${name}`;
     }
     if (!rawPattern || /[\\\x00-\x1f\x7f]/u.test(rawPattern)) throw new Error(`Invalid repository scope: ${rawPattern}`);
@@ -1880,9 +1892,9 @@ var LockEngine = class _LockEngine {
         return !this.pathCase.get(root);
       });
       const fold = (scope) => {
-        const hash = scope.startsWith("symbol:") ? scope.lastIndexOf("#") : -1;
-        const file = hash < 0 ? scope : scope.slice(0, hash);
-        return file.normalize("NFC").toLowerCase().replace(/ς/g, "\u03C3") + (hash < 0 ? "" : scope.slice(hash));
+        const hash2 = scope.startsWith("symbol:") ? scope.lastIndexOf("#") : -1;
+        const file = hash2 < 0 ? scope : scope.slice(0, hash2);
+        return file.normalize("NFC").toLowerCase().replace(/ς/g, "\u03C3") + (hash2 < 0 ? "" : scope.slice(hash2));
       };
       const overlap = (a, b) => _LockEngine.patternsOverlap(a, b) || insensitive && _LockEngine.patternsOverlap(fold(a), fold(b));
       return overlap(requested, existing) || overlap(requested, normalized) || this.wildcardHasAliases(requested) || this.wildcardHasAliases(normalized);
@@ -2481,7 +2493,7 @@ var ResourceBroker = class _ResourceBroker {
           worker.once("error", reject);
         }), stopped]);
         if (params.signal?.aborted) failure ??= abortError();
-        if (failure) throw failure;
+        if (failure) throw Object.assign(failure, { stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString() });
         if (!outcome) throw new Error("Command worker exited without a result");
         if (outcome.error) throw new Error(outcome.error);
         return { stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), exitCode: outcome.exitCode, waitedMs };
@@ -4046,25 +4058,188 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import fs16 from "fs";
 import path15 from "path";
+
+// src/mcp/retries.ts
+import crypto11 from "crypto";
+var RetryError = class extends Error {
+  constructor(code, message, retryable = false) {
+    super(message);
+    this.code = code;
+    this.retryable = retryable;
+  }
+  code;
+  retryable;
+};
+function failureData(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  let code = "OPERATION_FAILED", retryable = false;
+  if (error instanceof RetryError) {
+    code = error.code;
+    retryable = error.retryable;
+  } else if (error instanceof SessionOwnershipError) code = "SESSION_OWNERSHIP";
+  else if (error instanceof StaleFencingTokenError) code = "STALE_FENCING_TOKEN";
+  else if (error instanceof Error && error.name === "AbortError") code = "CANCELLED";
+  else if (message.startsWith("Timed out waiting for mutex ")) {
+    code = "MUTEX_WAIT_TIMEOUT";
+    retryable = true;
+  } else if (message === "Mutex command execution timed out") code = "COMMAND_TIMEOUT";
+  else if (message === "Mutex command output limit exceeded") code = "COMMAND_OUTPUT_LIMIT";
+  else if (/SQLITE_BUSY|database is locked/.test(message)) code = "DATABASE_BUSY";
+  else if (/schema|coordination database|fencing counter|recovery state/i.test(message)) code = "STATE_UNAVAILABLE";
+  else if (/repository|checkout path|project selected|connection is pinned|Command cwd|Invalid agent ID|Lease duration|Unsupported.*pattern/i.test(message)) code = "INVALID_REQUEST";
+  const details = error;
+  return {
+    ok: false,
+    error: message,
+    failure: {
+      code,
+      message,
+      retryable,
+      ...retryable ? { retryAfterMs: 100 } : {}
+    },
+    ...typeof details?.stdout === "string" ? { stdout: details.stdout } : {},
+    ...typeof details?.stderr === "string" ? { stderr: details.stderr } : {}
+  };
+}
+function classifyResult(data) {
+  if (data.ok !== false || data.failure) return data;
+  if (data.mergeResult) return { ...data, failure: {
+    code: "INTEGRATION_FAILED",
+    retryable: false,
+    message: "Inspect mergeResult.diagnostics and repair or preserve the source worktree before a new completion attempt."
+  } };
+  if (Array.isArray(data.lockConflicts) || Array.isArray(data.conflicts)) return { ...data, failure: {
+    code: data.waitTimedOut ? "CLAIM_WAIT_TIMEOUT" : "CLAIM_CONFLICT",
+    retryable: true,
+    retryAfterMs: 100,
+    message: "Scope is owned by another session. Back off before a new attempt (with a new operationKey if used)."
+  } };
+  if (typeof data.exitCode === "number") return { ...data, failure: {
+    code: "COMMAND_FAILED",
+    retryable: false,
+    message: "Inspect stdout, stderr and exitCode; commands may have partial effects. Repair before a new attempt."
+  } };
+  return { ...data, failure: {
+    code: "OPERATION_FAILED",
+    retryable: false,
+    message: typeof data.error === "string" ? data.error : "Inspect the result before a new attempt."
+  } };
+}
+function toolReply(data, footer = []) {
+  data = classifyResult(data);
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }, ...footer], structuredContent: data, isError: data.ok === false };
+}
+var hash = (text) => crypto11.createHash("sha256").update(text).digest("hex");
+function canonical(value) {
+  if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => JSON.stringify(k) + ":" + canonical(v)).join(",") + "}";
+  return JSON.stringify(value);
+}
+var OperationJournal = class _OperationJournal {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  static undurable = /* @__PURE__ */ new Set();
+  async execute(params) {
+    const { operationKey: _key, sessionToken: _token, ...input } = params.input;
+    const localKey = this.db.dbPath + ":" + params.key;
+    const requestHash = hash(canonical({ tool: params.tool, checkout: this.db.repoRoot, input }));
+    const operation = (state, replayed) => ({ key: params.key, state, replayed });
+    const previous = this.db.withTransaction(() => {
+      const row = this.db.db.prepare("SELECT * FROM mcp_operations WHERE operation_key=?").get(params.key);
+      if (row) {
+        const token = params.token();
+        if (!token || row.agent_id !== params.agentId || hash(token) !== row.capability_hash) throw new SessionOwnershipError(params.agentId ?? "");
+        if (row.request_hash !== requestHash) throw new RetryError("OPERATION_KEY_REUSED", "operationKey already identifies a different tool, checkout or input. Use a new key for new work.");
+        return row;
+      }
+      const identity = params.authorize();
+      const start = FencingAndAgentManager.getProcessStartTime(process.pid);
+      if (!start) throw new RetryError("STATE_UNAVAILABLE", "Cannot identify operation owner; no operation was started.");
+      this.db.db.prepare(`INSERT INTO mcp_operations
+        (operation_key,request_hash,agent_id,session_epoch,capability_hash,owner_pid,owner_start,result_json,created_at)
+        VALUES (?,?,?,?,?,?,?,NULL,?)`).run(
+        params.key,
+        requestHash,
+        identity.agentId,
+        identity.sessionEpoch,
+        hash(identity.token),
+        process.pid,
+        start,
+        Date.now()
+      );
+      return void 0;
+    });
+    if (previous) {
+      if (previous.result_json !== null) {
+        let saved2;
+        try {
+          saved2 = JSON.parse(previous.result_json);
+          if (!saved2.data || typeof saved2.data !== "object" || Array.isArray(saved2.data) || typeof saved2.grantsToken !== "boolean") throw new Error();
+        } catch {
+          throw new RetryError("STATE_UNAVAILABLE", "Unreadable operation result. Preserve coordination state before repair.");
+        }
+        return toolReply({ ...saved2.data, ...saved2.grantsToken ? { sessionToken: params.token() } : {}, operation: operation("completed", true) });
+      }
+      const alive = !_OperationJournal.undurable.has(localKey) && FencingAndAgentManager.isProcessAlive(previous.owner_pid, previous.owner_start);
+      return toolReply({
+        ...failureData(new RetryError(
+          alive ? "OPERATION_IN_PROGRESS" : "OPERATION_OUTCOME_UNKNOWN",
+          alive ? "Operation has not returned a durable result. Retry this same key after backoff; do not start a duplicate." : "Operation result was not recorded after its owner stopped or persistence failed. Inspect status, worktrees and external effects before deliberately starting new work with a new key.",
+          alive
+        )),
+        operation: operation(alive ? "running" : "unknown", true)
+      });
+    }
+    let reply;
+    try {
+      reply = await params.run();
+    } catch (error) {
+      reply = toolReply(failureData(error));
+    }
+    const data = reply.structuredContent;
+    const { sessionToken, ...saved } = data;
+    try {
+      const result = this.db.db.prepare("UPDATE mcp_operations SET result_json=? WHERE operation_key=? AND result_json IS NULL").run(JSON.stringify({ data: saved, grantsToken: typeof sessionToken === "string" }), params.key);
+      if (Number(result.changes) !== 1) throw new Error("Operation result was not recorded");
+    } catch {
+      _OperationJournal.undurable.add(localKey);
+      return toolReply({
+        ...failureData(new RetryError(
+          "OPERATION_OUTCOME_UNKNOWN",
+          "The operation may have completed but its result could not be recorded. Preserve state and inspect effects; do not repeat it automatically."
+        )),
+        operation: operation("unknown", false)
+      });
+    }
+    return toolReply({ ...data, operation: operation("completed", false) }, reply.content.slice(1));
+  }
+};
+
+// src/mcp/server.ts
 function buildKithMcpServer(repoRoot, pinned) {
   const pinnedRoot = pinned ? discoverRepository(repoRoot).checkoutRoot : void 0;
   const server = new McpServer({
     name: "kith-coordinator",
     version: KITH_VERSION
-  }, { instructions: "Kith coordinates work claims, isolated worktrees, local resources and verified integration for cooperating coding agents. State stays local; no hosted service or model API key is required. The optional repository argument selects an absolute Git checkout for each call on a global connection. Keep passing the original checkout, even while editing its returned worktree. If no project context is available, ask for a repository path; never substitute HOME or a filesystem root. Each call is routed independently; there is no shared current project. Recommended workflow: one isolated worktree per parallel agent. Call kith_begin_work with isolateWorktree:true and explicit scopeGlobs; edit only the returned worktreePath, call kith_record_file_edit, run literal argv with kith_run_with_mutex, and finish with kith_complete_work plus a project verificationCmd. Heartbeat before the session expires. " + (repoRoot && process.env.KITH_AGENT_ID ? `This server shares a session with CLI/hooks. Use agentId '${process.env.KITH_AGENT_ID}'. Its inherited capability is handled internally; do not request or log it.` : "Start with kith_begin_work or kith_start_session and a unique agentId. This connection retains its granted capability. Omit sessionToken on subsequent calls on this connection; only another connection needs it to resume that ID. Initial grant/resume replies contain the token and client transcripts may record it. Keep transcripts private.") });
+  }, { instructions: "Kith coordinates work claims, isolated worktrees, local resources and verified integration for cooperating coding agents. State stays local; no hosted service or model API key is required. The optional repository argument selects an absolute Git checkout for each call on a global connection. Keep passing the original checkout, even while editing its returned worktree. If no project context is available, ask for a repository path; never substitute HOME or a filesystem root. Each call is routed independently; there is no shared current project. Recommended workflow: one isolated worktree per parallel agent. Call kith_begin_work with isolateWorktree:true and explicit scopeGlobs; edit only the returned worktreePath, call kith_record_file_edit, run literal argv with kith_run_with_mutex, and finish with kith_complete_work plus a project verificationCmd. Heartbeat before the session expires. For mutations, generate a unique operationKey and reuse it only to recover that exact attempt after a timeout. Replay is a historical result, never a renewed claim. Inspect failure.code and failure.retryable; an unknown command outcome requires inspection, not automatic re-execution. " + (repoRoot && process.env.KITH_AGENT_ID ? `This server shares a session with CLI/hooks. Use agentId '${process.env.KITH_AGENT_ID}'. Its inherited capability is handled internally; do not request or log it.` : "Start with kith_begin_work or kith_start_session and a unique agentId. This connection retains its granted capability. Omit sessionToken on subsequent calls on this connection; only another connection needs it to resume that ID. Initial grant/resume replies contain the token and client transcripts may record it. Keep transcripts private.") });
   const disconnected = new AbortController();
   const commands = /* @__PURE__ */ new Set();
   const createContext = (root, inheritCapability) => {
     const engine2 = new KithEngine(root);
     const owned = /* @__PURE__ */ new Set();
-    const tokenFor = (args) => args.sessionToken ?? (inheritCapability && process.env.KITH_AGENT_ID === args.agentId ? process.env.KITH_SESSION_TOKEN : void 0);
+    const capabilities = /* @__PURE__ */ new Map();
+    const journal = new OperationJournal(engine2.coordDb);
+    const tokenFor = (args) => args.sessionToken ?? (inheritCapability && process.env.KITH_AGENT_ID === args.agentId ? process.env.KITH_SESSION_TOKEN : capabilities.get(args.agentId));
     const register = (args) => {
       const result = engine2.fencing.registerAgent({
         id: args.agentId,
         client: args.client ?? "mcp",
-        sessionToken: tokenFor(args),
+        sessionToken: args.sessionToken ?? (inheritCapability && process.env.KITH_AGENT_ID === args.agentId ? process.env.KITH_SESSION_TOKEN : void 0),
         leaseDurationMs: args.leaseDurationMs
       });
+      capabilities.set(args.agentId, result.sessionToken);
       if (result.agent.pid === process.pid) owned.add(args.agentId);
       return result;
     };
@@ -4076,10 +4251,7 @@ function buildKithMcpServer(repoRoot, pinned) {
     const formatReply = (agentId, payload) => {
       const delta = agentId ? engine2.consumeAgentDelta(agentId).formattedFooter : "";
       const data = payload;
-      return { content: [
-        { type: "text", text: JSON.stringify(data, null, 2) },
-        ...delta ? [{ type: "text", text: delta }] : []
-      ], structuredContent: data, isError: data.ok === false };
+      return toolReply(data, delta ? [{ type: "text", text: delta }] : []);
     };
     const close = () => {
       for (const id of owned) {
@@ -4090,7 +4262,7 @@ function buildKithMcpServer(repoRoot, pinned) {
       }
       engine2.close();
     };
-    return { engine: engine2, register, authorize, formatReply, close };
+    return { engine: engine2, register, authorize, formatReply, close, journal, tokenFor };
   };
   const contexts = /* @__PURE__ */ new Map();
   const contextFor = (repository) => {
@@ -4109,14 +4281,48 @@ function buildKithMcpServer(repoRoot, pinned) {
   };
   const engine = pinned ? contextFor().engine : void 0;
   const tool = (name, description, schema, handler) => {
-    const inputSchema = { ...schema, repository: z.string().optional().describe("Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task.") };
+    const keyed = !["kith_get_status", "kith_preview_integrate", "kith_heartbeat"].includes(name);
+    const inputSchema = { ...schema, ...keyed ? { operationKey: z.string().min(1).max(128).optional().describe("Unique client-generated key for this exact mutation. Reuse only to recover its result; never an ownership credential. Retried failures are snapshots; use a new key after repair or backoff.") } : {}, repository: z.string().optional().describe("Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task.") };
     server.tool(
       name,
       description,
       inputSchema,
       async (args, extra) => {
         const { repository, ...input } = args;
-        return handler(input, extra, contextFor(repository));
+        const execution = (async () => {
+          try {
+            const context = contextFor(repository);
+            const run = async () => {
+              extra.signal.throwIfAborted();
+              return handler(input, extra, context);
+            };
+            if (!keyed || input.operationKey === void 0) return await run();
+            const identity = input;
+            return await context.journal.execute({
+              key: input.operationKey,
+              tool: name,
+              input,
+              agentId: identity.agentId,
+              token: () => identity.agentId ? context.tokenFor({ ...identity, agentId: identity.agentId }) : void 0,
+              authorize: () => {
+                if (!identity.agentId) throw new RetryError("INVALID_REQUEST", "Keyed mutations require agentId and an owned session. Start a session first.");
+                const args2 = { ...identity, agentId: identity.agentId };
+                if (["kith_start_session", "kith_begin_work", "kith_claim_next_task"].includes(name)) context.register(args2);
+                else context.authorize(args2);
+                return { agentId: identity.agentId, sessionEpoch: context.engine.fencing.assertSession(identity.agentId), token: context.tokenFor(args2) };
+              },
+              run
+            });
+          } catch (error) {
+            return toolReply(failureData(error));
+          }
+        })();
+        commands.add(execution);
+        try {
+          return await execution;
+        } finally {
+          commands.delete(execution);
+        }
       }
     );
   };
@@ -4213,6 +4419,8 @@ function buildKithMcpServer(repoRoot, pinned) {
     "Add a task to the orchestrated DAG queue with optional task dependencies and file scope globs.",
     {
       id: z.string().optional(),
+      agentId: z.string().optional().describe("Required for operationKey; identifies an already owned session."),
+      sessionToken: z.string().optional(),
       title: z.string(),
       intentSummary: z.string().optional(),
       priority: z.number().optional(),
@@ -4220,6 +4428,7 @@ function buildKithMcpServer(repoRoot, pinned) {
       scopeGlobs: z.array(z.string()).optional()
     },
     async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
+      if (args.agentId) authorize({ ...args, agentId: args.agentId });
       const task = engine2.intents.addTask(args);
       return formatReply(void 0, { ok: true, task });
     }
@@ -4900,17 +5109,17 @@ function contentIdentity(repo, file) {
   try {
     const before = fs19.fstatSync(fd);
     if (before.ino !== stat.ino || before.dev !== stat.dev || before.size !== stat.size || before.mtimeMs !== stat.mtimeMs) throw new Error(`File changed during comparison: ${file}`);
-    const hash = createHash("sha256");
+    const hash2 = createHash("sha256");
     const buffer = Buffer.allocUnsafe(64 * 1024);
     for (let offset = 0; offset < before.size; ) {
       const count = fs19.readSync(fd, buffer, 0, Math.min(buffer.length, before.size - offset), offset);
       if (!count) throw new Error(`File changed during comparison: ${file}`);
-      hash.update(buffer.subarray(0, count));
+      hash2.update(buffer.subarray(0, count));
       offset += count;
     }
     const after = fs19.fstatSync(fd);
     if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error(`File changed during comparison: ${file}`);
-    return `file:${before.mode & 73}:${hash.digest("hex")}`;
+    return `file:${before.mode & 73}:${hash2.digest("hex")}`;
   } finally {
     fs19.closeSync(fd);
   }