kith-coord 0.1.3 → 0.1.5

package/docs/client-validation.md

@@ -66,3 +66,8 @@ This is **partial native Windows support**, included in npm `kith-coord@0.1.1`.
 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.
+
+
+## 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).

package/docs/integrations.md

@@ -13,6 +13,8 @@ Install Kith persistently or build and link the checkout first. On macOS/Linux,
 
 ## 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.
+
 ```sh
 kith init --dry-run
 kith init
@@ -50,7 +52,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. 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.
+`kith doctor /absolute/checkout` checks Node/Git versions, supported platform, project and global MCP launcher files, recorded session environment, guard failure policy and worktree health. It recognizes global setup before the first task creates project state; a missing database is distinct from damaged state. Missing launcher files and connections pinned to a different checkout require setup review. 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 +66,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.3`) 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.5`) 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.3","kith","mcp","--repo","/absolute/checkout"]}}}
+{"mcpServers":{"kith":{"command":"npx","args":["--yes","--package","kith-coord@0.1.5","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.2.0",
+  "protocolVersion": "1.3.0",
   "tools": [
     {
       "name": "kith_start_session",
@@ -88,6 +88,12 @@
             "type": "boolean",
             "description": "Recommended: true, giving each parallel agent a separate Git worktree"
           },
+          "waitTimeoutMs": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 600000,
+            "description": "Wait up to this many milliseconds for the whole scope; default fail-fast, not a FIFO file queue"
+          },
           "repository": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -200,6 +206,11 @@
           "reason": {
             "type": "string"
           },
+          "waitTimeoutMs": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 600000
+          },
           "repository": {
             "type": "string",
             "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
@@ -390,6 +401,67 @@
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "name": "kith_run_dev_server",
+      "description": "Run a literal argv command with an allocated port in PORT/KITH_PORT and substituted {port} arguments. Renews the lease while running; cancellation/disconnect stops the process group before release. Uses coordinator permissions. Requires macOS/Linux; no implicit shell or readiness guarantee.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "agentId": {
+            "type": "string"
+          },
+          "sessionToken": {
+            "type": "string"
+          },
+          "serviceName": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128
+          },
+          "command": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1
+          },
+          "basePort": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535
+          },
+          "cwd": {
+            "type": "string"
+          },
+          "leaseDurationMs": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 86400000
+          },
+          "commandTimeoutMs": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 600000
+          },
+          "maxOutputBytes": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1048576
+          },
+          "repository": {
+            "type": "string",
+            "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
+          }
+        },
+        "required": [
+          "agentId",
+          "serviceName",
+          "command"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "name": "kith_get_status",
       "description": "Retrieve coordination state, FIFO waiters and guarded commands, plus worktree paths, actual branches, dirty-file overlaps, commit age and ahead/behind against the current integration target HEAD. Normal engine startup may reap expired ownership.",

package/docs/protocol.md

@@ -1,4 +1,4 @@
-# Kith coordination protocol 1.1
+# Kith coordination protocol 1.3
 
 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,7 +6,7 @@ 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.2.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`.
+`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`.
 
 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.
 
@@ -37,3 +37,9 @@ Protocol 1.2 adds optional `repository` to every tool. A global `kith mcp` conne
 Normal CLI/MCP status opens the engine and may migrate or reap. `kith status --offline`, `kith recover`, and `kith doctor` instead inspect a private copy of the database plus matching SQLite sidecars. They never initialize/migrate the original, renew/release claims, clear guards, or remove work. If files change while being copied or validation fails, observation is unavailable; stop writers and preserve the complete set before retrying. `recover` lists retained worktree directories, recorded owners, expired claims, unfinished integrations and lock-file presence. It performs no automatic repair. See [recovery](reliability.md).
 
 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)
