kith-coord 0.1.0 → 0.1.1

package/docs/client-validation.md

@@ -7,13 +7,14 @@ pnpm install --frozen-lockfile
 pnpm build
 node scripts/validate-native-clients.mjs --client codex --output artifacts/codex.json
 node scripts/validate-native-clients.mjs --client claude --output artifacts/claude.json
+node scripts/validate-native-clients.mjs --client cursor --output artifacts/cursor.json
 ```
 
-Use `--scenario isolated` or `--scenario shared` for a single run. Claude also runs `--scenario hook-failure` by default, replacing the pre-hook executable with a missing path and proving that its native Write is denied. Both worktree modes integrate an isolated worktree. The isolated scenario gives Codex an MCP-owned session; shared mode forwards a capability anchored to the runner. Claude always inherits a session so its generated edit hooks and MCP server share ownership.
+Use `--scenario isolated` or `--scenario shared` for a single run. Claude and Cursor also run `--scenario hook-failure` by default, replacing the pre-hook executable with a missing path and proving that a native edit is denied. Both worktree modes integrate an isolated worktree. The isolated scenario gives Codex an MCP-owned session; shared mode forwards a capability anchored to the runner. Claude and Cursor always inherit a session so its generated edit hooks and MCP server share ownership.
 
-Each run uses a disposable Git repository with spaces and an apostrophe in its path. A peer holds a source file. The native client must receive the conflict (Claude also attempts a native edit that its pre-hook must deny), choose a separate scope, edit its returned worktree, report the edit, run a supervised MCP command across multiple lease periods, encounter an expected verification failure, inspect retained ownership, retry completion successfully, and release ownership. The runner checks native tool events, exact protected/integrated bytes, contracts, task completion, verification diagnostics, Git HEAD and remaining locks. An exit-zero client that merely reports a permission failure fails validation. Results are version-specific evidence, not certification of every client release or GUI.
+Each run uses a disposable Git repository with spaces and an apostrophe in its path. A peer holds a source file. The native client must receive the conflict (Claude and Cursor also attempt a native edit that their pre-hook must deny), choose a separate scope, edit its returned worktree, report the edit, run a supervised MCP command across multiple lease periods, encounter an expected verification failure, inspect retained ownership, retry completion successfully, and release ownership. The runner checks native tool events, exact protected/integrated bytes, contracts, task completion, verification diagnostics, Git HEAD and remaining locks. An exit-zero client that merely reports a permission failure fails validation. Results are version-specific evidence, not certification of every client release or GUI.
 
-The Codex invocation ignores user configuration/rules, uses a workspace-write sandbox, passes the generated TOML server values as invocation overrides, and approves only that fixture's Kith MCP tools for unattended execution. It does not test persisted project trust or GUI discovery; review and trust project settings in your normal client before use. Normal `kith init --only codex` does not change approval policy or mark a real project trusted. Claude loads project settings, restricts MCP to the generated config, permits its native editor and Kith tools, denies unattended permission prompts, and uses a $2 per-scenario budget. The runner has a three-minute deadline and bounded output. It does not log in, change global configuration, or create subagents.
+The Codex invocation ignores user configuration/rules, uses a workspace-write sandbox, passes the generated TOML server values as invocation overrides, and approves only that fixture's Kith MCP tools for unattended execution. It does not test persisted project trust or GUI discovery; review and trust project settings in your normal client before use. Normal `kith init --only codex` does not change approval policy or mark a real project trusted. Claude loads project settings, restricts MCP to the generated config, permits its native editor and Kith tools, denies unattended permission prompts, and uses a $2 per-scenario budget. Cursor uses its installed `agent` executable (override with `--binary /absolute/path`), generated project MCP/hook settings, fixture trust, automatic MCP approval and its enabled sandbox. It uses your existing Cursor login/default model and can consume Cursor usage; no price cap is available in this runner. The CLI can record trust/session metadata for the disposable fixture. The runner has a three-minute deadline and bounded output, does not log in or edit global client settings directly, and never requests subagents. Model-driven runs currently require macOS/Linux process groups for bounded cleanup.
 
 Reports contain client/version, platform, scenario outcomes and tool names. Raw MCP results include bearer capabilities and must not be published. No raw transcript is saved by default. Keep credentials out of repository settings; generated Codex config forwards environment variable names with `env_vars`.
 
@@ -43,9 +44,19 @@ The 2026-10-20 subtraction pass reran the isolated native workflows on macOS / N
 
 ## Cursor adapter coverage
 
-Generated Cursor hooks use the documented native `preToolUse`/`postToolUse` protocol and `failClosed:true`. Subprocess fixtures exercise allow/deny JSON, block/warn/off mode changes, preservation of unrelated hooks, and missing/forged ownership refusal. Native Cursor application discovery, hook invocation/failure handling and model workflows remain unvalidated; payload fixtures do not establish those outcomes. The shared Git/worktree and MCP boundaries have separate automated coverage.
+Generated Cursor hooks use the documented native `preToolUse`/`postToolUse` protocol and `failClosed:true`. Subprocess fixtures exercise allow/deny JSON, block/warn/off mode changes, preservation of unrelated hooks, and missing/forged ownership refusal. Native Cursor CLI evidence is recorded below. Cursor GUI discovery/trust and other client versions remain unvalidated; CLI and payload fixtures do not establish those outcomes. The shared Git/worktree and MCP boundaries have separate automated coverage.
 
 
 The 2026-10-20 adoption pass reran the isolated workflows on macOS / Node 22.23.3: [Codex CLI 0.163.0-alpha.10.2](validation/2026-10-20-adoption-codex.json) and [Claude Code 2.1.301](validation/2026-10-20-adoption-claude.json) passed native editing, renewable mutex execution, failed verification/retry, integration and ownership release. Claude also passed the separate [unavailable-guard denial](validation/2026-10-20-adoption-hook-failure.json).
 
 The [first Codex attempt](validation/2026-10-20-adoption-codex-first-attempt.json) stopped after its mutex call without completing the fixture; the runner correctly marked it failed despite the client exiting zero. Its cause was not established. A diagnostic rerun passed and now records redacted outcome fields without raw tool arguments/results. Keep the incomplete attempt visible: model-driven validation can vary, and one successful rerun does not explain an earlier incomplete workflow.
+
+
+On 2026-10-20, macOS / Node 22.23.3, [Cursor CLI 2026.10.19-6bbf2c4](validation/2026-10-20-cursor-cli.json) passed the real model workflow with an inherited session: native peer-edit denial, worktree editing, edit reporting, renewable command supervision, failed verification/retry, integration and released claims. A temporary wrapper forwarded the exact generated guard and recorded only path/exit status; native editor events and repository state were also checked. The separate [unavailable-guard check](validation/2026-10-20-cursor-hook-unavailable.json) passed: one native edit attempt was denied and the marker stayed absent. Raw capability-bearing transcripts were not saved.
+
+
+## Native Windows
+
+Version 0.1.1 has real `windows-latest` SDK/Node/Git workflow evidence on [Node 22.13.0](validation/2026-10-20-windows-node-22.13.0.json) and [Node 24](validation/2026-10-20-windows-node-24.json). These checks use two actual MCP server processes, not path mocks: owned sessions and refused theft/overlap, native and Git-style paths, literal bracket filenames, internal/escaping directory junctions, separate worktrees, port leases, dirty-preview refusal, failed verification/retry, integration, killed-owner recovery with a new capability, unchanged-state offline inspection, generated Node-based MCP startup and conservative uninstall. Git's configured checkout line endings are respected; failed verification must preserve the source's exact existing bytes. The installed package is tested from a fresh npm cache: source pushes use a packed archive, while matching release tags install the exact public registry version. The separate [Windows workflow](../.github/workflows/windows.yml) runs on pushes/PRs and retains redacted JSON; it also checks damaged-state refusal without replacing state or losing work.
+
+This is **partial native Windows support**, included in npm `kith-coord@0.1.1`. `kith_run_with_mutex` refuses before execution or lease/guard acquisition because its cleanup guarantee needs POSIX process groups. Native shell hooks/shims are refused during setup before writes; use `kith init --mcp-only` or WSL for the full workflow. `doctor` reports the platform limitation and exits nonzero. This does not certify a Windows model-driven client or GUI; the native Cursor runs above are on macOS. Windows backup files are flushed before client writes, but Node cannot flush directory entries there, so setup-ledger durability across sudden power loss is not promised.

package/docs/integrations.md

@@ -1,6 +1,6 @@
 # Client integrations
 
-Build and link the checkout first. Generated configurations use the `kith` executable already on PATH; they do not download an unverified package at hook execution time.
+Install Kith persistently or build and link the checkout first. On macOS/Linux, generated configurations use the `kith` executable already on PATH; they do not download an unverified package at hook execution time.
 
 | Selection | Files and behavior |
 | --- | --- |
@@ -50,7 +50,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. Windows is reported unvalidated. A missing/broken check exits nonzero and leaves configuration/state untouched.
+`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.
 
 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 +64,17 @@ 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.0`) 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.1`) 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.0","kith","mcp","--repo","/absolute/checkout"]}}}
