kith-coord 0.1.2 → 0.1.3

package/docs/integrations.md

@@ -64,12 +64,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.3`) 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.3","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 +78,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.2.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,10 @@
           "isolateWorktree": {
             "type": "boolean",
             "description": "Recommended: true, giving each parallel agent a separate Git worktree"
+          },
+          "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 +117,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 +159,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 +199,10 @@
           },
           "reason": {
             "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": [
@@ -206,6 +230,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 +279,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 +313,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 +375,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": [
@@ -365,6 +405,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 +426,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 +464,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

@@ -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.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`.
 
 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.

package/docs/usage.md

@@ -107,3 +107,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kith-coord",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",

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.2",
+  "version": "0.1.3",
   "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.2",
+      "version": "0.1.3",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {
@@ -42,9 +42,9 @@
         {
           "type": "named",
           "name": "--repo",
-          "description": "Absolute path to the Git checkout to coordinate. Git 2.38+ and Node 22.13+ (22.x) or 24+ required.",
+          "description": "Optional fixed Git checkout. Omit for a global connection and supply repository on each tool call. Git 2.38+ and Node 22.13+ (22.x) or 24+ required.",
           "format": "filepath",
-          "isRequired": true
+          "isRequired": false
         }
       ]
     }