kith-coord 0.1.6 → 0.1.7

package/docs/integrations.md

@@ -90,6 +90,11 @@ Version 0.1.1 generates MCP configuration using the current absolute Node execut
 
 ## Configure detected local clients
 
+From 0.1.7, `npx --yes --package kith-coord@0.1.7 kith setup /absolute/checkout` is the single setup path. Versions through 0.1.6 need a persistent npm installation first. Setup retains the exact bundled runtime under `~/.local/share/kith/runtimes/`, validates actual MCP discovery without selecting a repository, configures supported detected clients and adds marked project guidance. Clearing the original npx cache does not break its launcher. Repeat setup reuses identical content; upgrades retain prior runtimes so existing processes and configuration backups remain usable. A damaged selected runtime is refused rather than overwritten. Custom launchers remain custom.
+
+Retained runtimes are not automatically deleted by uninstall because existing or edited client configurations may still reference them. Global setup outside a Git checkout does not create one whole-machine coordination database. Project guidance joins the existing original-byte setup ledger. An older project schema is refused before changing clients: stop all coordinators and follow the upgrade procedure first.
+
+
 `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.

package/docs/protocol/tools.v1.json

@@ -1,5 +1,5 @@
 {
-  "protocolVersion": "1.4.0",
+  "protocolVersion": "1.5.0",
   "tools": [
     {
       "name": "kith_start_session",
@@ -136,6 +136,16 @@
           "client": {
             "type": "string"
           },
+          "isolateWorktree": {
+            "type": "boolean",
+            "description": "Recommended: true, giving the claiming agent an isolated Git worktree"
+          },
+          "waitTimeoutMs": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 600000,
+            "description": "Wait up to this many milliseconds for a queued task to become unblocked and claimable"
+          },
           "operationKey": {
             "type": "string",
             "minLength": 1,
@@ -541,6 +551,10 @@
           "sessionToken": {
             "type": "string"
           },
+          "includeHistory": {
+            "type": "boolean",
+            "description": "Include completed task history; default false returns current/pending tasks plus completedTaskCount. Lock lease details are always preserved."
+          },
           "includeContracts": {
             "type": "boolean",
             "description": "Include the full contract registry. Default false keeps frequent status polls compact; contractCount always reports its size."

package/docs/protocol.md

@@ -1,4 +1,4 @@
-# Kith coordination protocol 1.4
+# Kith coordination protocol 1.5
 
 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.4.0` starting with package 0.1.6. Package releases (`kith-coord`, beginning at 0.1.0) and the SQLite storage schema (3) 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`.
+`KITH_PROTOCOL_VERSION` and status responses advertise `1.5.0` starting with package 0.1.7; package 0.1.6 advertises `1.4.0`. Package releases (`kith-coord`, beginning at 0.1.0) and the SQLite storage schema (3) 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.
 
@@ -44,6 +44,14 @@ Preview refuses repositories with configured custom merge drivers because Git ca
 
 `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.
 
+## Protocol 1.5: compact context with explicit full details (0.1.7)
+
+MCP JSON text omits formatting whitespace without changing its data or literal strings. Contract previews remove database fingerprints while preserving file/symbol/signature, version, breaking status, owner and documentation. A write scope is not a read-dependency filter: previews draw from all scopes and include every breaking contract, even beyond the ordinary 30-record preview size. `publishedContractsComplete` and `publishedContractsOmitted` label omitted ordinary records; `contractDetails` points to `kith_get_status` with `includeContracts:true` for the full original registry. Large sets of critical changes may therefore produce larger replies; Kith does not discard them to meet a token target.
+
+Linked-module replies retain every symbol supplied by the already bounded core inspector and preserve `exportsComplete`, `ownershipAvailable`, dirty/unknown state and drift details. `totalSymbolsInFile` is null when the core cannot establish a complete list. File-edit replies retain all changed contracts, the established per-consumer breaking-change fields, removal/conflict details and warnings. Only the advisory text footer groups repeated signatures, retaining each affected file, owner and hop distance together. This grouping never changes the machine-readable `contractReport.breakingChanges` shape.
+
+`kith_get_status` defaults to current/pending tasks and reports `completedTaskCount` and `historyIncluded:false`. Its optional `includeHistory:true` returns completed tasks too. All lock records retain their identity, fencing and lease/expiry fields in both modes. `includeContracts:true` continues to return full unmodified registry records. No new tool, dependency or storage migration is introduced.
+
 ## Protocol 1.4: keyed retries and operational failures (0.1.6)
 
 These additions ship in `kith-coord` 0.1.6. Existing callers can omit the new fields and retain the same ownership requirements.

