kith-coord 0.1.1 → 0.1.2

package/docs/client-validation.md

@@ -60,3 +60,9 @@ On 2026-10-20, macOS / Node 22.23.3, [Cursor CLI 2026.10.19-6bbf2c4](validation/
 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

@@ -64,12 +64,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.1`) 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.1","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.

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kith-coord",
-  "version": "0.1.1",
+  "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
+        }
+      ]
+    }
+  ]
+}