kith-coord 0.0.0-stage → 0.1.0

package/docs/protocol.md

@@ -0,0 +1,35 @@
+# Kith coordination protocol 1.0
+
+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.
+
+## Versioning and schemas
+
+`KITH_PROTOCOL_VERSION` and status responses advertise `1.0.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.
+
+## 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. Tokens are returned at grant/resume and must not be logged. Public status omits capabilities and their hashes.
+- `kith_heartbeat` renews an owned active generation before expiry (five minutes by default). It cannot revive an expired or completed generation. Engine startup may reap expired/dead owners and requeue unfinished tasks. Active supervised command guards remain until shutdown is confirmed.
+- `kith_begin_work` declares an intent and atomically acquires its supported scope claims. An overlapping exclusive claim returns a conflict. Use `isolateWorktree:true`, and edit only the returned `worktree.worktreePath`. Worktrees separate files while claims describe cooperative ownership across checkouts.
+- `kith_check_and_lock_files` acquires file/glob/symbol claims using fencing generations. See [scope rules](path-and-scope-rules.md); unsupported patterns are rejected. Direct filesystem writes and bypassed hooks are outside this protocol's enforcement boundary.
+- `kith_add_task` adds tasks with priority, scope and optional `dependsOn`. `kith_claim_next_task` atomically claims the next unblocked task and its scope. `kith_get_status` lists tasks. These are the canonical names; there are no redundant task aliases or capability-matching scheduler.
+- `kith_record_file_edit` reports actual worktree changes. `kith_publish_contract` publishes an explicit interface record. Contract analysis and exact-name reuse hints are advisory, not proof of semantic compatibility.
+- `kith_acquire_port` reserves a port among Kith clients. The OS probe socket is released; unrelated processes can still bind it. `kith_run_with_mutex` executes literal argv under a renewable named FIFO mutex and persistent process-group guard. Cancellation/disconnect stops the guarded command before release. Do not detach protected work from its supervised group.
+
+## Workspace observation and integration
+
+`kith_get_status` preserves agents, tasks, locks, contracts, conflicts, resources, merge queue, quarantine and events. It adds `protocolVersion`, `mutexWaiters` (ticket order), `commandGuards`, and `workspaces`. Normal status observes active owners; offline inspection also includes retained recorded worktrees. Each workspace reports its path, recorded and actual branch, HEAD, dirty paths (including rename sources), last commit time/age, last heartbeat, lease expiry, availability, and dirty-file overlaps with active peers. `ahead`/`behind` compare against `comparisonBase`, the selected integration checkout's observed HEAD. Commit age is descriptive; an old commit is not evidence of a dead agent. Missing/unreadable workspaces are marked unavailable, not clean. Git observations are sequential snapshots, not a transaction over all files/checkouts.
+
+`kith_preview_integrate` requires an owned registered worktree on its recorded branch, committed source changes, and a clean integration target. It reports frozen `sourceHead`/`targetHead`, branch names, `clean`, and exact Git conflict paths. Dirty inputs return `ok:false` and are not checkpointed. Git may write unreachable merge-tree objects, but preview never stages files, advances refs or rewrites worktree contents. Authorization can renew the session and deliver an event delta. A clean preview does not run project verification or guarantee a later integration: inputs can change.
+
+`kith_complete_work` checkpoints source changes and integrates through a separate staging worktree into the selected checkout's current branch. Supply `verificationCmd`; without it, only Git mergeability is checked. Dirty/racing targets, Git conflicts and failing or mutating verification refuse integration. Failure retains source work, task and claims for repair/retry. Successful completion releases ownership/resources and retains the source worktree for explicit inspection/removal. External Git writers must coordinate too.
+
+## Offline inspection
+
+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.

package/docs/reliability.md

@@ -0,0 +1,78 @@
+# Reliability contract and recovery
+
+Kith coordinates cooperating coding agents through work claims, isolated worktrees, shared local resources and verification before integration. This contract describes tested behavior and recovery boundaries.
+
+Scope intersection is exact within the documented grammar; unsupported scopes are rejected. Contract analysis is advisory. Kith does not provide an OS sandbox, distributed consensus, or proof that two changes are semantically compatible.
+
+## Behavior covered by regression tests
+
+- Conflicting exclusive file locks and task claims have unique owners under simultaneous process contention.
+- Port reservations are rechecked atomically after asynchronous OS probes; exhaustion returns an error.
+- Setup previews without writes, preserves unrelated JSON settings, and rejects malformed config before writing selected configuration.
+- Worktree creation refuses an existing path or branch; removal refuses local, untracked, or ignored changes.
+- Integration refuses a dirty target and concurrent Kith integrations; failed or mutating verification preserves the target and source worktree for retry. Checks cannot change the candidate commit, tracked/index contents, or leave new nonignored files behind.
+- Unresolved Git conflicts fail integration without custom source/JSON rewriting. Source and target work remain available for explicit repair and retry.
+- Shadow-tree deletions reach Git; invalid merge inputs surface errors.
+- Bash recovery preserves current workspace bytes by default and saves before/after copies.
+- Event pagination does not acknowledge unseen events.
+- Commands passed after `--` retain their argument boundaries and child exit status.
+- Long commands renew leases; expiry, cancellation, supervisor death, and suspension do not permit overlapping guarded command groups.
+- FIFO tickets survive release, and cancelled waiters do not block the queue.
+- Separate CLI/MCP clients cannot mutate a live ID without its capability; old tokens cannot clean up a replacement session.
+- Generated hook commands, MCP wire initialization/calls, worktree reporting, failed verification followed by repair/retry, completion, and disconnect recovery run end to end against actual subprocesses.
+- A killed MCP owner can be recovered from a stopped database/WAL backup: its task is requeued, old capability rejected and worktree preserved for a new owning session.
+- Unknown or missing schema versions are refused before writable database setup. Failed legacy migrations roll back ownership/schema changes and preserve workspace and recovery files.
+
+These are test scenarios, not universal guarantees. CI coverage and real usage need to grow together.
+
+## Important limits
+
+**Hooks.** Clients must actually invoke hooks, use the same repository state, and agree on agent IDs. Missing or bypassed hooks do not prevent filesystem writes. Claude/Cursor hooks need matching `KITH_AGENT_ID` and `KITH_SESSION_TOKEN` when mixed with CLI commands. Malformed pre-tool execution errors exit with status 2, which the client uses to block the tool. Some payload shapes and client versions remain untested.
+
+**Sessions and leases.** Mutations require a capability bound to the active session generation. Process anchors are fixed on resume, real process identities replace test liveness sentinels, and expired/completed sessions cannot be revived by heartbeat. Sessions default to five minutes; use heartbeat before expiry. Supervised command mutexes renew their leases and preserve FIFO tickets across handoff. Active command-group guards survive expiry and are released only after the group stops. A protected daemon that escapes its group is outside this boundary. See [sessions and mutexes](sessions-and-mutexes.md) for lifecycle, cancellation, and upgrade details.
+
+**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.
+
+**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).
+
+## Recovery
+
+1. Stop all clients, writers and supervised commands. Inspect Git status in every worktree. Use `kith status --offline` or `kith recover` for inspection without migration/reaping; `kith doctor` diagnoses configuration/runtime too. These commands copy the database and matching sidecars into a private temporary directory, validate/read that copy, and leave original bytes alone. An unstable or damaged snapshot is reported unavailable. Normal CLI/MCP status opens the engine and may migrate or reap owners.
+2. Preserve worktree contents and quarantine files before removing state. Never delete `.coord` as routine cleanup: it contains worktrees, snapshots, and quarantine backups.
+3. If integration reports busy after a crash, inspect `.coord/merge-train.lock`, confirm its process is no longer running, and preserve any `_merge_train_*` worktree before manually removing the stale lock.
+4. Repair conflicts or failed checks in the source branch/worktree, then retry integration on the same session with a suitable verification command. Use checks that leave tracked/index contents and HEAD unchanged. Put formatters and fixers in the source worktree first. Ignored build/test outputs and Kith's unchanged dependency hydration are allowed; new nonignored staging files are rejected.
+5. To remove a worktree, commit or preserve local files first. After completing its session, start a new maintenance generation with `kith session start --agent <id> --new --owner-pid "$$" --shell`. Kith deliberately does not force removal.
+6. Inspect `mutex_runs` before manually removing a stuck command guard. Confirm its worker group and protected descendants cannot still execute. A process that escaped the group may require external recovery. Never clear a live guard to bypass a busy result.
+
+### Stopped database backups and interrupted agents
+
+Preserve `state.db` together with any matching `state.db-wal` and `state.db-shm` files after every client/writer has stopped. Keep worktrees, snapshots, quarantine copies and the private `setup/` ledger too. `recover` reports retained worktree directories, recorded owners, expired claims, unfinished integrations and lock-file presence; it does not repair or release anything. A crash can leave committed data only in the WAL; copying `state.db` alone can lose it. Restore the database and its matching sidecars as one stopped set, preserving the current set separately first. Never mix a restored database with sidecars from another snapshot or restore while old clients remain alive. These are tested recovery scenarios, not a corruption-repair tool.
+
+After an MCP owner dies, reconnect and inspect the queued tasks and retained worktree before claiming work. `kith_claim_next_task` with the same agent ID can create a fresh session generation and retain that worktree; verify the returned task ID/scope before continuing because it claims the highest-priority eligible task. The old capability is invalid. Do not request another isolated worktree over the retained path: creation deliberately refuses to replace existing work. Repair/report edits there, then complete with a read-only project check.
+
+Startup also refuses missing/empty databases when worktrees or recovery files remain, orphan SQLite sidecars, missing required tables or ownership columns, invalid/regressed fencing counters and SQLite-detected page damage. It preserves that state for inspection; it does not reconstruct lost ownership. Empty first initialization can be retried only when no recovery files remain. Fencing exhaustion fails without rounding or resetting the counter.
+
+Unsupported or missing schema metadata requires inspection of a preserved copy. Do not edit the version value to force an upgrade. A supported schema-1 upgrade invalidates legacy ownership and requeues unfinished tasks; an error rolls back those database changes. A process killed after migration writes but before commit is covered by a regression that reopens the old state, retries the upgrade and reclaims the queued task without changing unfinished files or recovery copies. Stop older clients before upgrading or retrying.
+
+The SQLite implementation requires Node's unflagged SQLite API: [Node SQLite documentation](https://nodejs.org/download/release/latest-jod/docs/api/sqlite.html). Generated Claude integration follows the [hook reference](https://code.claude.com/docs/en/hooks) and [project MCP configuration](https://code.claude.com/docs/en/mcp).
+
+## Existing databases
+
+No full-text SQLite extension is required. Contracts, tasks, locks and supervised commands use the canonical tables on every supported runtime. Older derived `contracts_fts` tables are left intact but are no longer read or maintained. Stop all clients before upgrading. Do not mix versions or rely on downgrading to an older search index after new contract writes. No schema reset, new tables or automatic repair are involved.
+
+## Paths, scopes and merge boundaries
+
+See [path and scope rules](path-and-scope-rules.md) for repository discovery, literal route filenames, supported glob grammar, symlink handling and conflict refusal. These checks assume cooperating writers: a process replacing filesystem links between a check and a write can race path checks. Hardlink aliases and a hostile filesystem writer are outside the containment boundary. Git merges non-conflicting edits; project verification still determines whether that combined change works.
+
+
+## Observations and previews
+
+Workspace status distinguishes recorded branch/lease from observed Git state. Dirty overlap means the same relative path is changed in multiple active checkouts; it does not prove a merge conflict. Ahead/behind uses the reported target HEAD, not a fetched remote branch. Commit age does not trigger release; ownership TTL and heartbeat remain authoritative. Unavailable observations must not be interpreted as clean.
+
+`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.