package/docs/reliability.md

@@ -93,3 +93,17 @@ Kith 0.1.6 (protocol 1.4) supports optional [operation keys and structured failu
 Replay is capability-protected historical access, not renewed ownership. Old session tokens cannot act on a replacement generation. Lost initial capability grants cannot be recovered with a key alone. Do not erase operation history to make a retry run; inspect effects and retained work before deliberately starting a new attempt. Keep the entire stopped database/sidecar set, because operation history and ownership belong to the same recovery snapshot.
 
 Schema 2 to 3 adds the journal transactionally and preserves current ownership, task state, files and process guards. A killed upgrade rolls back and can be retried. Startup refuses a schema-3 database missing its journal or required columns, rather than reconstructing an empty retry history. Stop old clients before upgrading; binaries that only support schema 2 refuse schema 3. Generic storage errors stay non-retryable because they can occur after external work. There are no new services, dependencies, retry daemons or UI controls.
+
+
+### Task handoff and cross-repository observations (0.1.7)
+
+A queued task's ownership/claims and its worktree handoff commit together. If the handoff fails, task/claim mutations roll back. Any partial filesystem output stays intact for inspection; Kith never deletes it to make a retry succeed. Reusing a saved worktree requires matching Git common-directory identity, branch and exclusive registration, no unfinished tracked/untracked changes, and HEAD matching the selected checkout's HEAD. A moved, dirty or stale checkout is refused for explicit recovery.
+
+Cross-repository advice reads explicit local TypeScript/JavaScript path aliases to tracked files in a distinct Git repository. It does not crawl folders or prove runtime compatibility. Status inspects direct aliases; concrete wildcard imports are resolved when recording edits. Inherited/referenced configuration and re-exports defer to your normal compiler and project checks. Source/config reads are capped at 64 KiB, reports at eight linked files/64 symbols and 16 KiB. Replies contain symbol names/kinds/hashes, not source initializers. MCP text replies use compact JSON without dropping fields or changing literal strings; structured responses and safety/recovery details are preserved. Partial exports suppress missing-export verdicts. Unavailable sibling ownership, Git checks or worktrees remain explicitly unavailable; advisory failure does not invalidate a successful work claim.
+
+The menu watches a selected workspace and stores recent selections. It does not search your home directory or assume project-folder names. Switching invalidates the old view immediately; late results from an earlier selection are discarded. Task prompts belong to individual Git checkouts, not a workspace parent. Observations never identify nonparticipating writers or authorize cleanup.
+
+
+### Compact MCP context (0.1.7)
+
+Compact replies preserve actionable context: all breaking contracts, linked exports within the core inspection bounds, changed contract receipts, warnings, failures and recovery instructions. They do not guess read dependencies from write scopes. Only ordinary contract previews are limited; omitted counts and a full-registry retrieval instruction are explicit. The text footer can group repeated signatures while retaining each downstream file/agent/distance relationship; machine-readable breaking alerts retain their established fields. `includeHistory:true` retrieves completed tasks, and lock identity, fencing and expiry remain visible. Savings come from formatting, repeated signatures and internal fingerprints rather than a semantic summarizer. No model calls or extra service are needed.

package/docs/roadmap.md

@@ -14,7 +14,7 @@ MCP is the default agent interface. Keep one shared ownership ledger per Git com
 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.
 
-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.
+Published 0.1.6 / protocol 1.4 has recorded clean npm and editor-registry evidence, including durable mutation retries and preserved recovery. The current usability pass simplifies activation and read-only feedback without changing ownership, storage schema or the MCP 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.
 
 ## Deferred
 

package/package.json

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