kith-coord 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+## 0.1.0 — 2026-10-20
+
+- Use the npm identity `kith-coord` with CLI `kith`. Protocol version 1.0.0 and storage schema 2 are independent. Earlier source manifests used 1.0.0 without a registry release.
+- Add optional Cursor native hooks and block/warn/off policy modes for native/Git hooks. Ownership and path checks remain mandatory; preserve custom hooks and update recognized generated guards in place.
+- Share CLI/MCP status assembly and report observed worktree branches, dirty paths/overlap, relative commits, heartbeat/commit age, FIFO waiters and command guards. Add owned committed-tree integration previews with exact Git conflict paths and dirty-input refusal.
+- Add offline status, recovery inspection and doctor without initializing, migrating, reaping or writing the original database/sidecars. Unstable/damaged state is unavailable rather than guessed clean.
+- Save private per-checkout setup backups before configuration writes. Uninstall restores only unchanged tracked writes, retaining edited configuration, state, worktrees, recovery copies and ignore protection.
+- Export the 13 canonical MCP input schemas from actual stdio discovery and check snapshot drift in CI; document protocol ownership and integration semantics. No database tables or runtime dependencies added.
+
+## Unreleased
+
+### Coordination positioning
+
+- Describe Kith consistently as local coordination for work claims, isolated worktrees, shared resources and verified integration across README, CLI, MCP instructions and package metadata.
+- Remove maturity labels from the current product description while retaining the documented support matrix, enforcement boundaries and recovery contract.
+
+### Subtraction pass (supersedes earlier unreleased advisory/UI behavior)
+
+- Remove `top`/`ui` and their dashboard modules. Use existing CLI/MCP status; normal engine startup may migrate or reap state, so preserve stopped recovery data first.
+- Remove fuzzy intent blocking, synonym/duplicate scoring, full-text search maintenance and their public APIs/result fields (`semanticOverlaps`, `duplicates`, `autoMergeableFiles`). Scope ownership remains authoritative; similar task titles no longer block disjoint scopes. The semantic-overlap `force` option is removed.
+- Retain a small non-blocking reuse hint for exact, case-sensitive symbol names of the same kind in other files, queried from canonical contracts and returned through existing edit warnings. No scoring, synonym rules, new API, search index or schema change.
+- Refuse unresolved Git conflicts instead of rewriting source/JSON. Remove `checkAdditiveMergeability` and `autoResolvedFiles`; retain worktrees/checkpoints for explicit repair and verification retries. TypeScript is a development dependency only.
+- Share CLI/MCP begin/complete orchestration. Default init configures MCP clients/instructions; hooks and shims require explicit selection. Existing guards and state are preserved. No schema changes; legacy derived search tables are left unused. Stop older clients before upgrading; mixed versions/downgrades are not supported by this change.
+
+
+### Interrupted upgrades and damaged-state refusal
+
+- Refuse missing/empty databases with retained recovery data, orphan sidecars, incomplete ownership schema, invalid/regressed counters and SQLite-detected page damage. Keep state intact for inspection rather than recreating empty ownership tables.
+- Fail safely at fencing exhaustion and validate state before init writes client configuration.
+- Test a real upgrade process killed before commit, followed by rollback/retry and recovery of unfinished work. Retain interrupted first-start retries when no coordination/recovery data exists.
+
+### Recovery and verification integrity
+
+- Freeze the integration candidate before verification and reject checks that change HEAD, tracked/index contents or leave new nonignored files in staging. Preserve source work and claims so callers can repair and retry.
+- Validate existing schema metadata read-only before writable setup; refuse unsupported/malformed/missing versions instead of changing the database first. Recheck within the migration transaction.
+- Cover killed MCP ownership, stopped WAL backup restoration, new session generations, failed legacy migration rollback, and repair/retry through real clients. Native validation now checks an expected failed verification followed by successful completion.
+
+### Lean MCP onboarding and read-only observation
+
+- Recommend MCP ownership and one worktree per parallel agent in setup instructions and examples. Add `init --mcp-only` to configure clients without installing hooks or shims; preserve existing guards with a review warning.
+- Make `top` read existing state without initialization, migrations, reaping or event acknowledgement. Show retained worktree paths, FIFO tickets without a current lease, command guards and the newest events.
+- Replace the incorrect recovery claim that files were reverted with recorded copy locations. No schema changes or Git-status polling.
+### Native clients and hosted checks
+
+- Share coordination automatically across Git subdirectories, symlink aliases, linked checkouts and separate Git directories. Preserve selected-checkout Git operations, register linked session roots, inspect the invoking pre-commit index and refuse orphaned legacy checkout-local state.
+- Resolve physical paths before containment checks, reject external/dangling/looping symlinks and redirected coordination/configuration writes, skip source symlinks/nested repositories, and support literal framework route filenames.
+- Replace sample-based glob overlap with exact intersection of a documented grammar (`*`, `?`, whole-segment `**`, including dotfiles). Reject unsupported requests; retain exclusion for legacy scopes, wildcard aliases and changed symlink layouts.
+- Resolve source conflicts with a lazily loaded TypeScript parser and a narrow appended-declaration policy. Keep imports, initialization, top-level execution, binding collisions, invalid syntax and ambiguous Git stages/modes as conflicts. Preserve executable modes and NUL-delimited Git filenames; reject duplicate/lossy JSON values.
+
+- Fix startup on stock Node 22.13.0, which lacks SQLite FTS5. Detect optional full-text support, retain normal contract/name/type hints without it, and rebuild the derived index safely when switching runtimes. Expose runtime capabilities in CLI/MCP status.
+
+- Add `kith_run_with_mutex` for sandboxed MCP clients unable to inspect process identities in their native shell. Preserve ownership, renewable supervision and actual exit codes; cancel commands on request cancellation or connection loss before closing coordination state. Translate stdio EOF into graceful cancellation; the MCP SDK alone does not emit a close callback for stdin EOF. Commands run with server permissions and need client approval.
+
+- Add non-destructive Codex project MCP configuration with capability environment forwarding. Preserve custom Kith transports and malformed-config fail-before-write behavior.
+- Make generated Claude pre-hooks fail closed on launch failures on supporting client versions; rerun init to upgrade existing Kith hooks.
+- Add an opt-in native Codex/Claude runner checking real editor/MCP workflows and resulting repository state, with redacted reports and bounded runs.
+- Add manually dispatched CI, retained JUnit evidence and installed-package/two-client demo validation across Linux/macOS and Node 22.13/22/24.
+
+## Unreleased
+
+### Session ownership, supervision, and client validation
+
+- Add random session capabilities, hashed storage, fixed process anchors, generation checks, and exact fencing-token checks. ID-only renewal, completion, lock release, and mutation are rejected across engines/connections.
+- Remove simulated liveness sentinels from production. Recheck reaper decisions after acquiring the writer lock.
+- Add `session start [--shell] [--new]` and `session end`; CLI/hook sharing uses KITH_AGENT_ID and KITH_SESSION_TOKEN. MCP connections retain their capabilities and support explicit resume/heartbeat.
+- Make `executeWithMutex` asynchronous with renewable leases, persistent FIFO tickets, process-group guards, cancellation, execution timeouts, streaming callbacks, output bounds, and signal/child exit-status handling. Await commands before closing an engine.
+- Contain signal-permission errors, bound shutdown waits, check recorded process identity before signalling, and avoid recursive package-install shim acquisition.
+- Preserve live command guards across session/resource expiry; private IPC records the worker group before the protected command can start.
+- Return MCP structured content and separate JSON/delta text blocks; validate actual stdio and generated-hook workflows with independent clients.
+- Read worktree edit reports from actual worktree bytes and pass owning credentials to Git hooks during integration.
+- Add `pnpm demo` for two real MCP clients integrating independent worktrees, plus packaged-worker smoke coverage.
+- Upgrade the coordination schema to 2. Stop old clients/commands before upgrading: legacy sessions are invalidated, ownership leases cleared, and unfinished work requeued. Files/worktrees/quarantine are preserved.
+
+### Reliability and safe defaults
+
+- Preserve existing client settings, unrelated hooks, and MCP servers during setup. Add `init --dry-run` and `--only` integration selection. Invalid JSON stops configuration writes.
+- Put Claude project MCP configuration in `.mcp.json`. Generated hooks and MCP entries now invoke the locally installed `kith` executable instead of downloading a package with npx.
+- Refuse existing worktree paths/branches and refuse removal of changed, untracked, or ignored work. Keep worktrees after successful CLI/MCP completion for explicit inspection and removal.
+- Use independent copies when filesystem cloning is unavailable. `hydrationMethod` now reports `copy` instead of the previous shared `symlink` fallback.
+- Serialize Kith merge integrations, use unique staging trees, and reject dirty or changed integration targets.
+- Preserve complete appended source blocks; refuse non-additive JSON changes and duplicate newly-added export names.
+- Recheck port reservations transactionally and return errors on exhaustion.
+- Preserve command argument boundaries and child exit status for CLI mutex commands.
+- Block pre-tool hook processing errors and missed lock-acquisition races; preserve all event pages and shadow-tree file deletions.
+- Save Bash recovery copies without restoring shared workspace bytes by default. Library users controlling all writers can explicitly request `restoreLockedFiles: true`; `.before` recovery copies preserve pre-command bytes when available.
+- Add `kith heartbeat --agent <id>`; completed or expired sessions cannot be revived by heartbeat alone.
+
+### Project foundation
+
+- Set the Node requirement to 22.13+ on 22.x, or 24+; pin the development package manager.
+- Add real 50-process contention, CLI, regression, and clean packed-package consumer checks.
+- Add macOS/Linux CI, contributor and security guidance, MIT license text, architecture, integration details, reliability boundaries, and an ordered roadmap.
+
+### Upgrade notes from the prototype
+
+Review generated integrations before rerunning init. Existing Git hooks and legacy Kith hook entries are preserved and may need manual migration. Ensure the client process can resolve `kith` on PATH and use a stable `KITH_AGENT_ID` across CLI and hook calls. Automatic shared-file restoration, forced worktree replacement, and automatic worktree deletion are no longer defaults. Plan explicit worktree cleanup and preserve ignored files such as `.env`.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Community expectations
+
+Be respectful, specific, and constructive. Critique ideas and code without attacking people. Welcome questions and contributors with different levels of experience. Harassment, discrimination, threats, and publishing private information are unacceptable.
+
+Project maintainers may remove inappropriate content and restrict participation to protect contributors. Apply moderation consistently, explain decisions when safe, and handle reports confidentially. A private moderation contact must be established alongside the public upstream repository before community launch.