package/docs/roadmap.md

@@ -0,0 +1,42 @@
+# 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.
+
+## 1. Reliability foundation — implemented
+
+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.
+
+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.
+
+## 2. Session, command, and client validation — implemented
+
+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`.
+
+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.
+
+## 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.0 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.

package/docs/sessions-and-mutexes.md

@@ -0,0 +1,97 @@
+# Sessions, ownership, and supervised commands
+
+## Start through MCP
+
+For agents, prefer `kith_begin_work` with a unique ID, explicit scopes and `isolateWorktree: true`. One persistent MCP connection retains its capabilities internally. Edit only the returned worktree, report edits with `kith_record_file_edit`, run serialized commands with `kith_run_with_mutex`, and complete with a project verification command. No environment exports are required for MCP-only setup. Keep the connection alive and heartbeat before expiry. See [client setup](integrations.md) and [examples](usage.md).
+
+## Share a session with CLI and hooks
+
+A session has a unique agent ID, a random 256-bit capability, a generation (epoch), a kernel process identity, and an expiry. An ID alone grants no ownership. The database stores a hash of the capability; public agent records and event/status responses omit it.
+
+For a terminal workflow, initialize the environment before launching an agent client:
+
+```sh
+eval "$(kith session start --agent auth-worker --owner-pid "$$" --shell)"
+kith begin --title "Refresh authentication" --scope "src/auth/**" --worktree
+# Edit in the returned worktreePath.
+# Launch the hook-enabled client from this environment.
+kith heartbeat
+kith complete
+unset KITH_AGENT_ID KITH_SESSION_TOKEN
+```
+
+`--shell` emits quoted exports for `KITH_AGENT_ID` and `KITH_SESSION_TOKEN`. Treat the token like a password: do not paste it into issues, commits, or logs. Passing `--session-token` explicitly is supported, but an environment variable avoids placing it in the command line.
+
+CLI sessions are anchored to their parent process unless `--owner-pid` is supplied. Shell export mode requires `--owner-pid "$$"`: sh/bash command substitution can create a transient parent, so the outer shell PID must be passed explicitly. Library and MCP sessions default to their own process. Resuming a session does not rebind that anchor. Keep the owner process alive; use heartbeats before the default five-minute expiry. Completed, expired, and replaced capabilities cannot renew or mutate the new owner’s state.
+
+`kith session end` abandons a session and requeues unfinished tasks. `kith complete` explicitly completes work. To reuse a completed/expired ID intentionally, create a new generation:
+
+```sh
+eval "$(kith session start --agent auth-worker --new --owner-pid "$$" --shell)"
+```
+
+`--new` does not steal a live session. Worktree paths are retained across generations. After successful worktree integration, use a new maintenance session to run `kith worktree remove`; changed, untracked, and ignored files still prevent removal.
+
+## MCP ownership
+
+`kith_begin_work`, `kith_claim_next_task`, and `kith_start_session` return a session token when they register or resume a session. A single stdio connection retains its granted capabilities internally. Another connection must explicitly present the capability to resume the same live ID. All agent-scoped mutation tools accept an optional `sessionToken`; a mixed CLI/hook/MCP client can inherit `KITH_AGENT_ID` and `KITH_SESSION_TOKEN` instead.
+
+`kith_heartbeat` renews an active owned session. `kith_get_status` without an ID is a public read; supplying an ID also consumes that session’s event cursor and requires ownership. Responses provide `structuredContent`, a separately parseable JSON text block, and any coordination delta in another text block. Tool conflicts set `isError: true`.
+
+Sessions started by the MCP process are abandoned on connection close; unfinished tasks are requeued. A hard crash is reclaimed by another operation’s process/expiry scan. A CLI command sharing that capability stops when its owning MCP session is lost.
+
+The protocol response format follows the [MCP tool-result specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+## Supervised mutex commands
+
+```sh
+kith mutex --name package-install --lease-ms 30000 --wait-ms 60000 --timeout-ms 600000 -- pnpm install
+```
+
+The wait timeout defaults to 60 seconds. Execution has no timeout unless `--timeout-ms` is supplied. The mutex lease defaults to five minutes and is renewed at roughly one-third of the lease duration. Output streams to the terminal. Child exit statuses are preserved. SIGINT/SIGTERM cancel queued or running work; the CLI exits with 130/143 after cleanup.
+
+A standalone mutex invocation without a pre-existing capability creates a temporary session anchored to that invocation. Reusing a live agent ID still requires its capability.
+
+The runner records an execution guard before starting a detached process-group leader. The leader cannot launch the command until its group has been recorded and the supervisor sends a private IPC start message. A live group blocks competing acquisitions even if the resource lease or agent session has expired. If renewal fails, cancellation occurs, output exceeds its configured limit, or an execution timeout fires, Kith terminates the group before releasing the guard. It escalates from SIGTERM to SIGKILL when needed, checks the recorded group-leader identity before signalling, and bounds shutdown waits. Signal-permission errors are contained; an unconfirmed shutdown retains its guard. A worker loses permission to run when its supervisor’s IPC connection closes.
+
+FIFO tickets live separately from the current resource lease, so releasing a mutex preserves queue order. Cancelled, dead, expired, and replaced-session waiters are pruned. Concurrent commands from the same session also serialize. Package-manager shims recognize an existing supervised package-install context, so an install wrapped explicitly in that mutex does not deadlock by reacquiring itself. This context marker is cooperative, not a security boundary. A general session heartbeat does not renew mutex leases: manual lease users must call `renewMutex` with the exact acquisition token.
+
+This uses [Node’s POSIX detached-process support](https://nodejs.org/download/release/v22.23.0/docs/api/child_process.html). Commands must keep protected work in the supervised process group. Deliberately detached daemons, remote jobs, privileged processes that cannot be terminated, and malicious same-user code require a different lock/enforcement boundary. If Kith cannot prove that a guarded group stopped, it retains the guard and fails closed rather than granting a second runner.
+
+## Library use
+
+`executeWithMutex` is asynchronous. Await it before closing the engine; `close()` refuses an engine with active supervised commands.
+
+```js
+import { KithEngine } from 'kith-coord';
+const engine = new KithEngine('/absolute/path/to/repository');
+try {
+  const session = engine.fencing.registerAgent({ id: 'worker' });
+  // Another engine may resume with: fencing.resumeSession('worker', session.sessionToken).
+  const result = await engine.broker.executeWithMutex({
+    agentId: 'worker', mutexName: 'install', command: ['pnpm', 'install'],
+    leaseDurationMs: 30_000, commandTimeoutMs: 600_000,
+  });
+  console.log(result.exitCode);
+} finally { engine.close(); }
+```
+
+The API also accepts an AbortSignal, `timeoutMs` for queue waiting, `killGraceMs`, output callbacks, and `maxOutputBytes` (16 MiB by default). Resource renew/release operations require their exact fencing token, including rejection of invented future tokens.
+
+## Upgrade from schema 1
+
+Stop all old Kith clients and running commands before upgrading. The schema-2 migration invalidates legacy sessions that have no capabilities, clears their coordination leases/conflicts, and requeues unfinished tasks. It preserves workspace files, worktrees, snapshots, and quarantine copies. Create fresh sessions after upgrading. Do not run an old binary against the upgraded database.
+
+For a database backup, stop writers and use a SQLite-aware backup or preserve the database together with its WAL/SHM files. Do not copy a live `state.db` alone and assume it is complete. Broader backup/restore and downgrade tooling remains future work.
+
+## Commands from sandboxed MCP clients
+
+On the validated macOS Codex version, the sandboxed native shell cannot inspect process identities, so direct CLI mutex execution fails closed with `Cannot inspect mutex waiter process`. Use `kith_run_with_mutex` on the already-owned MCP connection instead:
+
+```json
+{"agentId":"worker","mutexName":"package-install","command":["pnpm","install"],"leaseDurationMs":30000,"commandTimeoutMs":600000}
+```
+
+The executable and arguments remain separate. The working directory defaults to the registered worktree (otherwise the repository); a supplied `cwd` must resolve inside that root. The server renews the mutex while the command runs and stops it on request cancellation or connection loss, including borrowed sessions. A disconnected borrowed session retains its original owner after its command stops. Nonzero command exits set `isError: true` and retain the actual `exitCode`. Execution defaults to a 60-second timeout and 64 KiB output limit; bounded overrides are supported. Increase the client's MCP tool timeout as needed for longer commands.
+
+This tool runs with the coordinator process permissions, outside the native client's command sandbox. Review and approve it as command execution. Cwd validation selects the working directory; it does not contain what a program can access. Use isolated worktrees and declared scopes for cooperating writers. Session capabilities never need to appear in the command arguments.

package/docs/usage.md

@@ -0,0 +1,101 @@
+# MCP, CLI and library workflows
+
+## Recommended: MCP and isolated worktrees
+
+Connect through the [MCP-only client setup](integrations.md). Each parallel agent uses its own MCP connection and worktree. No shell exports are needed when using only MCP. The connection retains its granted capability; another connection needs that capability to resume the same ID.
+
+Call these tools on the same connection:
+
+```text
+kith_begin_work      {"agentId":"auth-worker","title":"Refresh authentication","scopeGlobs":["src/auth/**"],"isolateWorktree":true}
+# Edit files under the returned worktree.worktreePath.
+kith_record_file_edit {"agentId":"auth-worker","filePath":"src/auth/middleware.ts"}
+kith_run_with_mutex  {"agentId":"auth-worker","mutexName":"project-checks","command":["pnpm","typecheck"]}
+kith_heartbeat       {"agentId":"auth-worker"}
+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).
+
+## CLI fallback: keep the owning shell alive
+
+CLI commands and Claude edit hooks need the same capability environment. Start from one persistent shell, then launch hook clients from it. Separate stateless shell calls do not preserve these exports or the owning shell process.
+
+Run from the repository root, or pass `--repo /absolute/path`:
+
+```sh
+eval "$(kith session start --agent auth-worker --owner-pid "$$" --shell)"
+kith begin --agent auth-worker --title "Refresh authentication" --scope "src/auth/**" --worktree
+# Edit in the worktreePath returned in the JSON result.
+kith status
+kith heartbeat --agent auth-worker
+kith complete --agent auth-worker --verify "pnpm typecheck"
+# Open a maintenance generation to remove the retained worktree explicitly.
+eval "$(kith session start --agent auth-worker --new --owner-pid "$$" --shell)"
+kith worktree remove --agent auth-worker
+kith session end
+unset KITH_AGENT_ID KITH_SESSION_TOKEN
+```
+
+Quote globs so the shell does not expand them. CLI scopes are comma-separated. Use `file:src/routes/[id]/page.tsx` for a literal filename containing glob syntax; see [scope grammar and discovery](path-and-scope-rules.md). An ID alone cannot resume another session. Dead or expired sessions release coordination resources when a mutating operation reaps them. Active supervised command guards survive expiry until shutdown is confirmed.
+
+Completion checkpoints uncommitted worktree changes and integrates into the branch currently checked out in the selected repository checkout (`--repo` when supplied). The target must be clean. A verification failure leaves the target unchanged and the worktree available for repair. Successful completion also keeps the worktree for inspection; removal is explicit and refuses dirty, untracked, or ignored work. Existing branches are never reset to create a worktree. Hydration tries filesystem clones and falls back to an independent copy; cost depends on the filesystem and dependency size.
+
+A verification command is optional. Without one, integration checks Git mergeability only. Choose a command that actually checks your project.
+
+## Other CLI workflows
+
+These agent-scoped commands assume an active session. Start one before claiming work or reserving resources:
+
+```sh
+eval "$(kith session start --agent worker-1 --owner-pid "$$" --shell)"
+
+# Task dependencies
+kith task add --id schema --title "Billing schema" --scope "src/db/**"
+kith task add --id api --title "Billing endpoints" --depends-on schema --scope "src/api/**"
+kith task claim --agent worker-1
+
+# Inspect worktrees, overlaps, relative commits, FIFO tickets and command guards
+kith status
+# Offline observations do not reap or migrate
+kith status --offline
+kith recover
+kith doctor
+# Preview committed source/target trees; dirty inputs are refused
+kith worktree preview --agent worker-1
+
+# Allocate a cooperating client's port; start your service promptly
+kith port --agent worker-1 --service web
+
+# Serialize commands; argument boundaries are preserved after --
+kith mutex --agent worker-1 --name package-install -- pnpm install
+
+# Start the MCP stdio server
+kith mcp
+```
+
+The `coord` executable is an alias for `kith`. The library exports `KithEngine` and its component classes for custom integrations:
+
+```js
+import { KithEngine } from 'kith-coord';
+const kith = new KithEngine('/absolute/path/to/repository');
+try {
+  kith.fencing.registerAgent({ id: 'custom-worker' });
+  const result = kith.locks.acquireLocks({
+    agentId: 'custom-worker', patterns: ['src/auth/**'],
+  });
+  console.log(result);
+} finally {
+  kith.close();
+}
+```
+
+## End a session
+
+When abandoning a task, use `kith session end` from the shell that owns the session. After completion or ending, remove the exported credentials:
+
+```sh
+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.

package/docs/validation/2026-10-19-claude-client-report.json

@@ -0,0 +1,67 @@
+{
+  "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"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    },
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    },
+    {
+      "scenario": "hook-failure",
+      "passed": true,
+      "checks": [
+        "native Write attempted once",
+        "tool denied",
+        "marker absent"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native CLI workflows, renewable MCP command supervision and failure probes; not GUI certification",
+  "configuration": "Generated settings; Codex receives server values via invocation overrides, Claude loads generated project hooks/MCP"
+}

package/docs/validation/2026-10-19-claude-hook-report.json

@@ -0,0 +1,33 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native CLI, disposable worktree fixture; not GUI certification",
+  "configuration": "Generated settings; Codex receives server values via invocation overrides, Claude loads generated project hooks/MCP"
+}

package/docs/validation/2026-10-19-claude-hook-unavailable-report.json

@@ -0,0 +1,20 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "hook-failure",
+      "passed": true,
+      "checks": [
+        "native Write attempted once",
+        "tool denied",
+        "marker absent"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Generated PreToolUse onFailure block; disposable macOS fixture"
+}

package/docs/validation/2026-10-19-claude-mutex-report.json

@@ -0,0 +1,34 @@
+{
+  "client": "claude",
+  "version": "2.1.301 (Claude Code)",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "hookDenialVerified": true,
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native MCP command supervision and editor workflow; macOS"
+}

package/docs/validation/2026-10-19-codex-client-report.json

@@ -0,0 +1,55 @@
+{
+  "client": "codex",
+  "version": "codex-cli 0.163.0-alpha.10.2",
+  "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"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released"
+      ]
+    },
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native CLI workflows, renewable MCP command supervision and failure probes; not GUI certification",
+  "configuration": "Generated settings; Codex receives server values via invocation overrides, Claude loads generated project hooks/MCP"
+}

package/docs/validation/2026-10-19-codex-mutex-report.json

@@ -0,0 +1,33 @@
+{
+  "client": "codex",
+  "version": "codex-cli 0.163.0-alpha.10.2",
+  "platform": "darwin",
+  "node": "v22.23.3",
+  "scenarios": [
+    {
+      "scenario": "shared",
+      "passed": true,
+      "tools": [
+        "kith_begin_work",
+        "kith_begin_work",
+        "kith_record_file_edit",
+        "kith_run_with_mutex",
+        "kith_complete_work",
+        "kith_get_status"
+      ],
+      "checks": [
+        "protected bytes unchanged",
+        "native edit",
+        "contract recorded",
+        "renewable MCP mutex command",
+        "verified integration",
+        "task completed",
+        "locks released",
+        "inherited owner preserved"
+      ]
+    }
+  ],
+  "passed": true,
+  "date": "2026-10-19",
+  "scope": "Native MCP command supervision and editor workflow; macOS"
+}