kith-coord 0.0.0-stage → 0.1.1

package/docs/sessions-and-mutexes.md

@@ -0,0 +1,97 @@
+# Sessions, ownership, and supervised commands
+
+## Start through MCP
+
+For agents, prefer `kith_begin_work` with a unique ID, explicit scopes and `isolateWorktree: true`. One persistent MCP connection retains its capabilities internally. Edit only the returned worktree, report edits with `kith_record_file_edit`, run serialized commands with `kith_run_with_mutex`, and complete with a project verification command. No environment exports are required for MCP-only setup. Keep the connection alive and heartbeat before expiry. See [client setup](integrations.md) and [examples](usage.md).
+
+## Share a session with CLI and hooks
+
+A session has a unique agent ID, a random 256-bit capability, a generation (epoch), a kernel process identity, and an expiry. An ID alone grants no ownership. The database stores a hash of the capability; public agent records and event/status responses omit it.
+
+For a terminal workflow, initialize the environment before launching an agent client:
+
+```sh
+eval "$(kith session start --agent auth-worker --owner-pid "$$" --shell)"
+kith begin --title "Refresh authentication" --scope "src/auth/**" --worktree
+# Edit in the returned worktreePath.
+# Launch the hook-enabled client from this environment.
+kith heartbeat
+kith complete
+unset KITH_AGENT_ID KITH_SESSION_TOKEN
+```
+
+`--shell` emits quoted exports for `KITH_AGENT_ID` and `KITH_SESSION_TOKEN`. Treat the token like a password: do not paste it into issues, commits, or logs. Passing `--session-token` explicitly is supported, but an environment variable avoids placing it in the command line.
+
+CLI sessions are anchored to their parent process unless `--owner-pid` is supplied. Shell export mode requires `--owner-pid "$$"`: sh/bash command substitution can create a transient parent, so the outer shell PID must be passed explicitly. Library and MCP sessions default to their own process. Resuming a session does not rebind that anchor. Keep the owner process alive; use heartbeats before the default five-minute expiry. Completed, expired, and replaced capabilities cannot renew or mutate the new owner’s state.
+
+`kith session end` abandons a session and requeues unfinished tasks. `kith complete` explicitly completes work. To reuse a completed/expired ID intentionally, create a new generation:
+
+```sh
+eval "$(kith session start --agent auth-worker --new --owner-pid "$$" --shell)"
+```
+
+`--new` does not steal a live session. Worktree paths are retained across generations. After successful worktree integration, use a new maintenance session to run `kith worktree remove`; changed, untracked, and ignored files still prevent removal.
+
+## MCP ownership
+
+`kith_begin_work`, `kith_claim_next_task`, and `kith_start_session` return a session token when they register or resume a session. A single stdio connection retains its granted capabilities internally. Another connection must explicitly present the capability to resume the same live ID. All agent-scoped mutation tools accept an optional `sessionToken`; a mixed CLI/hook/MCP client can inherit `KITH_AGENT_ID` and `KITH_SESSION_TOKEN` instead.
+
+`kith_heartbeat` renews an active owned session. `kith_get_status` without an ID is a public read; supplying an ID also consumes that session’s event cursor and requires ownership. Responses provide `structuredContent`, a separately parseable JSON text block, and any coordination delta in another text block. Tool conflicts set `isError: true`.
+
+Sessions started by the MCP process are abandoned on connection close; unfinished tasks are requeued. A hard crash is reclaimed by another operation’s process/expiry scan. A CLI command sharing that capability stops when its owning MCP session is lost.
+
+The protocol response format follows the [MCP tool-result specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+## Supervised mutex commands
+
+```sh
+kith mutex --name package-install --lease-ms 30000 --wait-ms 60000 --timeout-ms 600000 -- pnpm install
+```
+
+The wait timeout defaults to 60 seconds. Execution has no timeout unless `--timeout-ms` is supplied. The mutex lease defaults to five minutes and is renewed at roughly one-third of the lease duration. Output streams to the terminal. Child exit statuses are preserved. SIGINT/SIGTERM cancel queued or running work; the CLI exits with 130/143 after cleanup.
+
+A standalone mutex invocation without a pre-existing capability creates a temporary session anchored to that invocation. Reusing a live agent ID still requires its capability.
+
+The runner records an execution guard before starting a detached process-group leader. The leader cannot launch the command until its group has been recorded and the supervisor sends a private IPC start message. A live group blocks competing acquisitions even if the resource lease or agent session has expired. If renewal fails, cancellation occurs, output exceeds its configured limit, or an execution timeout fires, Kith terminates the group before releasing the guard. It escalates from SIGTERM to SIGKILL when needed, checks the recorded group-leader identity before signalling, and bounds shutdown waits. Signal-permission errors are contained; an unconfirmed shutdown retains its guard. A worker loses permission to run when its supervisor’s IPC connection closes.
+
+FIFO tickets live separately from the current resource lease, so releasing a mutex preserves queue order. Cancelled, dead, expired, and replaced-session waiters are pruned. Concurrent commands from the same session also serialize. Package-manager shims recognize an existing supervised package-install context, so an install wrapped explicitly in that mutex does not deadlock by reacquiring itself. This context marker is cooperative, not a security boundary. A general session heartbeat does not renew mutex leases: manual lease users must call `renewMutex` with the exact acquisition token.
+
+This uses [Node’s POSIX detached-process support](https://nodejs.org/download/release/v22.23.0/docs/api/child_process.html). Commands must keep protected work in the supervised process group. Deliberately detached daemons, remote jobs, privileged processes that cannot be terminated, and malicious same-user code require a different lock/enforcement boundary. If Kith cannot prove that a guarded group stopped, it retains the guard and fails closed rather than granting a second runner.
+
+## Library use
+
+`executeWithMutex` is asynchronous. Await it before closing the engine; `close()` refuses an engine with active supervised commands.
+
+```js
+import { KithEngine } from 'kith-coord';
+const engine = new KithEngine('/absolute/path/to/repository');
+try {
+  const session = engine.fencing.registerAgent({ id: 'worker' });
+  // Another engine may resume with: fencing.resumeSession('worker', session.sessionToken).
+  const result = await engine.broker.executeWithMutex({
+    agentId: 'worker', mutexName: 'install', command: ['pnpm', 'install'],
+    leaseDurationMs: 30_000, commandTimeoutMs: 600_000,
+  });
+  console.log(result.exitCode);
+} finally { engine.close(); }
+```
+
+The API also accepts an AbortSignal, `timeoutMs` for queue waiting, `killGraceMs`, output callbacks, and `maxOutputBytes` (16 MiB by default). Resource renew/release operations require their exact fencing token, including rejection of invented future tokens.
+
+## Upgrade from schema 1
+
+Stop all old Kith clients and running commands before upgrading. The schema-2 migration invalidates legacy sessions that have no capabilities, clears their coordination leases/conflicts, and requeues unfinished tasks. It preserves workspace files, worktrees, snapshots, and quarantine copies. Create fresh sessions after upgrading. Do not run an old binary against the upgraded database.
+
+For a database backup, stop writers and use a SQLite-aware backup or preserve the database together with its WAL/SHM files. Do not copy a live `state.db` alone and assume it is complete. Broader backup/restore and downgrade tooling remains future work.
+
+## Commands from sandboxed MCP clients
+
+On the validated macOS Codex version, the sandboxed native shell cannot inspect process identities, so direct CLI mutex execution fails closed with `Cannot inspect mutex waiter process`. Use `kith_run_with_mutex` on the already-owned MCP connection instead:
+
+```json
+{"agentId":"worker","mutexName":"package-install","command":["pnpm","install"],"leaseDurationMs":30000,"commandTimeoutMs":600000}
+```
+
+The executable and arguments remain separate. The working directory defaults to the registered worktree (otherwise the repository); a supplied `cwd` must resolve inside that root. The server renews the mutex while the command runs and stops it on request cancellation or connection loss, including borrowed sessions. A disconnected borrowed session retains its original owner after its command stops. Nonzero command exits set `isError: true` and retain the actual `exitCode`. Execution defaults to a 60-second timeout and 64 KiB output limit; bounded overrides are supported. Increase the client's MCP tool timeout as needed for longer commands.
+
+This tool runs with the coordinator process permissions, outside the native client's command sandbox. Review and approve it as command execution. Cwd validation selects the working directory; it does not contain what a program can access. Use isolated worktrees and declared scopes for cooperating writers. Session capabilities never need to appear in the command arguments.

package/docs/usage.md

@@ -0,0 +1,101 @@
+# MCP, CLI and library workflows
+
+## 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.
+
+Call these tools on the same connection:
+
+```text
+kith_begin_work      {"agentId":"auth-worker","title":"Refresh authentication","scopeGlobs":["src/auth/**"],"isolateWorktree":true}
+# Edit files under the returned worktree.worktreePath.
+kith_record_file_edit {"agentId":"auth-worker","filePath":"src/auth/middleware.ts"}
+kith_run_with_mutex  {"agentId":"auth-worker","mutexName":"project-checks","command":["pnpm","typecheck"]}
+kith_heartbeat       {"agentId":"auth-worker"}
+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).
+
+## 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.
+
+Run from the repository root, or pass `--repo /absolute/path`:
+
+```sh
+eval "$(kith session start --agent auth-worker --owner-pid "$$" --shell)"
+kith begin --agent auth-worker --title "Refresh authentication" --scope "src/auth/**" --worktree
+# Edit in the worktreePath returned in the JSON result.
+kith status
+kith heartbeat --agent auth-worker
+kith complete --agent auth-worker --verify "pnpm typecheck"
+# Open a maintenance generation to remove the retained worktree explicitly.
+eval "$(kith session start --agent auth-worker --new --owner-pid "$$" --shell)"
+kith worktree remove --agent auth-worker
+kith session end
+unset KITH_AGENT_ID KITH_SESSION_TOKEN
+```
+
+Quote globs so the shell does not expand them. CLI scopes are comma-separated. Use `file:src/routes/[id]/page.tsx` for a literal filename containing glob syntax; see [scope grammar and discovery](path-and-scope-rules.md). An ID alone cannot resume another session. Dead or expired sessions release coordination resources when a mutating operation reaps them. Active supervised command guards survive expiry until shutdown is confirmed.
+
+Completion checkpoints uncommitted worktree changes and integrates into the branch currently checked out in the selected repository checkout (`--repo` when supplied). The target must be clean. A verification failure leaves the target unchanged and the worktree available for repair. Successful completion also keeps the worktree for inspection; removal is explicit and refuses dirty, untracked, or ignored work. Existing branches are never reset to create a worktree. Hydration tries filesystem clones and falls back to an independent copy; cost depends on the filesystem and dependency size.
+
+A verification command is optional. Without one, integration checks Git mergeability only. Choose a command that actually checks your project.
+
+## Other CLI workflows
+
+These agent-scoped commands assume an active session. Start one before claiming work or reserving resources:
+
+```sh
+eval "$(kith session start --agent worker-1 --owner-pid "$$" --shell)"
+
+# Task dependencies
+kith task add --id schema --title "Billing schema" --scope "src/db/**"
+kith task add --id api --title "Billing endpoints" --depends-on schema --scope "src/api/**"
+kith task claim --agent worker-1
+
+# Inspect worktrees, overlaps, relative commits, FIFO tickets and command guards
+kith status
+# Offline observations do not reap or migrate
+kith status --offline
+kith recover
+kith doctor
+# Preview committed source/target trees; dirty inputs are refused
+kith worktree preview --agent worker-1
+
+# Allocate a cooperating client's port; start your service promptly
+kith port --agent worker-1 --service web
+
+# Serialize commands; argument boundaries are preserved after --
+kith mutex --agent worker-1 --name package-install -- pnpm install
+
+# Start the MCP stdio server
+kith mcp
+```
+
+The `coord` executable is an alias for `kith`. The library exports `KithEngine` and its component classes for custom integrations:
+
+```js
+import { KithEngine } from 'kith-coord';
+const kith = new KithEngine('/absolute/path/to/repository');
+try {
+  kith.fencing.registerAgent({ id: 'custom-worker' });
+  const result = kith.locks.acquireLocks({
+    agentId: 'custom-worker', patterns: ['src/auth/**'],
+  });
+  console.log(result);
+} finally {
+  kith.close();
+}
+```
+
+## End a session
+
+When abandoning a task, use `kith session end` from the shell that owns the session. After completion or ending, remove the exported credentials:
+
+```sh
+unset KITH_AGENT_ID KITH_SESSION_TOKEN
+```
+
+Never include session tokens in issues, terminal recordings, or shared logs. See [session lifecycle](sessions-and-mutexes.md) for expiry and recovery.

package/docs/validation/2026-10-19-claude-client-report.json

@@ -0,0 +1,67 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    },
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    },
+    {
+      "scenario": "hook-failure",
+      "passed": true,
+      "checks": [
+        "native Write attempted once",
+        "tool denied",
+        "marker absent"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native CLI workflows, renewable MCP command supervision and failure probes; not GUI certification",
+  "configuration": "Generated settings; Codex receives server values via invocation overrides, Claude loads generated project hooks/MCP"
+}

package/docs/validation/2026-10-19-claude-hook-report.json

@@ -0,0 +1,33 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native CLI, disposable worktree fixture; not GUI certification",
+  "configuration": "Generated settings; Codex receives server values via invocation overrides, Claude loads generated project hooks/MCP"
+}

package/docs/validation/2026-10-19-claude-hook-unavailable-report.json

@@ -0,0 +1,20 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "hook-failure",
+      "passed": true,
+      "checks": [
+        "native Write attempted once",
+        "tool denied",
+        "marker absent"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Generated PreToolUse onFailure block; disposable macOS fixture"
+}

package/docs/validation/2026-10-19-claude-mutex-report.json

@@ -0,0 +1,34 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native MCP command supervision and editor workflow; macOS"
+}

package/docs/validation/2026-10-19-codex-client-report.json

@@ -0,0 +1,55 @@
+{
+  "client": "codex",
+  "version": "codex-cli 0.163.0-alpha.10.2",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released"
+      ]
+    },
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native CLI workflows, renewable MCP command supervision and failure probes; not GUI certification",
+  "configuration": "Generated settings; Codex receives server values via invocation overrides, Claude loads generated project hooks/MCP"
+}

package/docs/validation/2026-10-19-codex-mutex-report.json

@@ -0,0 +1,33 @@
+{
+  "client": "codex",
+  "version": "codex-cli 0.163.0-alpha.10.2",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native MCP command supervision and editor workflow; macOS"
+}

package/docs/validation/2026-10-19-path-hardening-claude.json

@@ -0,0 +1,32 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true
+}

package/docs/validation/2026-10-19-path-hardening-codex.json

@@ -0,0 +1,30 @@
+{
+  "client": "codex",
+  "version": "codex-cli 0.163.0-alpha.10.2",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released"
+      ]
+    }
+  ],
+  "passed": true
+}

package/docs/validation/2026-10-19-recovery-claude.json

@@ -0,0 +1,35 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "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-19-recovery-codex.json

@@ -0,0 +1,33 @@
+{
+  "client": "codex",
+  "version": "codex-cli 0.163.0-alpha.10.2",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "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"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "failed verification and successful retry",
+        "verified integration",
+        "task completed",
+        "locks released"
+      ]
+    }
+  ],
+  "passed": true
+}

package/docs/validation/2026-10-19-sqlite-runtime-report.json

@@ -0,0 +1,50 @@
+{
+  "date": "2026-10-19",
+  "scope": "SQLite capability compatibility; local macOS checks, hosted failure reproduction",
+  "hosted_before_fix": {
+    "run": "https://github.com/connorhriley/kith/actions/runs/39280488937",
+    "passed": [
+      "macos/22",
+      "macos/24",
+      "ubuntu/22",
+      "ubuntu/24"
+    ],
+    "failed": [
+      "macos/22.13.0",
+      "ubuntu/22.13.0"
+    ],
+    "cause": "no such module: fts5"
+  },
+  "local_runtimes": [
+    {
+      "node": "22.13.0",
+      "fts5": false,
+      "tests_passed": 78,
+      "tests_skipped": 2,
+      "skip_reason": "Restoration of an FTS5 index requires the unavailable module; fallback behavior is exercised.",
+      "package_consumer": "passed",
+      "two_mcp_clients": "passed"
+    },
+    {
+      "node": "22.23.3",
+      "fts5": true,
+      "tests_passed": 80,
+      "tests_skipped": 0
+    },
+    {
+      "node": "24.22.0",
+      "fts5": true,
+      "tests_passed": 80,
+      "tests_skipped": 0
+    }
+  ],
+  "real_cross_runtime_roundtrip": {
+    "result": "passed",
+    "sequence": [
+      "Create indexed state under Node 22.23.3",
+      "Update a contract and delete another under stock Node 22.13.0",
+      "Rebuild derived FTS index under Node 22.23.3 and verify only the updated contract remains"
+    ]
+  },
+  "hosted_after_fix": "Pending; inspect the final commit CI run for Linux/macOS validation."
+}

package/docs/validation/2026-10-20-adoption-claude.json

@@ -0,0 +1,35 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "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
+}