kith-coord 0.1.2 → 0.1.4

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.2`) 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.4`) 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.2","kith","mcp","--repo","/absolute/checkout"]}}}
+{"mcpServers":{"kith":{"command":"npx","args":["--yes","--package","kith-coord@0.1.4","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.
@@ -78,3 +80,14 @@ Use a version you have verified; the unrelated npm package named `kith` is not K
 ## 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).
+
+
+## Configure detected local clients
+
+`kith setup --dry-run` previews configuration for detected existing clients; omit `--dry-run` to apply it. It works from HOME without creating a project database there. Global Claude Desktop, Claude Code, Codex and Antigravity entries use this installation's Node and CLI paths and can select a different Git repository on each MCP call. No disk-wide scan or shared current-project switch is involved. Clients started inside a Git checkout use that checkout by default. Desktop clients started at `/` or HOME connect without opening a coordinator; their agent supplies an absolute `repository` path for the task.
+
+Run `kith setup /absolute/checkout` inside a project to configure its Cursor entry as well. Project entries and explicit `mcp --repo /absolute/checkout` remain pinned to that checkout. Existing hooks and approval settings are untouched. Custom Kith transports or wrappers that cannot be safely recognized are preserved and reported for manual review, with a nonzero exit. Detection/configuration is not proof that a particular GUI client connected; restart or reconnect that client after setup and check its server status. VS Code is not an automatic setup adapter.
+
+Project configuration uses the existing checkout setup ledger. Global client files use a private `~/.coord/setup/` ledger: `kith uninstall --repo "$HOME" --dry-run` previews restoring those unchanged writes. As with project uninstall, edited files and backups are retained. Configuration already overwritten by older untracked setup cannot be reconstructed; recover an earlier copy manually. All selected configuration is parsed and checked before writes, and backups precede each write. A partial setup can still require manual review; rerunning does not discard recovery material.
+
+Generated launchers use absolute paths from the current installation. Rerun setup after moving Node or Kith. MCP connections retain capabilities as usual; setup neither creates a session nor changes ownership rules.

package/docs/protocol/tools.v1.json

@@ -1,5 +1,5 @@
 {
-  "protocolVersion": "1.1.0",
+  "protocolVersion": "1.3.0",
   "tools": [
     {
       "name": "kith_start_session",
@@ -15,6 +15,10 @@
           },
           "leaseDurationMs": {
             "type": "number"
+          },
+          "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": [
@@ -35,6 +39,10 @@
           },
           "sessionToken": {
             "type": "string"
+          },
+          "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": [
@@ -79,6 +87,16 @@
           "isolateWorktree": {
             "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."
           }
         },
         "required": [
@@ -105,6 +123,10 @@
           },
           "client": {
             "type": "string"
+          },
+          "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": [
@@ -143,6 +165,10 @@
             "items": {
               "type": "string"
             }
+          },
+          "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": [
@@ -179,6 +205,15 @@
           },
           "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."
           }
         },
         "required": [
@@ -206,6 +241,10 @@
           },
           "content": {
             "type": "string"
+          },
+          "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": [
@@ -251,6 +290,10 @@
           },
           "docComment": {
             "type": "string"
+          },
+          "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": [
@@ -281,6 +324,10 @@
           },
           "basePort": {
             "type": "number"
+          },
+          "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": [
@@ -339,6 +386,10 @@
             "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": [
@@ -350,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.",
@@ -365,6 +477,10 @@
           "includeContracts": {
             "type": "boolean",
             "description": "Include the full contract registry. Default false keeps frequent status polls compact; contractCount always reports its size."
+          },
+          "repository": {
+            "type": "string",
+            "description": "Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task."
           }
         },
         "additionalProperties": false,
@@ -382,6 +498,10 @@
           },
           "sessionToken": {
             "type": "string"
+          },
+          "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": [
@@ -416,6 +536,10 @@
           "verificationCmd": {
             "type": "string",
             "description": "Command to run in speculative merge tree (e.g. \"npm run typecheck\")"
+          },
+          "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": [

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,12 +6,14 @@ 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.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`.
+`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.
 
 Successful tool replies place the same JSON object in `structuredContent` and the first text block. Additional text may contain an advisory event delta. Inspect `isError` and the operation's fields: a computed preview with `clean:false` is a successful observation of a conflict, not permission to integrate. Exceptions are MCP tool errors. Never infer successful work from the client process exit code alone.
 
+Protocol 1.2 adds optional `repository` to every tool. A global `kith mcp` connection can route calls independently to absolute Git checkout paths; it creates no project database until a project is selected. A Git checkout in the process/project context supplies a default. Without one, calls must include `repository` and otherwise return a tool error while the connection remains available. Never substitute HOME or a filesystem root. Always keep the original checkout path for a task, even when editing its isolated worktree. Capabilities and commands remain attached to their repository context, and disconnect cleanup covers every opened context. An explicit `mcp --repo` connection retains its pinned checkout and refuses a different repository argument.
+
 ## 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. 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.
@@ -35,3 +37,9 @@ Successful tool replies place the same JSON object in `structuredContent` and th
 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

@@ -78,3 +78,6 @@ Workspace status distinguishes recorded branch/lease from observed Git state. Di
 `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.

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.3 / protocol 1.2 has recorded source/tag and clean-registry evidence. The 0.1.4 candidate adds protocol 1.3 dev-server supervision, bounded claim waits and the existing editor adapter. Its combined core/platform and bundled-server checks must pass before release. 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.
@@ -107,3 +166,12 @@ 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.
+
+
+## Optional read-only worktree observations
+
+`kith watch /absolute/checkout --once --json` reports uncommitted path overlaps across linked worktrees sharing a Git common directory. A parent directory can contain several independent repositories; equal filenames in unrelated repositories do not establish a collision. The watcher does not identify agents, enforce ownership, or establish contract/semantic compatibility. Clean output means only that the completed scan observed no differing or unverified shared dirty paths. Failed discovery or Git reads produce `complete:false`, error details and a nonzero one-shot exit; inspect the failure before relying on the observation.
+
+The read-only watcher excludes byte-identical dirty copies (including matching executable modes) across linked worktrees. Remaining shared dirty paths are advisories, not proven merge conflicts. Files over 8 MiB and non-file objects remain unverified rather than being treated as identical. The menu shows at most eight overlap rows; `kith watch --once` provides the full observations.
+
+Omit `--once` for continuous observation. `--notify=false` suppresses optional macOS notifications. On macOS 12 or newer, `kith menubar /absolute/checkout` opens the same limited read-only view. The package includes an Intel/Apple Silicon executable, launched with this installation's Node and CLI paths; unavailable/failed scans remain visibly unavailable. Other platforms use `kith watch`. Source contributors can rebuild with `pnpm build:menubar` using Apple's command-line tools, and run the pipe/timeout regressions with `pnpm test:menubar`.

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.2",
+  "version": "0.1.4",
   "description": "Local coordination for cooperating coding agents: work claims, isolated worktrees, shared resources, and verified integration without a hosted service.",
   "type": "module",
   "bin": {
@@ -25,7 +25,8 @@
     "SECURITY.md",
     "CODE_OF_CONDUCT.md",
     "CHANGELOG.md",
-    "assets/brand"
+    "assets/brand",
+    "bin/kith-menubar"
   ],
   "engines": {
     "node": "^22.13.0 || >=24.0.0"
@@ -37,12 +38,14 @@
     "test:watch": "tsup && vitest",
     "typecheck": "tsc --noEmit",
     "check": "pnpm typecheck && pnpm test",
-    "prepack": "tsup",
+    "prepack": "tsup && node scripts/build-menubar.mjs --if-supported",
     "test:package": "pnpm build && node scripts/smoke-package.mjs",
     "demo": "pnpm build && node examples/two-agents.mjs",
     "test:clients": "pnpm build && node scripts/validate-native-clients.mjs",
     "protocol:export": "pnpm build && node scripts/export-protocol.mjs",
-    "protocol:check": "node scripts/export-protocol.mjs --check"
+    "protocol:check": "node scripts/export-protocol.mjs --check",
+    "build:menubar": "node scripts/build-menubar.mjs",
+    "test:menubar": "node scripts/test-menubar.mjs"
   },
   "keywords": [
     "ai-agents",