kith-coord 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.7 — 2026-10-24
+
+- Retain the bundled setup runtime outside temporary npx caches, verify MCP discovery, and preserve existing client settings, custom launchers and original-byte recovery backups. Clarify actual tasks, claims, resource waits and verification results in the read-only coordination view.
+- Serialize MCP text replies as lossless compact JSON, retaining structured data, literal command output, warnings, capabilities and retry/recovery fields. No summarizer, extra calls or dependencies.
+- Compact contract metadata without inferring read relevance from write scopes. Preserve all breaking contracts and linked exports, retain per-consumer alert relationships and lock lease records, and expose full history with optional `includeHistory` (protocol 1.5). Ordinary preview omissions are explicit and point to the existing full-registry call.
+- Validate repository, branch, ownership, cleanliness and base before reusing a task worktree. Roll back queue/claim mutations when handoff fails; never remove partial or unfinished directories.
+- Bound advisory cross-repository inspection, require tracked files in a distinct Git repository, omit source initializers, resolve concrete wildcard imports, and report partial/unavailable observations without failing successful claims. Unsupported inherited configuration and re-exports defer to normal project verification.
+- Reject stale workspace scans, generate task prompts for selected Git checkouts, and retain only user-selected recent workspaces. Remove personal workspace defaults and automatic home-directory crawling. No new dependency or storage migration.
+
+## 0.1.6 — 2026-10-23
+
+- Add optional MCP operation keys with a capability-bound durable result journal in the existing database. Lost replies replay without repeating mutations; concurrent duplicates report in-progress, and interrupted/unrecorded outcomes refuse automatic re-execution. Historical replies never revive expired/completed sessions or authorize a replacement generation.
+- Add structured operational failure codes and retryability while preserving existing result fields. Distinguish claim/mutex wait contention from command deadlines, partial effects, ownership rejection and failed integration; preserve bounded command output on cancellation/timeouts.
+- Advance protocol to 1.4 and storage schema to 3. Transactional journal migration retains schema-2 ownership and recovery data; interrupted upgrades and missing journal state fail safely. No new runtime dependency, service or editor configuration changes.
+
 ## 0.1.5 — 2026-10-22
 
 - Group read-only radar observations by checkout, distinguishing current recorded Kith leases, retained sessions, unregistered checkouts and unavailable ownership. Label counts as paths to review before integration, with full checkout/owner details and preservation guidance. Reuse the same snapshot in the optional editor view without extra status subprocesses. No ownership, recovery or cleanup behavior changes.
@@ -102,6 +117,10 @@
 
 ## Unreleased
 
+- One-command setup retains a self-contained runtime outside transient npx caches, checks MCP discovery and installs marked project guidance alongside detected client configuration. Repeat/interrupted setup retains recovery material and existing custom launchers; older live project schemas require the stopped-upgrade procedure.
+- Read-only menu and editor views show current recorded tasks/claims, resource waits and failed integrations with next steps. Saved work and review paths move into details; the default menu omits file timestamps. Missing/partial state stays explicit. No new coordination database, model calls or automatic cleanup.
+
+
 ### Session ownership, supervision, and client validation
 
 - Add random session capabilities, hashed storage, fixed process anchors, generation checks, and exact fencing-token checks. ID-only renewal, completion, lock release, and mutation are rejected across engines/connections.

package/README.md

@@ -4,12 +4,13 @@
 
 <p align="center">
   <a href="https://github.com/connorhriley/kith/actions/workflows/ci.yml"><img src="https://github.com/connorhriley/kith/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/connorhriley/kith/actions/workflows/windows.yml"><img src="https://github.com/connorhriley/kith/actions/workflows/windows.yml/badge.svg" alt="Windows validation"></a>
   <a href="https://www.npmjs.com/package/kith-coord"><img src="https://img.shields.io/npm/v/kith-coord" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E" alt="MIT license"></a>
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick start</a> · <a href="#see-it-work">Demo</a> · <a href="docs/integrations.md">Integrations</a> · <a href="docs/usage.md">CLI &amp; API</a> · <a href="CONTRIBUTING.md">Contribute</a>
+  <a href="#quick-start">Quick start</a> · <a href="https://marketplace.visualstudio.com/items?itemName=kith-coord.kith">VS Code</a> · <a href="https://open-vsx.org/extension/kith-coord/kith">Cursor / Open VSX</a> · <a href="#see-it-work">Demo</a> · <a href="docs/integrations.md">Integrations</a> · <a href="docs/usage.md">CLI &amp; API</a> · <a href="CONTRIBUTING.md">Contribute</a>
 </p>
 
 **Local coordination for cooperating coding agents.**
@@ -28,7 +29,7 @@ Kith gives cooperating agents shared local state: who owns a task, which files a
 | Give agents separate working files | Git worktrees with an explicit integration step |
 | Check work before integration | Your project's verification command |
 | Share local tools | Port reservations and supervised command mutexes |