package/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to Kith
+
+Kith coordinates other people's uncommitted work. Preserving that work comes before convenience, automatic recovery, or speed claims.
+
+## Development
+
+Use Node.js 22.13+ (22.x) or 24+, Git 2.38+, and the pnpm version pinned in package.json.
+
+```sh
+corepack enable
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm test:package
+```
+
+`pnpm test` builds first because subprocess tests exercise the distributed JavaScript. Run `pnpm test -- tests/reliability.test.ts` for focused work. Test files run sequentially to avoid multiplying lifecycle timing workloads on constrained CI hosts; concurrency is exercised explicitly inside the tests. The 50-process test deliberately uses OS processes and a start barrier; do not replace it with synchronous callbacks wrapped in Promise.all.
+
+Run `pnpm demo` for a disposable two-MCP-client/worktree workflow. Ownership and supervision tests use real process identities, signals, expiry and client disconnects; keep those paths covered when changing lifecycle behavior.
+
+## Where to start
+
+| Area | Start here | Useful contribution |
+| --- | --- | --- |
+| Client integration | `src/cli/init.ts`, `src/cli/hook-handler.ts`, `src/mcp/server.ts` | A minimal fixture for an actual client payload or setup failure |
+| Ownership and lifecycle | `src/core/fencing.ts`, `src/core/broker.ts` | A reproducible stale-owner, cancellation, or disconnect edge case |
+| Git isolation | `src/core/worktree-cow.ts`, `src/core/merge-train.ts` | A fixture showing preserved work after a failed operation |
+| Source analysis | `src/core/ast-analyzer.ts`, `src/core/dep-graph.ts`, `src/core/dedup.ts` | A small syntax example that produces a false positive or missed hint |
+| First-run experience | `README.md`, `docs/integrations.md`, `examples/two-agents.mjs` | Reproduce the setup from a clean checkout and clarify a concrete stumbling block |
+
+For a first contribution, prefer a small reproduction or documentation correction over changes to locking or recovery semantics. Discuss a larger change in an issue before implementation. The [roadmap](docs/roadmap.md) lists the acceptance gates for broader work.
+
+## Proposing changes
+
+Open a focused issue or pull request describing the concrete problem, current behavior, desired behavior, and a reproducible example. For bugs, include OS, Node/Git versions, relevant commands, and redacted diagnostics. Never attach secrets or an entire `.coord` directory.
+
+Keep pull requests small enough to review. Add regression coverage for data loss, races, lifecycle changes, public API changes, and failure paths. Tests should assert outcomes, such as unchanged bytes or unique owners, rather than mirror implementation details. Include an upgrade note when changing generated client configuration or library behavior.
+
+Use `git diff --check` and `pnpm check` before submission. A reviewer should be able to understand the change without the authoring chat. Do not claim a latency, security property, or compatibility guarantee without reproducible evidence.
+
+## Extension points
+
+The public entrypoint is `src/index.ts`. `KithEngine` assembles storage, agent lifecycle, locks, tasks, source analysis, Git operations, and the resource broker. Client adapters should call those components rather than write SQLite rows directly. Keep client-specific behavior in the CLI/MCP layers. See [architecture](docs/architecture.md) and [roadmap](docs/roadmap.md).
+
+`pnpm test:package` builds and packs the distribution, installs it in an empty consumer project, and checks the CLI, packaged supervised worker, and library API. It needs registry access for runtime dependencies.
+
+Native client checks are opt-in: see [client validation](docs/client-validation.md). They require installed authenticated clients and consume model usage. CI uses no model credentials. Establish monitored security contacts before public launch or configuring a release workflow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/brand/readme-header.png" alt="Kith — Parallel agents. Shared direction. Local coordination for coding agents." width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://github.com/connorhriley/kith/actions/workflows/ci.yml"><img src="https://github.com/connorhriley/kith/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> · <a href="#see-it-work">Demo</a> · <a href="docs/integrations.md">Integrations</a> · <a href="docs/usage.md">CLI &amp; API</a> · <a href="CONTRIBUTING.md">Contribute</a>
+</p>
+
+**Local coordination for cooperating coding agents.**
+
+Claim work, isolate changes with Git worktrees, share local resources, and verify integration—without a hosted service.
+
+One agent changes an interface while another builds against it. Two agents edit the same file. Separate worktrees still compete for a dev-server port or a package install.
+
+Kith gives cooperating agents shared local state: who owns a task, which files are claimed, and which commands need to wait. Agents use its MCP server; CLI commands support local inspection and maintenance. Coordination lives in SQLite on your machine; Kith itself needs no hosted service or model API key.
+
+## What Kith does
+
+| Need | Kith provides |
+| --- | --- |
+| Keep tasks from overlapping | Scoped claims with conflict responses |
+| Give agents separate working files | Git worktrees with an explicit integration step |
+| Check work before integration | Your project's verification command |
+| Share local tools | Port reservations and supervised command mutexes |
+| See what is happening | Session/task state through `kith status` and MCP |
+
+Kith fits workflows where you already launch multiple coding agents and want them to coordinate. It does not choose models, write prompts, or launch a fleet for you. Worktrees separate files; Kith adds shared ownership and resource coordination.
+
+The [reliability contract](docs/reliability.md) defines ownership, verification, recovery and enforcement boundaries. Claims coordinate cooperating clients; hooks do not sandbox filesystem access. Scope matching follows a [documented grammar](docs/path-and-scope-rules.md). Contract-change reports and exact-name reuse hints are advisory.
+
+## Quick start
+
+Requires **Git 2.38+** and **Node.js 22.13+ on 22.x or Node.js 24+**. Development targets macOS and Linux. Windows is unvalidated.
+
+Install the release, then configure your project:
+
+```sh
+npm install --global kith-coord@0.1.0
+cd /path/to/your/project
+kith init
+```
+
+For source installation and the disposable demo, use the pinned **pnpm 10.20.0**:
+
+```sh
+git clone https://github.com/connorhriley/kith.git
+cd kith
+corepack enable
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+### See it work
+
+```sh
+pnpm demo
+```
+
+The demo starts **two real MCP clients**, gives each a separate Git worktree in a temporary repository, refuses an overlapping claim, records their edits, runs commands under a mutex, and verifies/integrates both changes. It removes the temporary repository afterward. No model calls or client credentials are needed.
+
+```text
+auth: claimed src/auth.mjs in an isolated worktree
+billing: overlapping claim on src/auth.mjs refused
+billing: claimed src/billing.mjs in an isolated worktree
+auth: checked its worktree through the MCP command supervisor
+auth: isolated edit reported, verified, and integrated
+billing: checked its worktree through the MCP command supervisor
+billing: isolated edit reported, verified, and integrated
+Two real MCP clients completed work in separate worktrees. Disposable example passed.
+```
+
+The implementation is in [examples/two-agents.mjs](examples/two-agents.mjs). This demonstrates the coordination protocol; [native-client validation](docs/client-validation.md) separately exercises installed coding clients.
+
+### Connect your client
+
+Link the built CLI, then switch to the repository you want to coordinate:
+
+```sh
+# From the Kith checkout
+pnpm link --global
+kith help
+
+# From your target repository, preview the selected integrations first
+kith init --dry-run
+kith init
+```
+
+Default setup installs MCP configuration for Claude, Codex and Cursor plus agent instructions, without adding hooks or package-manager shims. Review and commit the generated configuration before starting work; integration requires a clean target checkout. Restart your client with `kith` on its `PATH`. To select clients, use `--mcp-only --only claude,codex,agents`. Existing hooks are preserved; review warnings if they require an inherited session. See [hook setup](docs/integrations.md) if you need them.
+
+| Client | Setup and validation |
+| --- | --- |
+| Claude Code | MCP; optional edit hooks need shared session setup; recorded native CLI runs |
+| Codex | Project MCP configuration; recorded native CLI runs with configuration overrides |
+| Cursor | MCP and optional native hooks; generated-command fixtures tested; native application behavior unvalidated |
+| Other MCP clients | stdio server via `kith mcp`; client-specific validation required |
+
+Native checks are version-specific. GUI discovery and persisted project trust need separate checks. See [integration setup](docs/integrations.md), [recorded validation](docs/client-validation.md), and [session ownership](docs/sessions-and-mutexes.md) before mixing hooks, CLI commands, and MCP clients.
+
+The npm package is **`kith-coord`**, with the command name **`kith`**. For a pinned npx MCP launcher, see [registry setup](docs/integrations.md#registry-installation). The unrelated npm package `kith` is not this project.
+
+## How a task moves through Kith
+
+1. **Begin through MCP.** Call `kith_begin_work` with a unique `agentId`, explicit `scopeGlobs`, and `isolateWorktree: true`. The connection retains session ownership; no shell exports are needed for this MCP-only workflow.
+2. **Claim a scope.** Cooperating clients receive a conflict when an exclusive claim overlaps another claim.
+3. **Do the work.** Edit the returned `worktree.worktreePath`, report edits with `kith_record_file_edit`, and use `kith_run_with_mutex` for serialized commands. Heartbeat before expiry and keep the owning connection open.
+4. **Verify and complete.** For a worktree, Kith checkpoints changes and integrates through a separate staging worktree. The target must be clean. Supply a verification command to check more than Git mergeability.
+
+Failed verification leaves the target unchanged and keeps the worktree for repair. Successful integration also retains the worktree until explicit cleanup. External Git writers must still coordinate.
+
+Inspect through `kith_get_status` or `kith status`: worktree paths/branches, dirty-file overlap, ahead/behind, heartbeat/commit age and FIFO waiters are included. Use `kith_preview_integrate` for committed-tree conflict paths before completing. Normal status may reap expired owners. For non-mutating recovery inspection use:
+
+```sh
+kith status --offline
+kith recover
+kith doctor
+```
+
+Optional Claude/Cursor hooks support `--enforcement block` (default), `warn` and `off`; see [setup and safe uninstall](docs/integrations.md). The [versioned protocol](docs/protocol.md) records the tool schemas and ownership semantics.
+
+For MCP, CLI and library examples, see [workflows](docs/usage.md).
+
+## Project status
+
+The suite exercises process contention, session ownership, command cancellation and disconnects, generated hooks, MCP workflows, and worktree integration. Clean-package checks install the built distribution in a separate consumer project. Native-client reports include exact versions and outcomes.
+
+The CI badge links to current hosted results; local tests and recorded native runs do not establish that every platform or client release passes. Repository discovery, physical path checks, exact supported glob matching and Git conflict refusal have dedicated regressions. Recovery checks cover interrupted upgrades, stopped database/WAL backups and retained worktree continuation. The [reliability contract](docs/reliability.md) records the boundaries of those scenarios; native-client coverage is listed above.
+
+- [Reliability contract](docs/reliability.md): behavior, boundaries, and recovery
+- [Architecture](docs/architecture.md): storage, adapters, and Git integration
+- [Roadmap](docs/roadmap.md): priorities and completion gates
+- [Changelog](CHANGELOG.md): behavior changes and migration notes
+
+## Contributing
+
+The most useful contributions reproduce a concrete failure or improve a real multi-agent workflow. Include a disposable fixture, expected behavior, and a way to verify the change. Start with [contributor setup and entry points](CONTRIBUTING.md).
+
+For bugs, use the [bug report form](https://github.com/connorhriley/kith/issues/new?template=bug_report.yml). For a proposed workflow, use the [feature request form](https://github.com/connorhriley/kith/issues/new?template=feature_request.yml). Keep tokens, source snapshots, and `.coord` state out of public diagnostics; use the [security reporting guidance](SECURITY.md) for sensitive reports.
+
+[MIT licensed](LICENSE). Participation follows the [community expectations](CODE_OF_CONDUCT.md).

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security and reliability reports
+
+Use the latest reviewed source on `main` and include your commit or version when reporting an issue. Kith runs with the invoking user's privileges and cannot contain a malicious agent that can bypass hooks, write the coordination database, or invoke Git directly.
+
+Do not post exploit details, source snapshots, credentials, or quarantine contents in public issues. Use [GitHub private vulnerability reporting](https://github.com/connorhriley/kith/security/advisories/new), enabled on the canonical upstream. Include a minimal reproduction and affected version; do not disclose the report in a public issue.
+
+For ordinary reliability bugs, provide a minimal disposable repository and redacted steps. Quarantine and snapshot files can contain full source files and secrets. Treat `.coord` as sensitive local state, keep it out of Git, and inspect it before sharing diagnostics.
+
+Session capabilities protect cooperative client ownership and are omitted from status/events. They do not protect against a process with permission to read another process environment or rewrite the local SQLite database. Keep KITH_SESSION_TOKEN out of public diagnostics. See [session lifecycle](docs/sessions-and-mutexes.md).
+
+MCP command execution (`kith_run_with_mutex`) and merge verification execute programs with the coordinator process permissions. They are outside a native client shell sandbox and must be reviewed/approved accordingly. Working-directory checks do not sandbox programs.
+
+Read [the reliability contract](docs/reliability.md) for known enforcement and recovery limits.

package/assets/brand/avatar.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" role="img" aria-label="Kith avatar"><title>Kith avatar</title><rect width="256" height="256" rx="52" fill="#0B0F0E"/><g transform="translate(51 41) scale(1.6)"><path d="M25 57L49 33L89 73Q92 76 92 80V96Q92 100 88 100H69Q65 100 62 97Z" fill="#09624F"/><path d="M8 44L58 1Q59 0 63 0H81Q85 0 85 4V18Q85 21 82 24L8 87Q6 89 6 85V49Q6 46 8 44Z" fill="#22C55E"/></g></svg>

package/assets/brand/lockup.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="355" height="120" viewBox="0 0 355 120" role="img" aria-label="Kith logo"><title>Kith logo</title><g transform="translate(8 10) scale(1)"><path d="M25 57L49 33L89 73Q92 76 92 80V96Q92 100 88 100H69Q65 100 62 97Z" fill="#09624F"/><path d="M8 44L58 1Q59 0 63 0H81Q85 0 85 4V18Q85 21 82 24L8 87Q6 89 6 85V49Q6 46 8 44Z" fill="#22C55E"/></g><path d="M6.689453125,-0.0 L6.689453125,-71.58203125 L20.41015625,-71.58203125 L20.41015625,-33.59375 L36.474609375,-51.85546875 L53.369140625,-51.85546875 L35.64453125,-32.91015625 L54.638671875,-0.0 L39.84375,-0.0 L26.806640625,-23.291015625 L20.41015625,-16.6015625 L20.41015625,-0.0 Z M58.79296875,-58.88671875 L58.79296875,-71.58203125 L72.513671875,-71.58203125 L72.513671875,-58.88671875 Z M58.79296875,-0.0 L58.79296875,-51.85546875 L72.513671875,-51.85546875 L72.513671875,-0.0 Z M106.35546875,-51.85546875 L106.35546875,-40.91796875 L96.98046875,-40.91796875 L96.98046875,-20.01953125 Q96.98046875,-13.671875 97.2490234375,-12.6220703125 Q97.517578125,-11.572265625 98.4697265625,-10.888671875 Q99.421875,-10.205078125 100.7890625,-10.205078125 Q102.693359375,-10.205078125 106.306640625,-11.5234375 L107.478515625,-0.87890625 Q102.693359375,1.171875 96.638671875,1.171875 Q92.927734375,1.171875 89.94921875,-0.0732421875 Q86.970703125,-1.318359375 85.5791015625,-3.2958984375 Q84.1875,-5.2734375 83.650390625,-8.642578125 Q83.2109375,-11.03515625 83.2109375,-18.310546875 L83.2109375,-40.91796875 L76.912109375,-40.91796875 L76.912109375,-51.85546875 L83.2109375,-51.85546875 L83.2109375,-62.158203125 L96.98046875,-70.166015625 L96.98046875,-51.85546875 Z M125.548828125,-71.58203125 L125.548828125,-45.263671875 Q132.189453125,-53.02734375 141.41796875,-53.02734375 Q146.154296875,-53.02734375 149.962890625,-51.26953125 Q153.771484375,-49.51171875 155.7001953125,-46.77734375 Q157.62890625,-44.04296875 158.3369140625,-40.72265625 Q159.044921875,-37.40234375 159.044921875,-30.419921875 L159.044921875,-0.0 L145.32421875,-0.0 L145.32421875,-27.392578125 Q145.32421875,-35.546875 144.54296875,-37.744140625 Q143.76171875,-39.94140625 141.7841796875,-41.2353515625 Q139.806640625,-42.529296875 136.828125,-42.529296875 Q133.41015625,-42.529296875 130.724609375,-40.869140625 Q128.0390625,-39.208984375 126.7939453125,-35.8642578125 Q125.548828125,-32.51953125 125.548828125,-25.9765625 L125.548828125,-0.0 L111.828125,-0.0 L111.828125,-71.58203125 Z" transform="translate(125 102) scale(1.3)" fill="#0B0F0E"/></svg>

package/assets/brand/mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100" role="img" aria-label="Kith folded k"><title>Kith folded k</title><g transform="translate(0 0) scale(1)"><path d="M25 57L49 33L89 73Q92 76 92 80V96Q92 100 88 100H69Q65 100 62 97Z" fill="#09624F"/><path d="M8 44L58 1Q59 0 63 0H81Q85 0 85 4V18Q85 21 82 24L8 87Q6 89 6 85V49Q6 46 8 44Z" fill="#22C55E"/></g></svg>

package/assets/brand/readme-header.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="400" viewBox="0 0 1280 400" role="img" aria-label="Kith — Parallel agents. Shared direction."><title>Kith — Parallel agents. Shared direction.</title><rect width="1280" height="400" fill="#0B0F0E"/><g transform="translate(431 58) scale(1.2)"><path d="M25 57L49 33L89 73Q92 76 92 80V96Q92 100 88 100H69Q65 100 62 97Z" fill="#09624F"/><path d="M8 44L58 1Q59 0 63 0H81Q85 0 85 4V18Q85 21 82 24L8 87Q6 89 6 85V49Q6 46 8 44Z" fill="#22C55E"/></g><path d="M6.689453125,-0.0 L6.689453125,-71.58203125 L20.41015625,-71.58203125 L20.41015625,-33.59375 L36.474609375,-51.85546875 L53.369140625,-51.85546875 L35.64453125,-32.91015625 L54.638671875,-0.0 L39.84375,-0.0 L26.806640625,-23.291015625 L20.41015625,-16.6015625 L20.41015625,-0.0 Z M58.79296875,-58.88671875 L58.79296875,-71.58203125 L72.513671875,-71.58203125 L72.513671875,-58.88671875 Z M58.79296875,-0.0 L58.79296875,-51.85546875 L72.513671875,-51.85546875 L72.513671875,-0.0 Z M106.35546875,-51.85546875 L106.35546875,-40.91796875 L96.98046875,-40.91796875 L96.98046875,-20.01953125 Q96.98046875,-13.671875 97.2490234375,-12.6220703125 Q97.517578125,-11.572265625 98.4697265625,-10.888671875 Q99.421875,-10.205078125 100.7890625,-10.205078125 Q102.693359375,-10.205078125 106.306640625,-11.5234375 L107.478515625,-0.87890625 Q102.693359375,1.171875 96.638671875,1.171875 Q92.927734375,1.171875 89.94921875,-0.0732421875 Q86.970703125,-1.318359375 85.5791015625,-3.2958984375 Q84.1875,-5.2734375 83.650390625,-8.642578125 Q83.2109375,-11.03515625 83.2109375,-18.310546875 L83.2109375,-40.91796875 L76.912109375,-40.91796875 L76.912109375,-51.85546875 L83.2109375,-51.85546875 L83.2109375,-62.158203125 L96.98046875,-70.166015625 L96.98046875,-51.85546875 Z M125.548828125,-71.58203125 L125.548828125,-45.263671875 Q132.189453125,-53.02734375 141.41796875,-53.02734375 Q146.154296875,-53.02734375 149.962890625,-51.26953125 Q153.771484375,-49.51171875 155.7001953125,-46.77734375 Q157.62890625,-44.04296875 158.3369140625,-40.72265625 Q159.044921875,-37.40234375 159.044921875,-30.419921875 L159.044921875,-0.0 L145.32421875,-0.0 L145.32421875,-27.392578125 Q145.32421875,-35.546875 144.54296875,-37.744140625 Q143.76171875,-39.94140625 141.7841796875,-41.2353515625 Q139.806640625,-42.529296875 136.828125,-42.529296875 Q133.41015625,-42.529296875 130.724609375,-40.869140625 Q128.0390625,-39.208984375 126.7939453125,-35.8642578125 Q125.548828125,-32.51953125 125.548828125,-25.9765625 L125.548828125,-0.0 L111.828125,-0.0 L111.828125,-71.58203125 Z" transform="translate(571.4 168.39999999999998) scale(1.56)" fill="#F8FAFC"/><text x="640" y="246" text-anchor="middle" fill="#F8FAFC" font-family="Arial,Helvetica,sans-serif" font-size="38" font-weight="500" letter-spacing="-.9">Parallel agents. Shared direction.</text><text x="640" y="293" text-anchor="middle" fill="#A8B4B0" font-family="Arial,Helvetica,sans-serif" font-size="22">Local coordination for coding agents.</text><path d="M564 343H716" stroke="#174536" stroke-width="2"/><path d="M615 343H665" stroke="#22C55E" stroke-width="2"/></svg>

package/assets/brand/social-preview.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-label="Kith — Parallel agents. Shared direction."><title>Kith — Parallel agents. Shared direction.</title><rect width="1280" height="640" fill="#0B0F0E"/><g transform="translate(431 90) scale(1.2)"><path d="M25 57L49 33L89 73Q92 76 92 80V96Q92 100 88 100H69Q65 100 62 97Z" fill="#09624F"/><path d="M8 44L58 1Q59 0 63 0H81Q85 0 85 4V18Q85 21 82 24L8 87Q6 89 6 85V49Q6 46 8 44Z" fill="#22C55E"/></g><path d="M6.689453125,-0.0 L6.689453125,-71.58203125 L20.41015625,-71.58203125 L20.41015625,-33.59375 L36.474609375,-51.85546875 L53.369140625,-51.85546875 L35.64453125,-32.91015625 L54.638671875,-0.0 L39.84375,-0.0 L26.806640625,-23.291015625 L20.41015625,-16.6015625 L20.41015625,-0.0 Z M58.79296875,-58.88671875 L58.79296875,-71.58203125 L72.513671875,-71.58203125 L72.513671875,-58.88671875 Z M58.79296875,-0.0 L58.79296875,-51.85546875 L72.513671875,-51.85546875 L72.513671875,-0.0 Z M106.35546875,-51.85546875 L106.35546875,-40.91796875 L96.98046875,-40.91796875 L96.98046875,-20.01953125 Q96.98046875,-13.671875 97.2490234375,-12.6220703125 Q97.517578125,-11.572265625 98.4697265625,-10.888671875 Q99.421875,-10.205078125 100.7890625,-10.205078125 Q102.693359375,-10.205078125 106.306640625,-11.5234375 L107.478515625,-0.87890625 Q102.693359375,1.171875 96.638671875,1.171875 Q92.927734375,1.171875 89.94921875,-0.0732421875 Q86.970703125,-1.318359375 85.5791015625,-3.2958984375 Q84.1875,-5.2734375 83.650390625,-8.642578125 Q83.2109375,-11.03515625 83.2109375,-18.310546875 L83.2109375,-40.91796875 L76.912109375,-40.91796875 L76.912109375,-51.85546875 L83.2109375,-51.85546875 L83.2109375,-62.158203125 L96.98046875,-70.166015625 L96.98046875,-51.85546875 Z M125.548828125,-71.58203125 L125.548828125,-45.263671875 Q132.189453125,-53.02734375 141.41796875,-53.02734375 Q146.154296875,-53.02734375 149.962890625,-51.26953125 Q153.771484375,-49.51171875 155.7001953125,-46.77734375 Q157.62890625,-44.04296875 158.3369140625,-40.72265625 Q159.044921875,-37.40234375 159.044921875,-30.419921875 L159.044921875,-0.0 L145.32421875,-0.0 L145.32421875,-27.392578125 Q145.32421875,-35.546875 144.54296875,-37.744140625 Q143.76171875,-39.94140625 141.7841796875,-41.2353515625 Q139.806640625,-42.529296875 136.828125,-42.529296875 Q133.41015625,-42.529296875 130.724609375,-40.869140625 Q128.0390625,-39.208984375 126.7939453125,-35.8642578125 Q125.548828125,-32.51953125 125.548828125,-25.9765625 L125.548828125,-0.0 L111.828125,-0.0 L111.828125,-71.58203125 Z" transform="translate(571.4 200.39999999999998) scale(1.56)" fill="#F8FAFC"/><text x="640" y="320" text-anchor="middle" fill="#F8FAFC" font-family="Arial,Helvetica,sans-serif" font-size="38" font-weight="500" letter-spacing="-.9">Parallel agents. Shared direction.</text><text x="640" y="367" text-anchor="middle" fill="#A8B4B0" font-family="Arial,Helvetica,sans-serif" font-size="22">Local coordination for coding agents.</text><g fill="none" stroke-width="3" stroke-linecap="round"><path d="M350 445H410C490 445 480 500 600 500M350 555H410C490 555 480 500 600 500" stroke="#387267"/><path d="M350 500H930M916 486L930 500L916 514" stroke="#22C55E"/></g><g fill="#22C55E"><circle cx="350" cy="445" r="5"/><circle cx="350" cy="500" r="5"/><circle cx="350" cy="555" r="5"/></g></svg>

package/assets/brand/wordmark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="236" height="110" viewBox="0 0 236 110" role="img" aria-label="kith"><title>kith</title><path d="M6.689453125,-0.0 L6.689453125,-71.58203125 L20.41015625,-71.58203125 L20.41015625,-33.59375 L36.474609375,-51.85546875 L53.369140625,-51.85546875 L35.64453125,-32.91015625 L54.638671875,-0.0 L39.84375,-0.0 L26.806640625,-23.291015625 L20.41015625,-16.6015625 L20.41015625,-0.0 Z M58.79296875,-58.88671875 L58.79296875,-71.58203125 L72.513671875,-71.58203125 L72.513671875,-58.88671875 Z M58.79296875,-0.0 L58.79296875,-51.85546875 L72.513671875,-51.85546875 L72.513671875,-0.0 Z M106.35546875,-51.85546875 L106.35546875,-40.91796875 L96.98046875,-40.91796875 L96.98046875,-20.01953125 Q96.98046875,-13.671875 97.2490234375,-12.6220703125 Q97.517578125,-11.572265625 98.4697265625,-10.888671875 Q99.421875,-10.205078125 100.7890625,-10.205078125 Q102.693359375,-10.205078125 106.306640625,-11.5234375 L107.478515625,-0.87890625 Q102.693359375,1.171875 96.638671875,1.171875 Q92.927734375,1.171875 89.94921875,-0.0732421875 Q86.970703125,-1.318359375 85.5791015625,-3.2958984375 Q84.1875,-5.2734375 83.650390625,-8.642578125 Q83.2109375,-11.03515625 83.2109375,-18.310546875 L83.2109375,-40.91796875 L76.912109375,-40.91796875 L76.912109375,-51.85546875 L83.2109375,-51.85546875 L83.2109375,-62.158203125 L96.98046875,-70.166015625 L96.98046875,-51.85546875 Z M125.548828125,-71.58203125 L125.548828125,-45.263671875 Q132.189453125,-53.02734375 141.41796875,-53.02734375 Q146.154296875,-53.02734375 149.962890625,-51.26953125 Q153.771484375,-49.51171875 155.7001953125,-46.77734375 Q157.62890625,-44.04296875 158.3369140625,-40.72265625 Q159.044921875,-37.40234375 159.044921875,-30.419921875 L159.044921875,-0.0 L145.32421875,-0.0 L145.32421875,-27.392578125 Q145.32421875,-35.546875 144.54296875,-37.744140625 Q143.76171875,-39.94140625 141.7841796875,-41.2353515625 Q139.806640625,-42.529296875 136.828125,-42.529296875 Q133.41015625,-42.529296875 130.724609375,-40.869140625 Q128.0390625,-39.208984375 126.7939453125,-35.8642578125 Q125.548828125,-32.51953125 125.548828125,-25.9765625 L125.548828125,-0.0 L111.828125,-0.0 L111.828125,-71.58203125 Z" transform="translate(9 90) scale(1.3)" fill="#0B0F0E"/></svg>

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node