kith-coord 0.1.0 → 0.1.2

package/docs/client-validation.md

@@ -7,13 +7,14 @@ pnpm install --frozen-lockfile
 pnpm build
 node scripts/validate-native-clients.mjs --client codex --output artifacts/codex.json
 node scripts/validate-native-clients.mjs --client claude --output artifacts/claude.json
+node scripts/validate-native-clients.mjs --client cursor --output artifacts/cursor.json
 ```
 
-Use `--scenario isolated` or `--scenario shared` for a single run. Claude also runs `--scenario hook-failure` by default, replacing the pre-hook executable with a missing path and proving that its native Write is denied. Both worktree modes integrate an isolated worktree. The isolated scenario gives Codex an MCP-owned session; shared mode forwards a capability anchored to the runner. Claude always inherits a session so its generated edit hooks and MCP server share ownership.
+Use `--scenario isolated` or `--scenario shared` for a single run. Claude and Cursor also run `--scenario hook-failure` by default, replacing the pre-hook executable with a missing path and proving that a native edit is denied. Both worktree modes integrate an isolated worktree. The isolated scenario gives Codex an MCP-owned session; shared mode forwards a capability anchored to the runner. Claude and Cursor always inherit a session so its generated edit hooks and MCP server share ownership.
 
-Each run uses a disposable Git repository with spaces and an apostrophe in its path. A peer holds a source file. The native client must receive the conflict (Claude also attempts a native edit that its pre-hook must deny), choose a separate scope, edit its returned worktree, report the edit, run a supervised MCP command across multiple lease periods, encounter an expected verification failure, inspect retained ownership, retry completion successfully, and release ownership. The runner checks native tool events, exact protected/integrated bytes, contracts, task completion, verification diagnostics, Git HEAD and remaining locks. An exit-zero client that merely reports a permission failure fails validation. Results are version-specific evidence, not certification of every client release or GUI.
+Each run uses a disposable Git repository with spaces and an apostrophe in its path. A peer holds a source file. The native client must receive the conflict (Claude and Cursor also attempt a native edit that their pre-hook must deny), choose a separate scope, edit its returned worktree, report the edit, run a supervised MCP command across multiple lease periods, encounter an expected verification failure, inspect retained ownership, retry completion successfully, and release ownership. The runner checks native tool events, exact protected/integrated bytes, contracts, task completion, verification diagnostics, Git HEAD and remaining locks. An exit-zero client that merely reports a permission failure fails validation. Results are version-specific evidence, not certification of every client release or GUI.
 
-The Codex invocation ignores user configuration/rules, uses a workspace-write sandbox, passes the generated TOML server values as invocation overrides, and approves only that fixture's Kith MCP tools for unattended execution. It does not test persisted project trust or GUI discovery; review and trust project settings in your normal client before use. Normal `kith init --only codex` does not change approval policy or mark a real project trusted. Claude loads project settings, restricts MCP to the generated config, permits its native editor and Kith tools, denies unattended permission prompts, and uses a $2 per-scenario budget. The runner has a three-minute deadline and bounded output. It does not log in, change global configuration, or create subagents.
+The Codex invocation ignores user configuration/rules, uses a workspace-write sandbox, passes the generated TOML server values as invocation overrides, and approves only that fixture's Kith MCP tools for unattended execution. It does not test persisted project trust or GUI discovery; review and trust project settings in your normal client before use. Normal `kith init --only codex` does not change approval policy or mark a real project trusted. Claude loads project settings, restricts MCP to the generated config, permits its native editor and Kith tools, denies unattended permission prompts, and uses a $2 per-scenario budget. Cursor uses its installed `agent` executable (override with `--binary /absolute/path`), generated project MCP/hook settings, fixture trust, automatic MCP approval and its enabled sandbox. It uses your existing Cursor login/default model and can consume Cursor usage; no price cap is available in this runner. The CLI can record trust/session metadata for the disposable fixture. The runner has a three-minute deadline and bounded output, does not log in or edit global client settings directly, and never requests subagents. Model-driven runs currently require macOS/Linux process groups for bounded cleanup.
 
 Reports contain client/version, platform, scenario outcomes and tool names. Raw MCP results include bearer capabilities and must not be published. No raw transcript is saved by default. Keep credentials out of repository settings; generated Codex config forwards environment variable names with `env_vars`.
 
@@ -43,9 +44,25 @@ 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 application discovery, hook invocation/failure handling and model workflows remain unvalidated; 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. 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.
 
 
 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).
 
 The [first Codex attempt](validation/2026-10-20-adoption-codex-first-attempt.json) stopped after its mutex call without completing the fixture; the runner correctly marked it failed despite the client exiting zero. Its cause was not established. A diagnostic rerun passed and now records redacted outcome fields without raw tool arguments/results. Keep the incomplete attempt visible: model-driven validation can vary, and one successful rerun does not explain an earlier incomplete workflow.
+
+
+On 2026-10-20, macOS / Node 22.23.3, [Cursor CLI 2026.10.19-6bbf2c4](validation/2026-10-20-cursor-cli.json) passed the real model workflow with an inherited session: native peer-edit denial, worktree editing, edit reporting, renewable command supervision, failed verification/retry, integration and released claims. A temporary wrapper forwarded the exact generated guard and recorded only path/exit status; native editor events and repository state were also checked. The separate [unavailable-guard check](validation/2026-10-20-cursor-hook-unavailable.json) passed: one native edit attempt was denied and the marker stayed absent. Raw capability-bearing transcripts were not saved.
+
+
+## Native Windows
+
+Version 0.1.1 has real `windows-latest` SDK/Node/Git workflow evidence on [Node 22.13.0](validation/2026-10-20-windows-node-22.13.0.json) and [Node 24](validation/2026-10-20-windows-node-24.json). These checks use two actual MCP server processes, not path mocks: owned sessions and refused theft/overlap, native and Git-style paths, literal bracket filenames, internal/escaping directory junctions, separate worktrees, port leases, dirty-preview refusal, failed verification/retry, integration, killed-owner recovery with a new capability, unchanged-state offline inspection, generated Node-based MCP startup and conservative uninstall. Git's configured checkout line endings are respected; failed verification must preserve the source's exact existing bytes. The installed package is tested from a fresh npm cache: source pushes use a packed archive, while matching release tags install the exact public registry version. The separate [Windows workflow](../.github/workflows/windows.yml) runs on pushes/PRs and retains redacted JSON; it also checks damaged-state refusal without replacing state or losing work.
+
+This is **partial native Windows support**, included in npm `kith-coord@0.1.1`. `kith_run_with_mutex` refuses before execution or lease/guard acquisition because its cleanup guarantee needs POSIX process groups. Native shell hooks/shims are refused during setup before writes; use `kith init --mcp-only` or WSL for the full workflow. `doctor` reports the platform limitation and exits nonzero. This does not certify a Windows model-driven client or GUI; the native Cursor runs above are on macOS. Windows backup files are flushed before client writes, but Node cannot flush directory entries there, so setup-ledger durability across sudden power loss is not promised.
+
+## External real-task report: Claude Code and OpenCode
+
+On 2026-10-21, [AgentScrum's maintainer reported](https://github.com/KoalaLyfestyle/AgentScrum/issues/39#issuecomment-6306658975) a trial of published `kith-coord@0.1.1` on macOS Darwin 27.0.0, Node 24.21.0 and Git 2.54.0, with Claude Code 2.1.305 and OpenCode 2.0.32 (DeepSeek V4.1 Flash). OpenCode used a manually written local MCP config; all 13 tools loaded. An overlapping claim on `src/services/scrum.ts` was refused, then accepted after the first agent completed. The maintainer reported both actual fixes integrated with verification passing (145 tests on the combined trial branch). [PR #42](https://github.com/KoalaLyfestyle/AgentScrum/pull/42) and [PR #43](https://github.com/KoalaLyfestyle/AgentScrum/pull/43) were subsequently merged into their `main`, after rebuilding PR branches to remove inherited setup and prior-task commits.
+
+This is an attributed external workflow report for those versions, not a controlled native OpenCode certification. It exposed oversized status/edit responses, token visibility in client logs, launcher PATH differences and friction adapting integration branches to independent PRs. See [workflow guidance](usage.md). No OpenCode init adapter or new client trust/permissions configuration is implied.

package/docs/integrations.md

@@ -1,6 +1,6 @@
 # Client integrations
 
-Build and link the checkout first. Generated configurations use the `kith` executable already on PATH; they do not download an unverified package at hook execution time.
+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 |
 | --- | --- |
@@ -50,7 +50,7 @@ Cursor's native `preToolUse`/`postToolUse` adapter handles `Shell`, `Write` and
 
 ## Diagnose and undo setup
 
-`kith doctor` checks Node/Git versions, supported platform, the CLI on PATH, parseable MCP configuration, recorded session environment, guard failure policy and worktree health. It does not execute configured hooks, establish project trust, authenticate clients or prove that a supplied token is valid. Windows is reported unvalidated. A missing/broken check exits nonzero and leaves configuration/state untouched.
+`kith doctor` checks Node/Git versions, supported platform, the CLI on PATH, parseable MCP configuration, recorded session environment, guard failure policy and worktree health. It does not execute configured hooks, establish project trust, authenticate clients or prove that a supplied token is valid. Native Windows is reported limited: MCP coordination is tested, while supervised mutex commands and shell hooks require macOS/Linux or WSL. A missing/broken check exits nonzero and leaves configuration/state untouched.
 
 Before writing selected client files, init persists private original-byte/mode backups in the shared coordination directory's `setup/` subdirectory. Each checkout has its own ledger. An exclusive `setup.lock` serializes cooperative setup/uninstall. A partial write can leave configuration requiring review; original backups remain available. Stop clients and inspect a stale lock before removing it manually. Never delete the ledger as routine cleanup.
 
@@ -64,12 +64,17 @@ 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.0`) 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.2`) 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.0","kith","mcp","--repo","/absolute/checkout"]}}}
+{"mcpServers":{"kith":{"command":"npx","args":["--yes","--package","kith-coord@0.1.2","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.
+
+
+## Native Windows setup
+
+Version 0.1.1 generates MCP configuration using the current absolute Node executable and built CLI path, avoiding `.cmd` launcher/shell quoting. Use `kith init --mcp-only` and review the generated paths; rerun setup if the Node/Kith installation moves. Native Windows setup refuses shell hooks and shims before configuration writes. Supervised mutex commands are also refused. Use WSL for those full workflows. The `npx` example above is a POSIX launcher; do not assume a native Windows client can spawn `npx.cmd` directly. See [platform proof and limits](client-validation.md#native-windows).

package/docs/path-and-scope-rules.md

@@ -36,7 +36,7 @@ Existing literal path prefixes are physically resolved before containment checks
 
 A wildcard can hide a symlink below its literal prefix. When a lexical comparison is disjoint, Kith checks relevant filesystem entries in active checkouts and retains exclusion if an alias makes the result uncertain. Scan errors or the 10,000-entry scan bound also retain exclusion. This favors extra conflicts over overlapping access. Release scopes or use narrower literal prefixes to reduce uncertainty.
 
-Path checks assume a stable layout during the check/write boundary. They do not provide protection against a hostile process swapping symlinks concurrently, hardlink aliases or clients bypassing Kith. Windows path behavior remains unvalidated.
+Path checks assume a stable layout during the check/write boundary. They do not provide protection against a hostile process swapping symlinks concurrently, hardlink aliases or clients bypassing Kith. Current source exercises native Windows absolute/Git-style concrete paths and internal/escaping directory junctions in the platform workflow. Concrete native Windows file paths accept backslash separators; scope expressions still use the documented forward-slash grammar. Native shell hooks remain unsupported.
 
 ## Integration and conflicts
 

package/docs/protocol/tools.v1.json

@@ -1,5 +1,5 @@
 {
-  "protocolVersion": "1.0.0",
+  "protocolVersion": "1.1.0",
   "tools": [
     {
       "name": "kith_start_session",
@@ -361,6 +361,10 @@
           },
           "sessionToken": {
             "type": "string"
+          },
+          "includeContracts": {
+            "type": "boolean",
+            "description": "Include the full contract registry. Default false keeps frequent status polls compact; contractCount always reports its size."
           }
         },
         "additionalProperties": false,
@@ -407,7 +411,7 @@
           },
           "mergeBranch": {
             "type": "string",
-            "description": "If work was done on a worktree/branch, run Speculative Merge Train to integrate it"
+            "description": "Source branch to integrate, not the destination. Defaults to the registered agent branch; destination is the selected repository checkout current branch. Omit for claims-only work without a registered branch."
           },
           "verificationCmd": {
             "type": "string",

package/docs/protocol.md

@@ -1,10 +1,12 @@
-# Kith coordination protocol 1.0
+# Kith coordination protocol 1.1
 
 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.
 
 ## Versioning and schemas
 
-`KITH_PROTOCOL_VERSION` and status responses advertise `1.0.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 13 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`.
+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.1.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 13 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.
 
@@ -12,7 +14,7 @@ Successful tool replies place the same JSON object in `structuredContent` and th
 
 ## Sessions and claims
 
-- `kith_start_session` or `kith_begin_work` grants a random session capability for a unique `agentId`. The owning MCP connection retains it. Another connection needs the capability to resume that generation; an ID is not authorization. Tokens are returned at grant/resume and must not be logged. Public status omits capabilities and their hashes.
+- `kith_start_session` or `kith_begin_work` grants a random session capability for a unique `agentId`. The owning MCP connection retains it. Another connection needs the capability to resume that generation; an ID is not authorization. Omit `sessionToken` on subsequent calls on the owning connection. Tokens are returned at grant/resume, so client transcripts can contain capabilities and must stay private. Public status omits capabilities and their hashes.
 - `kith_heartbeat` renews an owned active generation before expiry (five minutes by default). It cannot revive an expired or completed generation. Engine startup may reap expired/dead owners and requeue unfinished tasks. Active supervised command guards remain until shutdown is confirmed.
 - `kith_begin_work` declares an intent and atomically acquires its supported scope claims. An overlapping exclusive claim returns a conflict. Use `isolateWorktree:true`, and edit only the returned `worktree.worktreePath`. Worktrees separate files while claims describe cooperative ownership across checkouts.
 - `kith_check_and_lock_files` acquires file/glob/symbol claims using fencing generations. See [scope rules](path-and-scope-rules.md); unsupported patterns are rejected. Direct filesystem writes and bypassed hooks are outside this protocol's enforcement boundary.
@@ -22,7 +24,7 @@ Successful tool replies place the same JSON object in `structuredContent` and th
 
 ## Workspace observation and integration
 
-`kith_get_status` preserves agents, tasks, locks, contracts, conflicts, resources, merge queue, quarantine and events. It adds `protocolVersion`, `mutexWaiters` (ticket order), `commandGuards`, and `workspaces`. Normal status observes active owners; offline inspection also includes retained recorded worktrees. Each workspace reports its path, recorded and actual branch, HEAD, dirty paths (including rename sources), last commit time/age, last heartbeat, lease expiry, availability, and dirty-file overlaps with active peers. `ahead`/`behind` compare against `comparisonBase`, the selected integration checkout's observed HEAD. Commit age is descriptive; an old commit is not evidence of a dead agent. Missing/unreadable workspaces are marked unavailable, not clean. Git observations are sequential snapshots, not a transaction over all files/checkouts.
+`kith_get_status` preserves agents, tasks, locks, conflicts, resources, merge queue and quarantine. In protocol 1.1, frequent MCP polls return `contracts:[]`, `contractCount` and `contractsIncluded:false` by default; pass `includeContracts:true` to inspect the full registry. CLI `kith status` and `kith contract list` still include full contract records. Edit reports publish only new or changed contract metadata, retaining unchanged records without repeating them. It adds `protocolVersion`, `mutexWaiters` (ticket order), `commandGuards`, and `workspaces`. Normal status observes active owners; offline inspection also includes retained recorded worktrees. Each workspace reports its path, recorded and actual branch, HEAD, dirty paths (including rename sources), last commit time/age, last heartbeat, lease expiry, availability, and dirty-file overlaps with active peers. `ahead`/`behind` compare against `comparisonBase`, the selected integration checkout's observed HEAD. Commit age is descriptive; an old commit is not evidence of a dead agent. Missing/unreadable workspaces are marked unavailable, not clean. Git observations are sequential snapshots, not a transaction over all files/checkouts.
 
 `kith_preview_integrate` requires an owned registered worktree on its recorded branch, committed source changes, and a clean integration target. It reports frozen `sourceHead`/`targetHead`, branch names, `clean`, and exact Git conflict paths. Dirty inputs return `ok:false` and are not checkpointed. Git may write unreachable merge-tree objects, but preview never stages files, advances refs or rewrites worktree contents. Authorization can renew the session and deliver an event delta. A clean preview does not run project verification or guarantee a later integration: inputs can change.
 

package/docs/reliability.md

@@ -33,11 +33,13 @@ These are test scenarios, not universal guarantees. CI coverage and real usage n
 
 **Bash recovery.** Snapshots skip large files, symlinks, and generated/dependency directories. One snapshot is stored per agent. Overlapping commands can replace snapshots, and a shared-workspace snapshot cannot distinguish a sibling's legitimate concurrent edits from a command's unauthorized edits. The default saves current and pre-command recovery copies without changing workspace bytes. Explicit library callers can opt into `restoreLockedFiles: true` only when they control all writers; restoration is best effort and can restore older bytes. Prefer worktrees. This is not a safe attribution or security mechanism.
 
+**Native Windows.** Version 0.1.1 validates MCP claims, worktrees, ports, integration, killed-owner recovery and conservative setup. Supervised mutex commands and shell hooks remain refused; use macOS/Linux or WSL for those guarantees. See [platform evidence](client-validation.md#native-windows). These fixes are included in npm `kith-coord@0.1.1`.
+
 **Ports.** A reservation coordinates Kith clients but releases its OS probe socket immediately. Another process can bind the port before your service does. Handle bind failures.
 
 **Git.** Integration targets the currently checked-out branch, not a hardcoded main branch. External Git writers can race with integration. Dependency hydration and speculative verification may run project code with your privileges. Verification uses a shared dependency symlink in the staging tree; choose checks that do not mutate shared dependencies. Worktree hydration can copy `.env` files; treat those worktrees as sensitive.
 
-**Configuration.** Preflight refuses malformed selected configuration before writes. Private setup backups are persisted before client-file writes; disk failure can still leave partial configuration requiring inspection. Uninstall restores only unchanged recorded writes and preserves user edits, coordination state and the ignore rule. Custom Git hooks and third-party hook managers require manual integration. See [setup recovery](integrations.md#diagnose-and-undo-setup).
+**Configuration.** Preflight refuses malformed selected configuration before writes. Private setup backups are persisted before client-file writes; disk failure can still leave partial configuration requiring inspection. Backup files are flushed on Windows, but Node cannot flush parent directory entries there; setup-ledger survival across sudden power loss is not guaranteed. Uninstall restores only unchanged recorded writes and preserves user edits, coordination state and the ignore rule. Custom Git hooks and third-party hook managers require manual integration. See [setup recovery](integrations.md#diagnose-and-undo-setup).
 
 ## Recovery
 

package/docs/roadmap.md

@@ -28,7 +28,7 @@ Cursor native hook payload/command fixtures, enforcement modes, private setup ba
 
 ## 5. Public project and release operations
 
-The canonical upstream is established. The package identity is `kith-coord` (CLI `kith`); release checks include an actual installed-package MCP consumer. Input schemas and claim/status semantics are recorded under protocol 1.0 with a CI drift check. Maintain registry ownership, maintainer access, security/moderation contacts and the decision process. Private vulnerability reporting is enabled on the canonical upstream. Run the CI matrix on real pull requests. Publish a prerelease only after a packed-package clean-install check, dependency review, documented support matrix, changelog, rollback procedure, and end-to-end demo. Add provenance and automated publishing after ownership and credentials are established.
+The canonical upstream is established. The package identity is `kith-coord` (CLI `kith`); release checks include an actual installed-package MCP consumer. Input schemas and claim/status semantics are recorded under protocol 1.1 with a CI drift check. Maintain registry ownership, maintainer access, security/moderation contacts and the decision process. Private vulnerability reporting is enabled on the canonical upstream. Run the CI matrix on real pull requests. Publish a prerelease only after a packed-package clean-install check, dependency review, documented support matrix, changelog, rollback procedure, and end-to-end demo. Add provenance and automated publishing after ownership and credentials are established.
 
 ## 6. Adaptability after the core is sound
 

package/docs/usage.md

@@ -2,7 +2,7 @@
 
 ## Recommended: MCP and isolated worktrees
 
-Connect through the [MCP-only client setup](integrations.md). Each parallel agent uses its own MCP connection and worktree. No shell exports are needed when using only MCP. The connection retains its granted capability; another connection needs that capability to resume the same ID.
+Connect through the [MCP-only client setup](integrations.md). Each parallel agent uses its own MCP connection and worktree. No shell exports are needed when using only MCP. Omit `sessionToken` on subsequent calls on the same connection; the initial grant reply still contains it, so keep client transcripts private. The connection retains its granted capability; another connection needs that capability to resume the same ID.
 
 Call these tools on the same connection:
 
@@ -17,6 +17,14 @@ kith_complete_work   {"agentId":"auth-worker","verificationCmd":"pnpm typecheck"
 
 Use a different ID and nonoverlapping scope for another agent. An overlapping exclusive scope returns a tool error. Commands run with the MCP server permissions and require client approval; their working directory defaults to the registered worktree. Keep the connection open and heartbeat before the default five-minute session expiry. See the runnable [two-client example](../examples/two-agents.mjs).
 
+## Keep existing PR branches and checks
+
+For independent PRs, create each task's Git worktree from the intended PR base first, connect Kith to that worktree and use a fresh agent ID with `isolateWorktree:false`. Keep the existing PR/review/merge process. Kith-created worktrees branch from the selected integration checkout's current HEAD; they inherit its setup and earlier integrated commits.
+
+Successful completion ends the session and retains its worktree. Run owned commands before completing, or start a fresh session for later maintenance. A refused claim can leave an active session without locks; it can retry on the same connection or expire normally. Status `conflicts` describes current detected file conflicts, not a history of refused scope claims.
+
+Integration refuses a target with uncommitted or untracked work to preserve it. Commit or preserve those files explicitly, use a clean integration checkout, or keep the existing PR workflow above. Do not blanket-ignore unknown files to silence the guard. The supervised command runner uses the server's permissions, including network access; it is not a sandbox. `verificationCmd` is an explicit shell string; mutex commands use literal argv.
+
 ## CLI fallback: keep the owning shell alive
 
 CLI commands and Claude edit hooks need the same capability environment. Start from one persistent shell, then launch hook clients from it. Separate stateless shell calls do not preserve these exports or the owning shell process.

package/docs/validation/2026-10-20-cursor-cli.json

@@ -0,0 +1,38 @@
+{
+  "client": "cursor",
+  "version": "2026.10.19-6bbf2c4",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_start_session",
+        "kith_get_status",
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "failed verification and successful retry",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true
+}

package/docs/validation/2026-10-20-cursor-hook-unavailable.json

@@ -0,0 +1,18 @@
+{
+  "client": "cursor",
+  "version": "2026.10.19-6bbf2c4",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "hook-failure",
+      "passed": true,
+      "checks": [
+        "native edit attempted once",
+        "tool denied",
+        "marker absent"
+      ]
+    }
+  ],
+  "passed": true
+}

package/docs/validation/2026-10-20-windows-node-22.13.0.json

@@ -0,0 +1,17 @@
+{
+  "platform": "win32",
+  "node": "v22.13.0",
+  "passed": true,
+  "phase": "complete",
+  "checks": [
+    "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",
+    "unsupported process-group supervision refused without execution or leaked guards",
+    "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"
+  ],
+  "git": "git version 2.56.0.windows.2",
+  "sourceCommit": "5babcfee7fd8977352f3b58ac9e54fdd45e2ce79",
+  "hostedRun": "https://github.com/connorhriley/kith/actions/runs/39408240569"
+}

package/docs/validation/2026-10-20-windows-node-24.json

@@ -0,0 +1,17 @@
+{
+  "platform": "win32",
+  "node": "v24.21.0",
+  "passed": true,
+  "phase": "complete",
+  "checks": [
+    "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",
+    "unsupported process-group supervision refused without execution or leaked guards",
+    "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"
+  ],
+  "git": "git version 2.56.0.windows.2",
+  "sourceCommit": "5babcfee7fd8977352f3b58ac9e54fdd45e2ce79",
+  "hostedRun": "https://github.com/connorhriley/kith/actions/runs/39408240569"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kith-coord",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local coordination for cooperating coding agents: work claims, isolated worktrees, shared resources, and verified integration without a hosted service.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist",
+    "server.json",
     "README.md",
     "LICENSE",
     "docs",
@@ -81,5 +82,6 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
-  }
+  },
+  "mcpName": "io.github.connorhriley/kith"
 }

package/server.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.connorhriley/kith",
+  "title": "Kith",
+  "description": "Coordinate coding agents with work claims, Git worktrees, shared resources and verified integration.",
+  "version": "0.1.2",
+  "repository": {
+    "url": "https://github.com/connorhriley/kith",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/connorhriley/kith#quick-start",
+  "icons": [
+    {
+      "src": "https://raw.githubusercontent.com/connorhriley/kith/main/assets/brand/avatar.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "256x256"
+      ]
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "kith-coord",
+      "version": "0.1.2",
+      "runtimeHint": "npx",
+      "runtimeArguments": [
+        {
+          "type": "named",
+          "name": "--yes"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      },
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "mcp"
+        },
+        {
+          "type": "named",
+          "name": "--repo",
+          "description": "Absolute path to the Git checkout to coordinate. Git 2.38+ and Node 22.13+ (22.x) or 24+ required.",
+          "format": "filepath",
+          "isRequired": true
+        }
+      ]
+    }
+  ]
+}