+
+`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.

package/docs/reliability.md

@@ -73,8 +73,15 @@ See [path and scope rules](path-and-scope-rules.md) for repository discovery, li
 
 ## Observations and previews
 
-Workspace status distinguishes recorded branch/lease from observed Git state. Dirty overlap means the same relative path is changed in multiple active checkouts; it does not prove a merge conflict. Ahead/behind uses the reported target HEAD, not a fetched remote branch. Commit age does not trigger release; ownership TTL and heartbeat remain authoritative. Unavailable observations must not be interpreted as clean.
+Workspace status distinguishes recorded branch/lease from observed Git state. Dirty overlap means the same relative path is changed in multiple checkouts; it does not prove a merge conflict. Ahead/behind uses the reported target HEAD, not a fetched remote branch. Commit age does not trigger release; ownership TTL and heartbeat remain authoritative. Unavailable observations must not be interpreted as clean.
 
 `kith_preview_integrate` uses committed source/target trees and reports Git's exact conflict paths. It refuses dirty inputs rather than silently checkpointing them. It can create unreachable Git objects but leaves files/indexes/refs untouched; normal session authorization can renew a heartbeat. Actual completion rechecks inputs and performs the requested project verification independently. A successful preview is not a verification result.
 
 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.
+
+
+Passive CLI/menu observations use Git status and available file mtimes. They do not identify file writers or establish that a session is participating. Missing files and future timestamps cannot establish edit age and are omitted from timed recent-file lists. Incomplete scans retain unknown health; any retained findings may be stale. Use an explicit checkout and its owning session for integration, or offline inspection for recovery. Never clear warnings by deleting retained work.
+
+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.

package/docs/roadmap.md

@@ -1,42 +1,21 @@
 # Roadmap
 
-Success means a new contributor can reproduce a two-agent workflow, understand its boundaries, preserve work through failure, and extend one client adapter without rewriting the engine.
+The product gate is a developer completing a real task with cooperating agents: connect, claim, edit separate worktrees, coordinate shared resources, verify/integrate, and recover without losing unfinished work.
 
-## 1. Reliability foundation — implemented
+## Keep the core small
 
-Implemented: non-destructive configuration merging and previews, safer worktree lifecycle, serialized Kith integration, atomic port reservations, Git conflict refusal, surfaced Git errors, preserved command arguments, event pagination, non-destructive Bash recovery defaults, actual process contention coverage, contributor docs, license text, and a CI definition.
+MCP is the default agent interface. Keep one shared ownership ledger per Git common directory, capability-owned sessions, renewable command exclusion, conservative Git integration and retained-work recovery. Global connections select a repository per task. CLI inspection, the optional menu and editor adapters expose the same core; they do not become fleet controllers. Preserve existing client configuration and review gates.
 
-The canonical upstream is [connorhriley/kith](https://github.com/connorhriley/kith). Hosted results are available in [Actions](https://github.com/connorhriley/kith/actions/workflows/ci.yml); workflow configuration alone is not evidence of a passing matrix.
+## Current delivery gates
 
-## 2. Session, command, and client validation — implemented
+1. **Truthful observations.** Missing/future file times must not appear as fresh activity. Differing dirty copies, recorded ownership, unavailable scans and verified merge results remain distinct. No writer attribution or compatibility guarantee from polling.
+2. **One onboarding journey.** Explain global setup versus project init once; diagnose both without writes. Configuration is not connection or ownership. Keep MCP-only use free of manual capability exports and preserve custom entries/hooks/permissions.
+3. **Actual workflow completion.** Use current Kith fixes as real project work through scoped claims, isolated edits, normal verification and integration. Record native client versions separately from MCP fixtures. Validate failure/repair/retry and preserved target bytes; internal checks are not external adoption.
+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.
 
-Capability-owned session generations now protect agent-scoped mutation boundaries; process anchors cannot be silently rebound and liveness uses actual kernel identities. Schema 2 invalidates legacy unowned sessions while preserving files. Commands renew leases asynchronously, preserve FIFO tickets, and retain a process-group execution guard across expiry, cancellation, suspension, or supervisor crashes. CLI signals and output are supervised. Actual MCP stdio clients and generated hook commands now cover worktree reports, Git hooks, verification, completion, and disconnect recovery. A two-client disposable example is available with `pnpm demo`.
+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.
 
-These gates are covered locally. Version-specific native Codex and Claude CLI runs are recorded in [client validation](client-validation.md). Other releases, GUI discovery, and persisted project trust need separate validation.
+## Deferred
 
-## 3. Path, scope and merge hardening — implemented; recovery next
-
-- Exact scope-language intersection for literals, `*`, `?` and whole-segment `**`, with generated witness checks, dotfile coverage, explicit literal-file scopes and conservative handling of legacy unsupported scopes.
-- Redesign shared-tree Bash attribution before considering automatic restoration as a default. Gate: sibling edits cannot be reverted by another agent's post-hook.
-- Shared common-Git-directory discovery from roots, subdirectories, linked worktrees, symlink aliases and separate Git directories; physical containment, external-link refusal, literal framework paths and invoking-index Git guards have regression coverage.
-- Git conflicts require explicit source-worktree repair and retry; no custom source/JSON rewriting remains. Actual Git regressions preserve symlink targets, unusual filenames and non-UTF-8 bytes.
-- Legacy migration rollback/retry (including a process killed before commit), damaged-state refusal and stopped WAL backup restoration have regressions, including killed MCP ownership and worktree continuation. Broader upgrade/downgrade combinations and corrupted-state repair remain unvalidated.
-
-## 4. Broaden integration validation
-
-Cursor native hook payload/command fixtures, enforcement modes, private setup backups and conservative uninstall are implemented. Add manual workflows against actual Claude/Cursor/Codex application releases. Extend the current stdio/hook lifecycle and cancellation tests to other supported payload shapes. Cover paths with spaces, nested workspaces, custom Git hooks, missing Git identity, and crashes. Measure latency and memory in reproducible small and large repository fixtures before publishing performance claims.
-
-## 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.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
-
-Define parser and client adapter interfaces, add configuration for project-specific verification/hydration, and ship small runnable examples. Prioritize requests backed by concrete user workflows. Keep enforcement, advisory analysis, and presentation separate.
-
-
-## Requested priorities and remaining gates
-
-The current adoption pass adds optional Claude/Cursor block/warn/off hooks, richer status and committed-tree conflict previews, offline inspection/recovery reports, doctor, tracked setup/uninstall and a versioned input-schema snapshot. Atomic task claims/dependencies, port leases, supervised command mutexes, explicit contracts/symbol lock scopes and stopped WAL restore already exist; keep their canonical tool names rather than adding aliases.
-
-Next work needs concrete workflow validation: capability-filtered queue claims, named port/env/install bundles, broader Windows/process validation, and MCP registry publication. Optional notes, PR helpers, interoperable third-party ledgers and fleet spawning are proposals, not implemented behavior or release promises. No dashboard, model router or autonomous PR fixer is planned. Public adoption claims require actual user evidence.
+No new dashboard, fleet spawning, model router, automatic merges, semantic scoring, writer-PID attribution, whole-Mac crawler or new adapters are planned in this reliability pass. Prioritize concrete blocked workflows over feature requests. Actual external task completion remains a separate product-validation gate.

package/docs/usage.md

@@ -17,6 +17,65 @@ 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).
 
+## Launch a dev server on its allocated port
+
+These additions are available in source builds on `main`; the published `kith-coord@0.1.3` does not include them yet. Build/link the checkout before using the CLI examples.
+
+Run from the target repository (or pass `--repo /absolute/checkout`). Use a unique agent ID for each session. A standalone invocation creates and ends its own temporary session; an existing session must provide its capability as usual.
+
+```sh
+# A server that reads PORT needs no extra arguments.
+kith dev --agent web-a --service web -- npm run dev
+
+# For a tool requiring an explicit flag, substitute the allocated port.
+kith dev --agent web-b --service web -- npm run dev -- --port '{port}'
+
+# Vite: refuse a fallback port so the server cannot silently switch away.
+kith dev --agent web-c --service web --base 3000 -- pnpm exec vite --port '{port}' --strictPort
+```
+
+Kith starts scanning at 3000 by default, checks TCP availability and live reservations, and prints the allocation to stderr. It launches the literal argv with `PORT` and `KITH_PORT` set to the allocated number. Every `{port}` occurrence in an argument is substituted; shell metacharacters remain literal. It does not inject framework flags or rewrite configuration. Tools that ignore `PORT` must receive their own port flag via `{port}`. Use `--cwd apps/web` to select a subdirectory; the default is the registered worktree or selected checkout.
+
+The lease renews while the supervised process group runs. Ctrl-C/SIGTERM stops that group before releasing the reservation, and the command's exit status is preserved. For a temporary CLI session, completion also ends that session. A named service serializes launches from the same agent; different agents/services can run concurrently on separate ports.
+
+This does not hold a listening socket for the application or prove readiness. An unrelated process can win the bind race; the command's bind error is surfaced, with no automatic restart that might repeat side effects. The allocation is not a readiness URL or proof that a framework honored its port. Detached daemons escaping the group are outside the supervision boundary. Native Windows supervised launch is refused; use macOS/Linux or WSL.
+
+MCP clients with an active session can call:
+
+```text
+kith_run_dev_server {"agentId":"web-a","serviceName":"web","command":["pnpm","exec","vite","--port","{port}","--strictPort"],"commandTimeoutMs":600000}
+```
+
+This is a foreground tool call, returning the port, captured output and exit code when it ends. MCP defaults to a 60-second execution deadline and 64 KiB combined output limit; explicit limits allow up to 10 minutes and 1 MiB. Cancel the request or disconnect to stop the group. For a server needed throughout a longer interactive session, use the streaming CLI. Client approval applies: the process runs with the coordinator's permissions, not the client's shell sandbox. CLI output streams and has the existing supervisor's 16 MiB default combined output limit.
+
+## Wait for a shared file claim
+
+By default, overlapping exclusive claims still fail immediately. Opt in to bounded retry for occasional shared files:
+
+```sh
+# Within an existing capability-owned CLI session:
+kith begin --agent worker-1 --title "Update shared config" --scope 'package.json' --wait --wait-ms 30000
+
+# Or acquire a file scope without creating a new task:
+kith lock acquire --agent worker-1 --scope 'package.json' --wait --wait-ms 30000
+```
+
+`--wait` alone waits up to 60 seconds. `--wait-ms` also enables waiting without `--wait`, accepts 0–600000 milliseconds, and returns a conflict with nonzero exit status on timeout. Ctrl-C cancels the wait. Waiting renews the owning session, but cannot revive an expired or replaced session.
+
+The whole scope is checked atomically on each retry. No partial requested claim, task, or new worktree is created while blocked. On success, the usual exclusive ownership rules apply. Explicit requests report `waitedMs` and `waitTimedOut` alongside the normal result. Unsupported paths and invalid scopes fail immediately rather than being retried.
+
+On MCP, add `waitTimeoutMs` to `kith_begin_work` or `kith_check_and_lock_files`:
+
+```text
+kith_check_and_lock_files {"agentId":"worker-1","patterns":["file:package.json"],"waitTimeoutMs":30000}
+```
+
+The request remains open while waiting and responds to request cancellation and connection loss. Another request on the same connection can still heartbeat or release unrelated claims.
+
+This is cooperative retry, **not a FIFO file queue**. Use task dependencies when order matters. Do not claim multiple shared files in different orders across agents: retain no unnecessary claims while waiting, and always choose a finite deadline. Waiting for a worktree task grants ownership; it does not automatically rebase an existing worktree onto a peer's edits. Review the current file before changing it.
+
+Library callers can await `engine.beginWorkWhenAvailable(...)`, `engine.acquireLocksWhenAvailable(...)`, or `engine.broker.executeWithPort(...)`, passing an `AbortSignal` for cancellation. Await/cancel those operations before closing the engine.
+
 ## 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.

package/docs/validation/2026-10-22-product-claude.json

@@ -0,0 +1,38 @@
+{
+  "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,
+  "validationDate": "2026-10-22",
+  "authentication": "existing subscription login; API-key environment overrides removed",
+  "scope": "Disposable synthetic native-client workflow; not external adoption or all-version certification."
+}

package/docs/validation/2026-10-22-product-codex.json

@@ -0,0 +1,76 @@
+{
+  "client": "codex",
+  "version": "codex-cli 0.163.0-alpha.11.1",
+  "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"
+      ],
+      "toolOutcomes": [
+        {
+          "tool": "kith_begin_work",
+          "status": "failed",
+          "ok": false
+        },
+        {
+          "tool": "kith_begin_work",
+          "status": "completed",
+          "ok": true
+        },
+        {
+          "tool": "kith_record_file_edit",
+          "status": "completed"
+        },
+        {
+          "tool": "kith_run_with_mutex",
+          "status": "completed",
+          "ok": true,
+          "exitCode": 0
+        },
+        {
+          "tool": "kith_complete_work",
+          "status": "failed",
+          "ok": false
+        },
+        {
+          "tool": "kith_get_status",
+          "status": "completed"
+        },
+        {
+          "tool": "kith_complete_work",
+          "status": "completed",
+          "ok": true
+        },
+        {
+          "tool": "kith_get_status",
+          "status": "completed"
+        }
+      ],
+      "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,
+  "validationDate": "2026-10-22",
+  "authentication": "existing subscription login; API-key environment overrides removed",
+  "scope": "Disposable synthetic native-client workflow; not external adoption or all-version certification."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kith-coord",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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.3",
+  "version": "0.1.5",
   "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.3",
+      "version": "0.1.5",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {