kith-coord 0.1.5 → 0.1.7

package/docs/client-validation.md

@@ -20,7 +20,7 @@ Reports contain client/version, platform, scenario outcomes and tool names. Raw
 
 ## Hosted checks
 
-The `CI` workflow runs independently on Linux/macOS with Node 22.13.0, current 22 and 24. Each job checks types, process/lifecycle and MCP tests, an installed package consumer, and the two-client worktree demo. JUnit reports are retained even when a test fails. It also supports manual dispatch. Hosted CI does not run paid models or require agent credentials. Run native clients separately after adapter changes and record their exact versions and outcomes here or in the pull request.
+The `CI` workflow runs independently on Linux/macOS with Node 22.13.0, current 22 and 24. Each job checks types, process/lifecycle and MCP tests, an installed package consumer, and the two-client worktree demo. JUnit reports are retained even when a test fails. It also supports manual dispatch. The separate Windows workflow adds two installed-package jobs on Node 22.13.0 and 24, making eight hosted jobs in total. Hosted CI does not run paid models or require agent credentials. Run native clients separately after adapter changes and record their exact versions and outcomes here or in the pull request.
 
 ## Recorded native runs
 
@@ -44,7 +44,7 @@ The 2026-10-20 subtraction pass reran the isolated native workflows on macOS / N
 
 ## Cursor adapter coverage
 
-Generated Cursor hooks use the documented native `preToolUse`/`postToolUse` protocol and `failClosed:true`. Subprocess fixtures exercise allow/deny JSON, block/warn/off mode changes, preservation of unrelated hooks, and missing/forged ownership refusal. Native Cursor CLI evidence is recorded below. Cursor GUI discovery/trust and other client versions remain unvalidated; CLI and payload fixtures do not establish those outcomes. The shared Git/worktree and MCP boundaries have separate automated coverage.
+Generated Cursor hooks use the documented native `preToolUse`/`postToolUse` protocol and `failClosed:true`. Subprocess fixtures exercise allow/deny JSON, block/warn/off mode changes, preservation of unrelated hooks, and missing/forged ownership refusal. Native Cursor CLI evidence is recorded below. Editor marketplace discovery and native MCP registration have separate versioned checks below. CLI hook runs do not establish GUI hook behavior or support for other client versions. The shared Git/worktree and MCP boundaries have separate automated coverage.
 
 
 The 2026-10-20 adoption pass reran the isolated workflows on macOS / Node 22.23.3: [Codex CLI 0.163.0-alpha.10.2](validation/2026-10-20-adoption-codex.json) and [Claude Code 2.1.301](validation/2026-10-20-adoption-claude.json) passed native editing, renewable mutex execution, failed verification/retry, integration and ownership release. Claude also passed the separate [unavailable-guard denial](validation/2026-10-20-adoption-hook-failure.json).
@@ -71,3 +71,17 @@ This is an attributed external workflow report for those versions, not a control
 ## 2026-10-22 reliability pass
 
 Fresh synthetic isolated-worktree checks passed with Claude Code 2.1.301 and Codex CLI 0.163.0-alpha.11.1 on macOS / Node 22.23.3, using existing subscription sign-ins. Both exercised conflicting claim refusal, native edits, a renewable command mutex, failed verification with preserved target, successful repair/retry and released ownership. Claude also verified native hook denial. These are version-specific native checks, separate from the actual Kith project integration and from external adoption. Reports: [Claude](validation/2026-10-22-product-claude.json), [Codex](validation/2026-10-22-product-codex.json).
+
+
+## Editor marketplaces and signed-in chats
+
+On 2026-10-22, published extension **0.1.4** was installed from each editor's own marketplace in **VS Code 1.143.0** and **Cursor 3.24.18** on macOS. Search, download and installation succeeded without sideloading or a gallery override. Installed payloads matched the released VSIX. Native checks passed activation, MCP registration, Node autodetection with a minimal PATH, read-only observation without database initialization, and byte-for-byte preservation of existing custom/disabled Kith entries and peer configurations. SDK-driven workflows against each installed bundled server separately covered ownership, scope/path refusal, worktrees, resources, verified integration and recovery. [Marketplace report](validation/2026-10-22-editor-marketplaces.json).
+
+Separate **signed-in GUI chats** used a disposable invoice task with one discount agent and one tax agent. Both editors refused a tax agent's overlapping discount claim and gave the agents separate worktrees. Each chat implemented its scoped module, reported the edit, ran tests through `kith_run_with_mutex`, and committed. Full verification correctly failed before the other module was integrated; independent Git checks confirmed the target stayed unchanged and the committed worktree was retained.
+
+| Editor | Signed-in task result |
+| --- | --- |
+| VS Code 1.143.0 / Copilot | Discount integrated with scoped checks; tax retried through Kith with the full suite. All five tests passed; both sessions completed and no locks remained. An independent `npm test` and scoped Git diff confirmed the result. |
+| Cursor 3.24.18 | Both implementations committed and scoped tests passed. Discount integrated; the account's Agent usage limit blocked the final tax retry. That retry remains pending, with the worktree and commits preserved. This is partial GUI workflow evidence. |
+
+[Signed-in chat report](validation/2026-10-22-editor-chats.json). Normal OS Keychain storage and native approval controls were used for these chats; the mock Keychain is only for unsigned disposable host tests. All 15 monitored live client configuration paths remained byte-for-byte unchanged. Only synthetic fixture code and task prompts were used for model-driven work; no API keys were added. Public reports omit credentials and raw capability-bearing transcripts. No production work was changed. These are internal synthetic checks, separate from external user adoption, Windows GUI coverage and later client/extension releases.