+{"mcpServers":{"kith":{"command":"npx","args":["--yes","--package","kith-coord@0.1.1","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.
+
+
+## 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).

package/docs/path-and-scope-rules.md

@@ -36,7 +36,7 @@ Existing literal path prefixes are physically resolved before containment checks
 
 A wildcard can hide a symlink below its literal prefix. When a lexical comparison is disjoint, Kith checks relevant filesystem entries in active checkouts and retains exclusion if an alias makes the result uncertain. Scan errors or the 10,000-entry scan bound also retain exclusion. This favors extra conflicts over overlapping access. Release scopes or use narrower literal prefixes to reduce uncertainty.
 
-Path checks assume a stable layout during the check/write boundary. They do not provide protection against a hostile process swapping symlinks concurrently, hardlink aliases or clients bypassing Kith. Windows path behavior remains unvalidated.
+Path checks assume a stable layout during the check/write boundary. They do not provide protection against a hostile process swapping symlinks concurrently, hardlink aliases or clients bypassing Kith. Current source exercises native Windows absolute/Git-style concrete paths and internal/escaping directory junctions in the platform workflow. Concrete native Windows file paths accept backslash separators; scope expressions still use the documented forward-slash grammar. Native shell hooks remain unsupported.
 
 ## Integration and conflicts
 

package/docs/reliability.md

@@ -33,11 +33,13 @@ These are test scenarios, not universal guarantees. CI coverage and real usage n
 
 **Bash recovery.** Snapshots skip large files, symlinks, and generated/dependency directories. One snapshot is stored per agent. Overlapping commands can replace snapshots, and a shared-workspace snapshot cannot distinguish a sibling's legitimate concurrent edits from a command's unauthorized edits. The default saves current and pre-command recovery copies without changing workspace bytes. Explicit library callers can opt into `restoreLockedFiles: true` only when they control all writers; restoration is best effort and can restore older bytes. Prefer worktrees. This is not a safe attribution or security mechanism.
 
+**Native Windows.** Version 0.1.1 validates MCP claims, worktrees, ports, integration, killed-owner recovery and conservative setup. Supervised mutex commands and shell hooks remain refused; use macOS/Linux or WSL for those guarantees. See [platform evidence](client-validation.md#native-windows). These fixes are included in npm `kith-coord@0.1.1`.
+
 **Ports.** A reservation coordinates Kith clients but releases its OS probe socket immediately. Another process can bind the port before your service does. Handle bind failures.
 
 **Git.** Integration targets the currently checked-out branch, not a hardcoded main branch. External Git writers can race with integration. Dependency hydration and speculative verification may run project code with your privileges. Verification uses a shared dependency symlink in the staging tree; choose checks that do not mutate shared dependencies. Worktree hydration can copy `.env` files; treat those worktrees as sensitive.
 
-**Configuration.** Preflight refuses malformed selected configuration before writes. Private setup backups are persisted before client-file writes; disk failure can still leave partial configuration requiring inspection. Uninstall restores only unchanged recorded writes and preserves user edits, coordination state and the ignore rule. Custom Git hooks and third-party hook managers require manual integration. See [setup recovery](integrations.md#diagnose-and-undo-setup).
+**Configuration.** Preflight refuses malformed selected configuration before writes. Private setup backups are persisted before client-file writes; disk failure can still leave partial configuration requiring inspection. Backup files are flushed on Windows, but Node cannot flush parent directory entries there; setup-ledger survival across sudden power loss is not guaranteed. Uninstall restores only unchanged recorded writes and preserves user edits, coordination state and the ignore rule. Custom Git hooks and third-party hook managers require manual integration. See [setup recovery](integrations.md#diagnose-and-undo-setup).
 
 ## Recovery
 

package/docs/validation/2026-10-20-cursor-cli.json

@@ -0,0 +1,38 @@
+{
+  "client": "cursor",
+  "version": "2026.10.19-6bbf2c4",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "isolated",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_start_session",
+        "kith_get_status",
+        "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
+}

package/docs/validation/2026-10-20-cursor-hook-unavailable.json

@@ -0,0 +1,18 @@
+{
+  "client": "cursor",
+  "version": "2026.10.19-6bbf2c4",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "hook-failure",
+      "passed": true,
+      "checks": [
+        "native edit attempted once",
+        "tool denied",
+        "marker absent"
+      ]
+    }
+  ],
+  "passed": true
+}

package/docs/validation/2026-10-20-windows-node-22.13.0.json

@@ -0,0 +1,17 @@
+{
+  "platform": "win32",
+  "node": "v22.13.0",
+  "passed": true,
+  "phase": "complete",
+  "checks": [
+    "owned sessions, refused overlap and refused capability theft",
+    "native absolute and Git-style paths, literal brackets, internal/escaping links, isolated worktrees and distinct port leases",
+    "unsupported process-group supervision refused without execution or leaked guards",
+    "dirty preview refusal, committed preview, failed verification and successful retry/integration",
+    "killed MCP owner recovered with new capability and preserved worktree, then integrated",
+    "offline inspection preserves original state; tracked MCP setup/uninstall preserves integrated work"
+  ],
+  "git": "git version 2.56.0.windows.2",
+  "sourceCommit": "5babcfee7fd8977352f3b58ac9e54fdd45e2ce79",
+  "hostedRun": "https://github.com/connorhriley/kith/actions/runs/39408240569"
+}

package/docs/validation/2026-10-20-windows-node-24.json

@@ -0,0 +1,17 @@
+{
+  "platform": "win32",
+  "node": "v24.21.0",
+  "passed": true,
+  "phase": "complete",
+  "checks": [
+    "owned sessions, refused overlap and refused capability theft",
+    "native absolute and Git-style paths, literal brackets, internal/escaping links, isolated worktrees and distinct port leases",
+    "unsupported process-group supervision refused without execution or leaked guards",
+    "dirty preview refusal, committed preview, failed verification and successful retry/integration",
+    "killed MCP owner recovered with new capability and preserved worktree, then integrated",
+    "offline inspection preserves original state; tracked MCP setup/uninstall preserves integrated work"
+  ],
+  "git": "git version 2.56.0.windows.2",
+  "sourceCommit": "5babcfee7fd8977352f3b58ac9e54fdd45e2ce79",
+  "hostedRun": "https://github.com/connorhriley/kith/actions/runs/39408240569"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kith-coord",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local coordination for cooperating coding agents: work claims, isolated worktrees, shared resources, and verified integration without a hosted service.",
   "type": "module",
   "bin": {