-| See what is happening | Session/task state through `kith status` and MCP |
+| See what is happening | Session/task state through CLI/MCP; optional read-only editor and worktree views |
 
 Kith fits workflows where you already launch multiple coding agents and want them to coordinate. It does not choose models, write prompts, or launch a fleet for you. Worktrees separate files; Kith adds shared ownership and resource coordination.
 
@@ -36,28 +37,50 @@ The [reliability contract](docs/reliability.md) defines ownership, verification,
 
 ## Quick start
 
-Requires **Git 2.38+** and **Node.js 22.13+ on 22.x or Node.js 24+**. Full workflows target macOS and Linux. Version 0.1.1 also validates native Windows MCP claims, worktrees, ports, integration and recovery; supervised mutex commands and shell hooks require macOS/Linux or WSL. See the [support evidence](docs/client-validation.md#native-windows).
+Requires **Git 2.38+** and **Node.js 22.13+ on 22.x or Node.js 24+**. Full workflows target macOS and Linux. Native Windows MCP checks cover claims, worktrees, ports, integration and recovery; supervised mutex commands and shell hooks require macOS/Linux or WSL. See the [support evidence](docs/client-validation.md#native-windows).
 
 Git recording and integration require a commit identity configured for the repository (`user.name` and `user.email`). Kith does not change your global Git identity.
 
-Install the release:
+**Upgrading to 0.1.6:** Stop existing Kith connections first. Back up stopped coordination state (including SQLite sidecars) and retain worktrees; upgrade all coordinators sharing a repository together. This release migrates storage schema 2 to 3, which older binaries refuse. Existing custom launchers are preserved; review their pinned version before reconnecting. See [recovery guidance](docs/reliability.md#recovery).
+
+### VS Code or Cursor
+
+Install **Kith** (`kith-coord.kith`) from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=kith-coord.kith) or [Cursor / Open VSX](https://open-vsx.org/extension/kith-coord/kith). You can also search for `kith-coord.kith` in the editor's Extensions view.
+
+To select release **0.1.7** explicitly with an editor CLI already on your `PATH`:
 
 ```sh
-npm install --global kith-coord@0.1.5
+code --install-extension kith-coord.kith@0.1.7
+cursor --install-extension kith-coord.kith@0.1.7
 ```
 
-Choose the setup scope your client needs:
+Use the command for your editor. A marketplace lookup can temporarily select an older version; the [extension guide](extensions/editor/README.md#install) also links the published 0.1.7 VSIX.
 
-- **Global desktop/CLI connection:** run `kith setup --dry-run`, then `kith setup`. Restart/reconnect the configured client. A desktop agent supplies the absolute Git `repository` on each tool call; no whole-Mac ownership database is created.
-- **Project configuration and agent instructions:** run the following inside the checkout. This is the default for project-scoped clients. Existing global connections need not be registered again; use `kith init --only agents` when only project guidance is needed.
+Open a trusted local Git checkout and approve Kith's MCP server through the editor. The extension bundles the coordination server, detects Node, and preserves existing MCP entries, hooks and tool permissions. **No global npm install is needed.** Each agent still needs to use Kith's tools; installing the extension does not enforce claims on other writers.
+
+Start with a scoped task:
+
+```text
+Use Kith to begin an isolated task in this repository with a unique agent ID.
+Claim only the files this task needs, edit the returned worktree, and report edits.
+Run the project checks and complete through Kith with that verification command.
+```
+
+The [extension guide](extensions/editor/README.md) covers settings and existing configurations; [recorded editor checks](docs/client-validation.md#editor-marketplaces-and-signed-in-chats) distinguish installation, native MCP registration and signed-in task results.
+
+### CLI and other MCP clients
+
+One command from your Git checkout configures supported detected clients and adds project instructions:
 
 ```sh
-cd /path/to/your/project
-kith init --dry-run
-kith init
+npx --yes --package kith-coord@0.1.7 kith setup
 ```
 
-Setup preserves peer configurations, hooks and permissions. A written configuration is not a confirmed connection: check Kith's server status in the client, then ask it to begin an isolated task. `kith doctor /absolute/checkout` checks global and project launcher files without starting clients or creating project state. See [client setup](docs/integrations.md#configure-detected-local-clients).
+Durable setup starts with **0.1.7**. Earlier versions need a persistent global npm installation before setup. [Client setup](docs/integrations.md#configure-detected-local-clients) covers configuration scope and advanced options.
+
+Setup retains an exact self-contained runtime outside npx's cache, checks its MCP discovery, and backs up changes before writing them. Existing custom Kith launchers, peer servers, hooks and permissions are preserved. From outside a Git checkout it configures global connections; pass a project path to add that project's guidance. Reconnect the client and approve its MCP server through the client's normal controls.
+
+Ask your agent to do the task using Kith. The view says **Watching only** until a task is actually recorded. A configured server is not a running task. `kith setup --dry-run` previews without writes; `kith doctor /absolute/checkout` diagnoses configuration.
 
 For source installation and the disposable demo, use the pinned **pnpm 10.20.0**:
 
@@ -90,24 +113,17 @@ Two real MCP clients completed work in separate worktrees. Disposable example pa
 
 The implementation is in [examples/two-agents.mjs](examples/two-agents.mjs). This demonstrates the coordination protocol; [native-client validation](docs/client-validation.md) separately exercises installed coding clients.
 
-### Connect your client
-
-After the npm quick start above, restart your coding client in that project and approve its Kith MCP connection. Generated configuration uses the installed `kith` executable; no source checkout or `pnpm link` is needed. Review and commit the generated files before asking agents to integrate work.
+### Client support
 
-Default setup installs MCP configuration for Claude, Codex and Cursor plus agent instructions, without adding hooks or package-manager shims. Review and commit the generated configuration before starting work; integration requires a clean target checkout. Restart your client with `kith` on its `PATH`. To select clients, use `--mcp-only --only claude,codex,agents`. Existing hooks are preserved; review warnings if they require an inherited session. See [hook setup](docs/integrations.md) if you need them.
+The editor extension bundles the server and offers it through native MCP registration; no global npm install is needed. Installing an extension or writing configuration does not enforce claims on writers that do not use Kith. Existing custom Kith entries retain precedence.
 
 | Client | Setup and validation |
 | --- | --- |
-| Claude Code | MCP; optional edit hooks need shared session setup; recorded native CLI runs |
-| Codex | Project MCP configuration; recorded native CLI runs with configuration overrides |
-| Cursor | Native CLI workflow and fail-closed edit hooks validated; GUI discovery/trust unvalidated |
+| VS Code / Cursor | One-click marketplace extension; native MCP controls retain approval and trust |
+| Claude Code / Claude Desktop / Codex | Detected client configuration through `kith setup` |
 | Other MCP clients | stdio server via `kith mcp`; client-specific validation required |
 
-For VS Code and Cursor, the [editor extension](extensions/editor) offers a bundled MCP server and a small read-only status indicator. Install its VSIX through **Extensions → Install from VSIX**. It preserves existing MCP entries and leaves server approval and tool permissions to the editor. No global npm installation is needed; compatible Node.js is still required.
-
-Native checks are version-specific. GUI discovery and persisted project trust need separate checks. See [integration setup](docs/integrations.md), [recorded validation](docs/client-validation.md), and [session ownership](docs/sessions-and-mutexes.md) before mixing hooks, CLI commands, and MCP clients.
-
-The npm package is **`kith-coord`**, with the command name **`kith`**. For a pinned npx MCP launcher, see [registry setup](docs/integrations.md#registry-installation). The unrelated npm package `kith` is not this project.
+Native evidence is version-specific. See [client validation](docs/client-validation.md), [advanced integration setup](docs/integrations.md) and [session ownership](docs/sessions-and-mutexes.md). The npm package is **`kith-coord`** and the command is **`kith`**; the unrelated npm package `kith` is not this project.
 
 ## Dev servers and shared config
 
@@ -121,6 +137,17 @@ kith lock acquire --agent worker-1 --scope package.json --wait --wait-ms 30000
 
 See [dev-server launch and waiting claims](docs/usage.md#launch-a-dev-server-on-its-allocated-port) for framework flags, session setup, cancellation, and MCP usage.
 
+## Optional read-only monitoring
+
+```sh
+kith watch /path/to/workspace --once --json
+kith menubar /path/to/workspace  # macOS 12+, Intel or Apple Silicon
+```
+
+The menu and editor lead with recorded tasks, current file claims, shared-resource waits and integrations that need inspection. A registered session without a task is shown separately. Saved checkouts and path comparisons stay in details; nothing is automatically deleted. The menu's default view omits the file-timestamp feed.
+
+**Watching only** means no active Kith task is recorded. Shared dirty paths are files to review before integration, not a proven merge conflict. **Status unavailable** remains explicit when state cannot be inspected safely. Reads use private snapshots without renewing owners or migrating the original database. See [observation limits](docs/usage.md#optional-read-only-worktree-observations).
+
 ## How a task moves through Kith
 
 1. **Begin through MCP.** Call `kith_begin_work` with a unique `agentId`, explicit `scopeGlobs`, and `isolateWorktree: true`. The connection retains session ownership; no shell exports are needed for this MCP-only workflow.

package/dist/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,80 @@
+## undefined@undefined
+
+
+
+## picomatch@4.0.7
+MIT
+The MIT License (MIT)
+
+Copyright (c) 2017-present, Jon Schlinkert.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+## smol-toml@1.9.1
+BSD-3-Clause
+Copyright (c) Squirrel Chat et al., All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+## zod@3.25.76
+MIT
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.