package/docs/integrations.md

@@ -1,6 +1,6 @@
 # Client integrations
 
-Install Kith persistently or build and link the checkout first. On macOS/Linux, generated configurations use the `kith` executable already on PATH; they do not download an unverified package at hook execution time.
+For CLI-generated configuration, install Kith persistently or build and link the checkout first. On macOS/Linux, generated configurations use the `kith` executable already on PATH; they do not download an unverified package at hook execution time.
 
 | Selection | Files and behavior |
 | --- | --- |
@@ -11,6 +11,12 @@ Install Kith persistently or build and link the checkout first. On macOS/Linux,
 | `git` | Installs a pre-commit hook only when one does not exist; uses an in-repository Git hooks path and skips external hooks directories |
 | `shims` | Creates optional `.coord/bin/npm`, `pnpm`, and `yarn` wrappers |
 
+## VS Code and Cursor extension
+
+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). Open a trusted local Git checkout with a supported Node installation, then approve the bundled server through the editor's native MCP controls. No global npm install or hand-written MCP entry is required for this path.
+
+The extension preserves existing project/global Kith entries and suppresses its duplicate registration when one exists. Other MCP servers, hooks and permissions remain untouched. Custom entries continue to use their configured launcher; installing the extension does not replace it. Use a unique agent ID, pass the original absolute `repository` on each call, and edit only the worktree returned by `kith_begin_work`. The small status view is read-only. See [extension settings](../extensions/editor/README.md) and [recorded native checks](client-validation.md#editor-marketplaces-and-signed-in-chats).
+
 ## Start with MCP
 
 Choose global `kith setup` for an existing desktop/user-wide client connection, or project `kith init` for checkout-scoped configuration and instructions. You do not need to run both for the same client. An existing global connection can use `kith init --only agents` to add just project guidance. Configuration changes do not prove native connection or ownership.
@@ -66,12 +72,12 @@ Uninstall restores the exact original bytes/permissions or deletes files created
 
 ## Registry installation
 
-The package is `kith-coord`, and its binary remains `kith`. Install it persistently (`npm install --global kith-coord@0.1.5`) before `kith init`, because generated configurations launch `kith` on PATH. Invoking init through npx alone does not create that persistent executable.
+The package is `kith-coord`, and its binary remains `kith`. Install it persistently (`npm install --global kith-coord@0.1.6`) before `kith init`, because generated configurations launch `kith` on PATH. Invoking init through npx alone does not create that persistent executable.
 
 An MCP client can instead use a pinned registry launcher without a global install:
 
 ```json
-{"mcpServers":{"kith":{"command":"npx","args":["--yes","--package","kith-coord@0.1.5","kith","mcp","--repo","/absolute/checkout"]}}}
+{"mcpServers":{"kith":{"command":"npx","args":["--yes","--package","kith-coord@0.1.6","kith","mcp","--repo","/absolute/checkout"]}}}
 ```
 
 Use a version you have verified; the unrelated npm package named `kith` is not Kith's distribution. Hook commands still need their configured executable to remain available. The clean-package smoke check exercises the installed binary, library, supervised worker and actual MCP discovery/status in a separate consumer.
@@ -84,6 +90,11 @@ Version 0.1.1 generates MCP configuration using the current absolute Node execut
 
 ## Configure detected local clients
 
+From 0.1.7, `npx --yes --package kith-coord@0.1.7 kith setup /absolute/checkout` is the single setup path. Versions through 0.1.6 need a persistent npm installation first. Setup retains the exact bundled runtime under `~/.local/share/kith/runtimes/`, validates actual MCP discovery without selecting a repository, configures supported detected clients and adds marked project guidance. Clearing the original npx cache does not break its launcher. Repeat setup reuses identical content; upgrades retain prior runtimes so existing processes and configuration backups remain usable. A damaged selected runtime is refused rather than overwritten. Custom launchers remain custom.
+
+Retained runtimes are not automatically deleted by uninstall because existing or edited client configurations may still reference them. Global setup outside a Git checkout does not create one whole-machine coordination database. Project guidance joins the existing original-byte setup ledger. An older project schema is refused before changing clients: stop all coordinators and follow the upgrade procedure first.
+
+
 `kith setup --dry-run` previews configuration for detected existing clients; omit `--dry-run` to apply it. It works from HOME without creating a project database there. Global Claude Desktop, Claude Code, Codex and Antigravity entries use this installation's Node and CLI paths and can select a different Git repository on each MCP call. No disk-wide scan or shared current-project switch is involved. Clients started inside a Git checkout use that checkout by default. Desktop clients started at `/` or HOME connect without opening a coordinator; their agent supplies an absolute `repository` path for the task.
 
 Run `kith setup /absolute/checkout` inside a project to configure its Cursor entry as well. Project entries and explicit `mcp --repo /absolute/checkout` remain pinned to that checkout. Existing hooks and approval settings are untouched. Custom Kith transports or wrappers that cannot be safely recognized are preserved and reported for manual review, with a nonzero exit. Detection/configuration is not proof that a particular GUI client connected; restart or reconnect that client after setup and check its server status. VS Code is not an automatic setup adapter.

package/docs/protocol/tools.v1.json

@@ -1,5 +1,5 @@
 {
-  "protocolVersion": "1.3.0",
+  "protocolVersion": "1.5.0",
   "tools": [
     {
       "name": "kith_start_session",
@@ -16,6 +16,12 @@
           "leaseDurationMs": {
             "type": "number"
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -94,6 +100,12 @@
             "maximum": 600000,
             "description": "Wait up to this many milliseconds for the whole scope; default fail-fast, not a FIFO file queue"
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -124,6 +136,22 @@
           "client": {
             "type": "string"
           },
+          "isolateWorktree": {
+            "type": "boolean",
+            "description": "Recommended: true, giving the claiming agent an isolated Git worktree"
+          },
+          "waitTimeoutMs": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 600000,
+            "description": "Wait up to this many milliseconds for a queued task to become unblocked and claimable"
+          },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -145,6 +173,13 @@
           "id": {
             "type": "string"
           },
+          "agentId": {
+            "type": "string",
+            "description": "Required for operationKey; identifies an already owned session."
+          },
+          "sessionToken": {
+            "type": "string"
+          },
           "title": {
             "type": "string"
           },
@@ -166,6 +201,12 @@
               "type": "string"
             }
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -211,6 +252,12 @@
             "minimum": 0,
             "maximum": 600000
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -242,6 +289,12 @@
           "content": {
             "type": "string"
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -291,6 +344,12 @@
           "docComment": {
             "type": "string"
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -325,6 +384,12 @@
           "basePort": {
             "type": "number"
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -387,6 +452,12 @@
             "minimum": 1,
             "maximum": 1048576
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -448,6 +519,12 @@
             "minimum": 1,
             "maximum": 1048576
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -474,6 +551,10 @@
           "sessionToken": {
             "type": "string"
           },
+          "includeHistory": {
+            "type": "boolean",
+            "description": "Include completed task history; default false returns current/pending tasks plus completedTaskCount. Lock lease details are always preserved."
+          },
           "includeContracts": {
             "type": "boolean",
             "description": "Include the full contract registry. Default false keeps frequent status polls compact; contractCount always reports its size."
@@ -537,6 +618,12 @@
             "type": "string",
             "description": "Command to run in speculative merge tree (e.g. \"npm run typecheck\")"
           },
+          "operationKey": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "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": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."

package/docs/protocol.md

@@ -1,4 +1,4 @@
-# Kith coordination protocol 1.3
+# Kith coordination protocol 1.5
 
 Kith is a local ledger for cooperating coding agents. Clients share one repository's coordination state, including across linked Git worktrees. The transport is MCP over stdio (`kith mcp --repo /absolute/checkout`). No hosted service or Kith API key is required. The server process has the user's filesystem and command permissions.
 
@@ -6,11 +6,11 @@ Kith is a local ledger for cooperating coding agents. Clients share one reposito
 
 Protocol 1.1 ships with package 0.1.2. Earlier `kith-coord@0.1.1` reports protocol 1.0 and includes full contracts in MCP status; the compact default and `includeContracts` input below require 0.1.2.
 
-`KITH_PROTOCOL_VERSION` and status responses advertise `1.3.0`. Package releases (`kith-coord`, beginning at 0.1.0) and the SQLite storage schema (2) have independent versions. The [tool snapshot](protocol/tools.v1.json) contains all 14 tool names, descriptions and JSON input schemas, exported from an actual MCP `tools/list` response. `pnpm protocol:check` rejects snapshot drift in CI. Update deliberately using `pnpm protocol:export`.
+`KITH_PROTOCOL_VERSION` and status responses advertise `1.5.0` starting with package 0.1.7; package 0.1.6 advertises `1.4.0`. Package releases (`kith-coord`, beginning at 0.1.0) and the SQLite storage schema (3) have independent versions. The [tool snapshot](protocol/tools.v1.json) contains all 14 tool names, descriptions and JSON input schemas, exported from an actual MCP `tools/list` response. `pnpm protocol:check` rejects snapshot drift in CI. Update deliberately using `pnpm protocol:export`.
 
 For protocol 1.x, existing tool names, required input fields and the ownership/claim semantics below remain compatible. New optional fields/tools and additive result fields use a minor version; compatible repairs use a patch version. Removing tools, adding required inputs or changing ownership semantics requires a major version. Clients should ignore unknown result fields. The snapshot describes inputs; it is not a machine-validated schema for every result or a guarantee of source-level library compatibility.
 
-Successful tool replies place the same JSON object in `structuredContent` and the first text block. Additional text may contain an advisory event delta. Inspect `isError` and the operation's fields: a computed preview with `clean:false` is a successful observation of a conflict, not permission to integrate. Exceptions are MCP tool errors. Never infer successful work from the client process exit code alone.
+Successful tool replies place the same JSON object in `structuredContent` and the first text block. Additional text may contain an advisory event delta. Inspect `isError` and the operation's fields: a computed preview with `clean:false` is a successful observation of a conflict, not permission to integrate. Operational failures also return `failure` as described below. Malformed arguments, unknown tools and transport/protocol errors still use the MCP SDK error format; do not retry those blindly. Never infer successful work from the client process exit code alone.
 
 Protocol 1.2 adds optional `repository` to every tool. A global `kith mcp` connection can route calls independently to absolute Git checkout paths; it creates no project database until a project is selected. A Git checkout in the process/project context supplies a default. Without one, calls must include `repository` and otherwise return a tool error while the connection remains available. Never substitute HOME or a filesystem root. Always keep the original checkout path for a task, even when editing its isolated worktree. Capabilities and commands remain attached to their repository context, and disconnect cleanup covers every opened context. An explicit `mcp --repo` connection retains its pinned checkout and refuses a different repository argument.
 
@@ -38,8 +38,49 @@ Normal CLI/MCP status opens the engine and may migrate or reap. `kith status --o
 
 Preview refuses repositories with configured custom merge drivers because Git can execute their commands during merge-tree. It does not silently substitute a different merge policy. Actual integration can run trusted project code and still needs an appropriate verification command.
 
-## Protocol 1.3 additions (source builds)
+## Protocol 1.3 additions (0.1.4)
 
 `kith_run_dev_server` launches literal argv with an allocated port in `PORT`/`KITH_PORT` and substitutes `{port}` in arguments. It uses the existing process-group supervisor and permission boundary. Cancellation/disconnect drains execution before cleanup. It is foreground, with a default 60-second deadline and bounded output; longer-lived interactive servers should use `kith dev` in the CLI. No readiness or socket handoff is promised.
 
 `kith_begin_work` and `kith_check_and_lock_files` accept optional `waitTimeoutMs` (0–600000). Omitted fields preserve fail-fast behavior. Wait results add `waitedMs` and `waitTimedOut`; timeout keeps the normal conflict payload, with `isError:true`. Cancellation is a request error and never grants a partial claim. No FIFO ordering guarantee is added. The storage schema is unchanged; the published 0.1.3 package still uses protocol 1.2.
+
+## Protocol 1.5: compact context with explicit full details (0.1.7)
+
+MCP JSON text omits formatting whitespace without changing its data or literal strings. Contract previews remove database fingerprints while preserving file/symbol/signature, version, breaking status, owner and documentation. A write scope is not a read-dependency filter: previews draw from all scopes and include every breaking contract, even beyond the ordinary 30-record preview size. `publishedContractsComplete` and `publishedContractsOmitted` label omitted ordinary records; `contractDetails` points to `kith_get_status` with `includeContracts:true` for the full original registry. Large sets of critical changes may therefore produce larger replies; Kith does not discard them to meet a token target.
+
+Linked-module replies retain every symbol supplied by the already bounded core inspector and preserve `exportsComplete`, `ownershipAvailable`, dirty/unknown state and drift details. `totalSymbolsInFile` is null when the core cannot establish a complete list. File-edit replies retain all changed contracts, the established per-consumer breaking-change fields, removal/conflict details and warnings. Only the advisory text footer groups repeated signatures, retaining each affected file, owner and hop distance together. This grouping never changes the machine-readable `contractReport.breakingChanges` shape.
+
+`kith_get_status` defaults to current/pending tasks and reports `completedTaskCount` and `historyIncluded:false`. Its optional `includeHistory:true` returns completed tasks too. All lock records retain their identity, fencing and lease/expiry fields in both modes. `includeContracts:true` continues to return full unmodified registry records. No new tool, dependency or storage migration is introduced.
+
+## Protocol 1.4: keyed retries and operational failures (0.1.6)
+
+These additions ship in `kith-coord` 0.1.6. Existing callers can omit the new fields and retain the same ownership requirements.
+
+Mutating tools accept an optional client-generated `operationKey` (1–128 characters). Generate a fresh UUID for each logical attempt. After a timeout, resend the **same tool, original checkout, agent ID, key and arguments**. The server stores a reservation before execution and a result afterward in the existing repository database. It never executes the reserved operation a second time. A different tool, checkout or argument set with the same key returns `OPERATION_KEY_REUSED`. Explicit `sessionToken` may be supplied on another connection without changing the request identity.
+
+`kith_add_task` accepts optional `agentId` and `sessionToken`; a keyed task addition requires an already owned session. Unkeyed task additions retain their existing behavior. Heartbeats and observations (`kith_get_status`, `kith_preview_integrate`) do not accept operation keys: they must refresh or observe current state on each call.
+
+Keyed replies add `operation: { key, state, replayed }`:
+
+- `completed`: the original success **or failure** was recorded. A replay returns that historical snapshot, with no new task, command, port allocation, contract update or integration. It does not renew a lease, reacquire a claim, deliver another event delta or establish that the old result is still current. After repairing a failure, use a **new** key for the new attempt.
+- `running`: no result has been recorded and the coordinator process is still alive. `OPERATION_IN_PROGRESS` permits backoff and another read using the **same** key; it never starts another execution. A suspended process is still an owner.
+- `unknown`: the coordinator died before recording a result, or the result could not be saved. `OPERATION_OUTCOME_UNKNOWN` refuses automatic re-execution. Inspect project status, retained worktrees, command output and external side effects. A deliberate new attempt needs a new key after that review.
+
+An operation key is not a capability. Replay requires the original session token, retained internally on the owning connection or supplied explicitly on a different connection. A token from a replacement session cannot retrieve the old generation's result. The old capability may read its historical result after expiry/completion, but cannot resume, heartbeat, mutate or release a replacement generation. Raw session tokens are not saved in operation records; initial grant replays reconstruct the token from the caller's proof. If the initial grant response and connection are both lost before the caller receives a capability, possession of the key cannot recover that secret or seize the session. Inspect/recover the retained work after its owner expires.
+
+Operational tool errors set `isError:true`, preserve existing fields and add `failure: { code, message, retryable, retryAfterMs? }` to both JSON text and `structuredContent`:
+
+| Code | Retryable | Client action |
+| --- | --- | --- |
+| `CLAIM_CONFLICT`, `CLAIM_WAIT_TIMEOUT`, `MUTEX_WAIT_TIMEOUT` | Yes | Back off; use a new key for another attempt. Existing failure snapshots stay unchanged. |
+| `OPERATION_IN_PROGRESS` | Yes | Back off and resend the exact same key/request to recover its result. |
+| `OPERATION_OUTCOME_UNKNOWN` | No | Inspect effects and recovery state; never blindly repeat commands or integration. |
+| `INTEGRATION_FAILED` | No | Read `mergeResult.diagnostics`, inspect/repair the retained source worktree and normal project checks, then use a new key. |
+| `COMMAND_FAILED`, `COMMAND_TIMEOUT`, `COMMAND_OUTPUT_LIMIT`, `CANCELLED` | No | Inspect bounded output and partial effects. Cancellation/deadlines do not undo completed filesystem or external writes. |
+| `SESSION_OWNERSHIP`, `STALE_FENCING_TOKEN` | No | Establish valid current ownership; never bypass a lease or guard. |
+| `OPERATION_KEY_REUSED`, `INVALID_REQUEST` | No | Correct the request; new work needs a new key. |
+| `DATABASE_BUSY`, `STATE_UNAVAILABLE`, `OPERATION_FAILED` | No | Preserve state and diagnose. A generic storage/runtime error may occur after a side effect. |
+
+Command execution deadlines/cancellation retain captured bounded `stdout` and `stderr` where available. A computed preview with `clean:false` remains an observation, not a failed command or permission to integrate. Task-queue polling with `claimed:false` remains a successful observation of no eligible task.
+
+Reservations/results survive process restarts, including a lost response after completion. Records are not automatically expired or pruned: forgetting a key would allow a later retry to execute again. They include private command output/diagnostics; protect and preserve the complete `.coord` recovery set. This is at-most-once execution for a retained key under coordinator process failures, **not exactly-once external effects**, command rollback or a guarantee across power loss, damaged/lost storage or manually discarded history. Stop older clients before upgrading schema 2 to 3. The additive transaction preserves existing sessions, claims and command guards; older binaries reject schema 3 instead of dropping the journal. Offline observation accepts schemas 2 and 3 without migrating the original.

package/docs/reliability.md

@@ -64,7 +64,7 @@ The SQLite implementation requires Node's unflagged SQLite API: [Node SQLite doc
 
 ## Existing databases
 
-No full-text SQLite extension is required. Contracts, tasks, locks and supervised commands use the canonical tables on every supported runtime. Older derived `contracts_fts` tables are left intact but are no longer read or maintained. Stop all clients before upgrading. Do not mix versions or rely on downgrading to an older search index after new contract writes. No schema reset, new tables or automatic repair are involved.
+No full-text SQLite extension is required. Contracts, tasks, locks and supervised commands use the canonical tables on every supported runtime. Older derived `contracts_fts` tables are left intact but are no longer read or maintained. Stop all clients before upgrading. Do not mix versions or rely on downgrading to an older search index after new contract writes. Removing the old derived search machinery requires no schema reset or automatic repair. Kith 0.1.6 (protocol 1.4) adds one operation journal table in the same database; see below.
 
 ## Paths, scopes and merge boundaries
 
@@ -85,3 +85,25 @@ Passive CLI/menu observations use Git status and available file mtimes. They do
 The radar groups differing paths by checkout. **Active Kith lease** means a recorded active session with an unexpired lease, not proof of a live writer. **Retained** means its recorded sessions are completed, idle, dead or expired; it is not permission to delete the checkout. **No Kith session** means outside activity is unknown. **Ownership unavailable** means the preserved coordination snapshot could not be read; inspect `kith status --offline` or `kith recover` in that checkout. Reads never renew or reap owners. Git change counts exclude ignored files and say nothing about unpushed commits or whether cleanup is safe.
 
 The menu's path count is a review list before integration, not an urgency score or a count of colliding agents. Identical dirty copies are excluded. A path shown under several checkouts need not differ between every pair. Recorded owners are not attributed as file writers. Review the worktree copies and run normal verification through the owning session before integration; preserve unfinished work in retained checkouts.
+
+## Retrying timed-out MCP mutations
+
+Kith 0.1.6 (protocol 1.4) supports optional [operation keys and structured failures](protocol.md#protocol-14-keyed-retries-and-operational-failures-016). Reusing a key returns the original recorded result, including failures; it never repeats the mutation. A live pending owner produces a retryable in-progress response. If the result was lost between a side effect and its database commit, the outcome is unknown and automatic execution is refused. Commands can leave partial effects despite cancellation or deadlines.
+
+Replay is capability-protected historical access, not renewed ownership. Old session tokens cannot act on a replacement generation. Lost initial capability grants cannot be recovered with a key alone. Do not erase operation history to make a retry run; inspect effects and retained work before deliberately starting a new attempt. Keep the entire stopped database/sidecar set, because operation history and ownership belong to the same recovery snapshot.
+
+Schema 2 to 3 adds the journal transactionally and preserves current ownership, task state, files and process guards. A killed upgrade rolls back and can be retried. Startup refuses a schema-3 database missing its journal or required columns, rather than reconstructing an empty retry history. Stop old clients before upgrading; binaries that only support schema 2 refuse schema 3. Generic storage errors stay non-retryable because they can occur after external work. There are no new services, dependencies, retry daemons or UI controls.
+
+
+### Task handoff and cross-repository observations (0.1.7)
+
+A queued task's ownership/claims and its worktree handoff commit together. If the handoff fails, task/claim mutations roll back. Any partial filesystem output stays intact for inspection; Kith never deletes it to make a retry succeed. Reusing a saved worktree requires matching Git common-directory identity, branch and exclusive registration, no unfinished tracked/untracked changes, and HEAD matching the selected checkout's HEAD. A moved, dirty or stale checkout is refused for explicit recovery.
+
+Cross-repository advice reads explicit local TypeScript/JavaScript path aliases to tracked files in a distinct Git repository. It does not crawl folders or prove runtime compatibility. Status inspects direct aliases; concrete wildcard imports are resolved when recording edits. Inherited/referenced configuration and re-exports defer to your normal compiler and project checks. Source/config reads are capped at 64 KiB, reports at eight linked files/64 symbols and 16 KiB. Replies contain symbol names/kinds/hashes, not source initializers. MCP text replies use compact JSON without dropping fields or changing literal strings; structured responses and safety/recovery details are preserved. Partial exports suppress missing-export verdicts. Unavailable sibling ownership, Git checks or worktrees remain explicitly unavailable; advisory failure does not invalidate a successful work claim.
+
+The menu watches a selected workspace and stores recent selections. It does not search your home directory or assume project-folder names. Switching invalidates the old view immediately; late results from an earlier selection are discarded. Task prompts belong to individual Git checkouts, not a workspace parent. Observations never identify nonparticipating writers or authorize cleanup.
+
+
+### Compact MCP context (0.1.7)
+
+Compact replies preserve actionable context: all breaking contracts, linked exports within the core inspection bounds, changed contract receipts, warnings, failures and recovery instructions. They do not guess read dependencies from write scopes. Only ordinary contract previews are limited; omitted counts and a full-registry retrieval instruction are explicit. The text footer can group repeated signatures while retaining each downstream file/agent/distance relationship; machine-readable breaking alerts retain their established fields. `includeHistory:true` retrieves completed tasks, and lock identity, fencing and expiry remain visible. Savings come from formatting, repeated signatures and internal fingerprints rather than a semantic summarizer. No model calls or extra service are needed.

package/docs/roadmap.md

@@ -14,7 +14,7 @@ MCP is the default agent interface. Keep one shared ownership ledger per Git com
 4. **Followable recovery.** Exercise disconnect, expiry, failed checks, partial setup, interrupted migration and damaged-state refusal. Preserve worktrees and matching stopped database/sidecars; no automatic repair, forced claim release or deletion of `.coord`.
 5. **Exact release evidence.** Require all six Linux/macOS and both Windows jobs on the candidate, including any editor checks, plus the exact packed-package consumer. Verify registry bytes and tag workflows after publication. Maintain versioned client evidence and honest platform limits.
 
-Published 0.1.4 / protocol 1.3 has recorded clean npm and editor-registry evidence. Version 0.1.5 carries the read-only radar clarity fixes without changing the protocol. Each candidate must pass its own combined core/platform, bundled-server and clean-install gates before publication; a green prior release does not certify a new branch.
+Published 0.1.6 / protocol 1.4 has recorded clean npm and editor-registry evidence, including durable mutation retries and preserved recovery. The current usability pass simplifies activation and read-only feedback without changing ownership, storage schema or the MCP protocol. Each candidate must pass its own combined core/platform, bundled-server and clean-install gates before publication; a green prior release does not certify a new branch.
 
 ## Deferred
 

package/docs/validation/2026-10-22-editor-chats.json

@@ -0,0 +1,88 @@
+{
+  "checkedAt": "2026-10-22T20:58:43.770422+00:00",
+  "type": "Signed-in native GUI agent chats on disposable synthetic invoice task; not external adoption or production validation",
+  "platform": "macOS",
+  "versions": {
+    "kithExtension": "0.1.4 from each editor own marketplace",
+    "vscode": "1.143.0",
+    "cursor": "3.24.18"
+  },
+  "task": {
+    "description": "Implement discount and tax calculations for a synthetic invoice in two independent signed-in chats.",
+    "scopes": [
+      "src/discount.js",
+      "src/tax.js"
+    ],
+    "scopedVerification": [
+      "node --test tests/discount.test.js",
+      "node --test tests/tax.test.js"
+    ],
+    "fullVerification": "npm test",
+    "tests": 5
+  },
+  "results": {
+    "vscode": {
+      "status": "passed",
+      "commits": {
+        "main": "f528332e1af5843dc051de486412aa0ea862b5cc",
+        "kith/vscode-discount": "5183d9db42c03be38eedd0a9b039e4ea19de4988",
+        "kith/vscode-tax": "1b4d2f5862e234653b689448bea54e2cd87171ca"
+      },
+      "targetClean": true,
+      "conflictingClaimRefused": true,
+      "isolatedWorktrees": true,
+      "scopedTestsViaMutexPassed": true,
+      "failedFullVerificationPreservedTargetAndWork": true,
+      "bothChangesIntegrated": true,
+      "fullSuitePassed": true,
+      "agents": [
+        {
+          "id": "vscode-discount",
+          "statusAtCheck": "completed"
+        },
+        {
+          "id": "vscode-tax",
+          "statusAtCheck": "completed"
+        }
+      ],
+      "failedVerificationTargetUnchanged": true
+    },
+    "cursor": {
+      "status": "pending_client_usage",
+      "commits": {
+        "main": "a47ce3ee9f2c8a9a5bc3c32e219ad9ec84870da3",
+        "kith/cursor-discount": "db8b4b2b312ed2d7a88f0823f1ec0a9af72f0016",
+        "kith/cursor-tax": "92ca13b7a30b0a5f74517797e8561f735705ad7e"
+      },
+      "targetClean": true,
+      "conflictingClaimRefused": true,
+      "isolatedWorktrees": true,
+      "scopedTestsViaMutexPassed": true,
+      "failedFullVerificationPreservedTargetAndWork": true,
+      "bothChangesIntegrated": false,
+      "fullSuitePassed": false,
+      "agents": [
+        {
+          "id": "cursor-discount",
+          "statusAtCheck": "completed"
+        },
+        {
+          "id": "cursor-tax",
+          "statusAtCheck": "active"
+        }
+      ],
+      "failedVerificationTargetUnchanged": true
+    }
+  },
+  "clientConfigs": {
+    "monitoredPaths": 15,
+    "byteIdentical": true
+  },
+  "sourceChanges": false,
+  "boundaries": [
+    "Normal OS Keychain and native tool approvals; no mock Keychain for signed-in chats.",
+    "No private source, credentials or capability-bearing transcripts published.",
+    "Cursor final retry remains pending by user choice after account usage exhaustion.",
+    "Internal synthetic validation, not external adoption or production coverage."
+  ]
+}

package/docs/validation/2026-10-22-editor-marketplaces.json

@@ -0,0 +1,84 @@
+{
+  "checkedAt": "2026-10-22T20:37:24.745310+00:00",
+  "type": "internal synthetic marketplace and native host validation",
+  "extensionVersion": "0.1.4",
+  "extensionSource": "70e44620d4e24c488f2f6020809a9ccd67b1ae00",
+  "passed": true,
+  "results": [
+    {
+      "editor": "vscode",
+      "appVersion": "1.143.0",
+      "vscodeApiVersion": "1.143.0",
+      "extensionVersion": "0.1.4",
+      "search": {
+        "editor": "vscode",
+        "serviceUrl": "https://marketplace.visualstudio.com/_apis/public/gallery/extensionquery",
+        "query": "kith",
+        "searchRank": 1,
+        "extensionId": "Kith-coord.kith",
+        "version": "0.1.4",
+        "checkedAt": "2026-10-22T20:27:15.575204+00:00"
+      },
+      "marketplaceIdInstallPassed": true,
+      "nativeActivationPassed": true,
+      "nativeMcpRegistration": "Bundled Kith offered through VS Code MCP. VS Code manages server approval and start status.",
+      "nodeAutodetectionWithMinimalPathPassed": true,
+      "existingConfigurationPreservedByteForByte": true,
+      "duplicateRegistrationSuppressed": true,
+      "readOnlyObservationCreatesNoCoordinationState": true,
+      "installedPayloadMatchesValidatedRelease": true,
+      "installedWorkflowPassed": true,
+      "workflowChecks": [
+        "owned sessions, refused overlap and refused capability theft",
+        "native absolute and Git-style paths, literal brackets, internal/escaping links, isolated worktrees and distinct port leases",
+        "dirty preview refusal, committed preview, failed verification and successful retry/integration",
+        "killed MCP owner recovered with new capability and preserved worktree, then integrated",
+        "offline inspection preserves original state; tracked MCP setup/uninstall preserves integrated work",
+        "global client connects at filesystem root, routes two projects independently and refuses cross-project capability reuse",
+        "automatic setup preserves peer configuration, binds native launcher from filesystem root and restores original bytes",
+        "damaged state refused without replacing database, creating client config or losing integrated work"
+      ]
+    },
+    {
+      "editor": "cursor",
+      "appVersion": "3.24.18",
+      "vscodeApiVersion": "1.128.0",
+      "extensionVersion": "0.1.4",
+      "search": {
+        "editor": "cursor",
+        "serviceUrl": "https://marketplace.cursorapi.com/_apis/public/gallery/extensionquery",
+        "query": "kith",
+        "searchRank": 1,
+        "extensionId": "kith-coord.kith",
+        "version": "0.1.4",
+        "checkedAt": "2026-10-22T20:27:16.859036+00:00"
+      },
+      "marketplaceIdInstallPassed": true,
+      "nativeActivationPassed": true,
+      "nativeMcpRegistration": "Bundled Kith offered through Cursor MCP. Cursor manages server approval and start status.",
+      "nodeAutodetectionWithMinimalPathPassed": true,
+      "existingConfigurationPreservedByteForByte": true,
+      "duplicateRegistrationSuppressed": true,
+      "readOnlyObservationCreatesNoCoordinationState": true,
+      "installedPayloadMatchesValidatedRelease": true,
+      "installedWorkflowPassed": true,
+      "workflowChecks": [
+        "owned sessions, refused overlap and refused capability theft",
+        "native absolute and Git-style paths, literal brackets, internal/escaping links, isolated worktrees and distinct port leases",
+        "dirty preview refusal, committed preview, failed verification and successful retry/integration",
+        "killed MCP owner recovered with new capability and preserved worktree, then integrated",
+        "offline inspection preserves original state; tracked MCP setup/uninstall preserves integrated work",
+        "global client connects at filesystem root, routes two projects independently and refuses cross-project capability reuse",
+        "automatic setup preserves peer configuration, binds native launcher from filesystem root and restores original bytes",
+        "damaged state refused without replacing database, creating client config or losing integrated work"
+      ]
+    }
+  ],
+  "liveClientConfigurationPathsChecked": 15,
+  "liveClientConfigurationsByteIdentical": true,
+  "boundaries": [
+    "Native host checks do not sign in or make model calls.",
+    "SDK workflows against installed bundled servers are distinct from model-driven GUI chats.",
+    "Results apply to recorded versions, not all clients or later extension releases."
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kith-coord",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Local coordination for cooperating coding agents: work claims, isolated worktrees, shared resources, and verified integration without a hosted service.",
   "type": "module",
   "bin": {

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.connorhriley/kith",
   "title": "Kith",
   "description": "Coordinate coding agents with work claims, Git worktrees, shared resources and verified integration.",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "repository": {
     "url": "https://github.com/connorhriley/kith",
     "source": "github"
@@ -23,7 +23,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "kith-coord",
-      "version": "0.1.5",
+      "version": "0.1.7",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {