kith-coord 0.0.0-stage → 0.1.1

package/docs/architecture.md

@@ -0,0 +1,37 @@
+# Architecture
+
+Kith runs locally. There is no coordination server: CLI and MCP clients share `.coord/state.db` through SQLite WAL.
+
+## Core components
+
+| Module | Responsibility |
+| --- | --- |
+| `db.ts` | Schema initialization, synchronous writer transactions, event log, monotonic token counter |
+| `fencing.ts` | Capability-owned session generations, heartbeats, real PID/start-time checks, reclamation |
+| `repository.ts` | Canonical checkout/common-Git-directory discovery and physical path containment |
+| `locks.ts`, `glob.ts` | Scoped lock acquisition, exact supported glob intersection, write checks |
+| `intents.ts` | Work declarations, task dependencies, transactional claims |
+| `ast-analyzer.ts`, `dep-graph.ts` | Advisory source-derived contracts and import relationships |
+| `shadow-git.ts` | Per-agent indexes, synthetic commits, dirty-tree merge probes |
+| `worktree-cow.ts` | Isolated worktree creation and dependency hydration |
+| `merge-train.ts` | Serialized integration through a disposable staging worktree |
+| `bash-guard.ts` | Best-effort snapshots and quarantine recovery |
+| `broker.ts` | Port reservations, FIFO mutex tickets, renewable command leases and process-group guards |
+
+`engine.ts` shares begin/complete orchestration across adapters. `src/cli` adapts commands and hook payloads. `src/mcp/server.ts` exposes tools. Library consumers use `src/index.ts` exports and close engines explicitly.
+
+## State boundaries
+
+Writer transactions use `BEGIN IMMEDIATE`, so task claims and lock conflict checks share a single SQLite writer boundary. No asynchronous work should occur inside a database transaction. Port probing occurs before the transaction and reservations are rechecked inside it.
+
+Git integration uses an exclusive local lock file and a unique staging directory per attempt. Kith checks the target's cleanliness, branch, and HEAD before advancing it. This does not serialize external Git processes. A crash intentionally leaves the lock for inspection rather than guessing that it is safe to reclaim.
+
+Git clients launched from subdirectories, symlink aliases and linked checkouts discover the same physical common Git directory. Ordinary repositories retain the primary checkout's `.coord` directory; repositories using a separate Git directory store shared state in `<common-git-dir>/kith`. Git operations still target the selected checkout and its current branch. A new session started inside a linked checkout records that checkout as its working path. Non-Git directories use the explicitly selected directory. Existing checkout-local databases are refused rather than silently abandoned. See [path and scope rules](path-and-scope-rules.md).
+
+Session capabilities are held in each engine's memory and hashed in the separate `agent_sessions` table. Agent records/status do not expose them. Mutation boundaries assert ownership inside writer transactions where applicable. `mutex_waiters` preserves handoff order independently of a resource row, and `mutex_runs` preserves execution exclusion even if session/resource rows expire. A private IPC handshake records a worker process group before it can execute a command. See [session and command lifecycle](sessions-and-mutexes.md).
+
+Worktree edit reports read source bytes from the registered worktree and store repository-relative contracts. Git checkpoint/merge subprocesses receive the owning capability in their environment so generated pre-commit guards can authorize them. Generated pre-commit guards inspect the invoking Git checkout/index even when `--repo` selects shared state through another checkout.
+
+## Adaptation
+
+Use a new adapter for a new agent client, retaining the same core lock/task APIs. Keep heuristic analysis advisory. Source matching cannot establish compatibility. Git conflicts require explicit resolution in the source worktree. Custom verification commands belong to the target project.

package/docs/client-validation.md

@@ -0,0 +1,62 @@
+# Native client validation
+
+Protocol tests and the two-client demo exercise the MCP SDK. Native validation additionally launches an installed agent client, lets its model use real MCP tools and its native editor, and checks the resulting repository state. It is opt-in because it needs a logged-in client or provider credentials and consumes model usage.
+
+```sh
+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 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 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. 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`.
+
+## Hosted checks
+
+The `CI` workflow runs independently on Linux/macOS with Node 22.13.0, current 22 and 24. Each job checks types, process/lifecycle and MCP tests, an installed package consumer, and the two-client worktree demo. JUnit reports are retained even when a test fails. It also supports manual dispatch. Hosted CI does not run paid models or require agent credentials. Run native clients separately after adapter changes and record their exact versions and outcomes here or in the pull request.
+
+## Recorded native runs
+
+On 2026-10-19, macOS / Node 22.23.3: [Codex CLI 0.163.0-alpha.10.2](validation/2026-10-19-codex-client-report.json) passed MCP-owned and inherited-owner scenarios; [Claude Code 2.1.301](validation/2026-10-19-claude-client-report.json) passed both worktree flows. An additional [native Claude edit denial](validation/2026-10-19-claude-hook-report.json) confirmed that a peer-owned file edit was blocked before a valid task completed. These are recorded outcomes on these versions, with the configuration delivery limits described above.
+
+The separate [missing guard check](validation/2026-10-19-claude-hook-unavailable-report.json) also passed: a native Write attempted once was denied and the marker file remained absent. This case is included in the reusable runner.
+
+The native shell check found a concrete macOS Codex failure: direct CLI supervision could not inspect its mutex waiter under the command sandbox. The new MCP command adapter preserves process-identity checks. [Codex](validation/2026-10-19-codex-mutex-report.json) and [Claude](validation/2026-10-19-claude-mutex-report.json) subsequently passed the full inherited-session workflow with a 1.2-second command on a 300 ms renewable lease.
+
+Wire-level regression coverage also caught an SDK transport lifecycle gap: stdin EOF did not invoke the server close callback while a command kept the event loop alive. Kith now translates EOF/signals into graceful closure, aborts active commands, waits for their guarded groups to stop, and closes state afterward. A borrowed owner remains active and its mutex becomes available after cleanup.
+
+
+After the repository/path/scope/merge hardening pass, the isolated workflows passed again on macOS / Node 22.23.3: [Codex](validation/2026-10-19-path-hardening-codex.json) and [Claude](validation/2026-10-19-path-hardening-claude.json). These reruns confirm native editing, conflict handling, contract reports, renewable command supervision, verified integration and release; the existing shared-owner and unavailable-hook reports cover those separate scenarios. Regression tests additionally launch real MCP clients from a Git subdirectory and an existing linked checkout, edit literal `[id]` route paths, and prove the invoking checkout's staged index is guarded.
+
+
+The recovery pass reran the isolated workflows on macOS / Node 22.23.3: [Codex](validation/2026-10-19-recovery-codex.json) and [Claude](validation/2026-10-19-recovery-claude.json) both passed an intentional verification failure followed by successful completion on the same session and worktree. Separate automated MCP regressions cover staging-only repairs being refused and a killed owner being recovered from a stopped database/WAL backup with a fresh capability and preserved worktree. These checks do not establish arbitrary corruption recovery or GUI behavior.
+
+
+The 2026-10-20 subtraction pass reran the isolated native workflows on macOS / Node 22.23.3: [Codex CLI 0.163.0-alpha.10.2](validation/2026-10-20-subtraction-codex.json) and [Claude Code 2.1.301](validation/2026-10-20-subtraction-claude.json) both passed edit reporting, renewable commands, failed verification followed by successful retry, integration and ownership release. Claude also verified native peer-edit denial with its inherited owner preserved. These runs use the shared begin/complete implementation after removing fuzzy advice, custom conflict rewriting and the dashboard.
+
+
+## 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 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

@@ -0,0 +1,80 @@
+# Client integrations
+
+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 |
+| --- | --- |
+| `claude` | Merges Kith into `.mcp.json`; adds Claude edit hooks only when selected explicitly with `--only` and without `--mcp-only` |
+| `codex` | Appends a Kith MCP table to `.codex/config.toml`, forwarding session environment names; preserves existing TOML and custom Kith servers |
+| `cursor` | Merges `.cursor/mcp.json`; adds `.cursor/hooks.json` guards only when selected explicitly without `--mcp-only` |
+| `agents` | Updates only the marked Kith block in AGENTS.md and creates a generic `.agent/skills/kith/SKILL.md` |
+| `git` | Installs a pre-commit hook only when one does not exist; uses an in-repository Git hooks path and skips external hooks directories |
+| `shims` | Creates optional `.coord/bin/npm`, `pnpm`, and `yarn` wrappers |
+
+## Start with MCP
+
+```sh
+kith init --dry-run
+kith init
+```
+
+Default setup configures Claude, Codex, Cursor and agent instructions through MCP. To select clients use `--mcp-only --only claude,codex,agents`. Review and commit setup files, then restart the client. Begin with `kith_begin_work` and `isolateWorktree: true`; edit the returned worktree, report files through `kith_record_file_edit`, run commands with `kith_run_with_mutex`, and complete with a project verification command. The MCP connection retains its capability without shell exports. Keep that connection alive and heartbeat before expiry. See [runnable workflows](usage.md).
+
+Default setup and `--mcp-only` select client configurations and agent instructions; it does not install Claude/Cursor edit hooks, Git hooks or shims. It never removes existing hooks. If tool hooks already exist, init warns to review their session requirements. This option cannot be combined with `--only git` or `shims`. Existing integrations may need manual migration if created by the initial prototype.
+
+## Optional hooks and CLI sharing
+
+Select clients explicitly without `--mcp-only` to add edit hooks, for example `kith init --only claude,cursor,agents`. Add `git` for the optional staged-file guard. Preview with `--dry-run` first.
+
+Before launching a hook client, run `eval "$(kith session start --agent <id> --owner-pid "$$" --shell)"`. The client, its MCP process, and hooks must inherit both `KITH_AGENT_ID` and `KITH_SESSION_TOKEN`. Use that same agent ID in MCP calls. A missing/forged/expired token blocks hook mutations. See [session setup](sessions-and-mutexes.md). Separate stateless shell calls cannot retain this setup. Prefer MCP and isolated worktrees when a persistent launcher environment is unavailable; AGENTS.md guidance alone cannot enforce writes.
+
+Shims are inactive until `.coord/bin` is prepended to PATH. Use an absolute path, for example `export PATH="$PWD/.coord/bin:$PATH"` at the repository root. Wrappers remove that directory from PATH before invoking the real package manager, avoiding recursive self-invocation. They serialize selected install/add/remove commands through the resource broker; leases renew while commands run, and FIFO tickets persist across releases. Protected work must remain in the supervised command group.
+
+Automated end-to-end tests launch real MCP SDK clients over stdio and execute generated hook commands, including worktree edits, Git hooks, verification, completion, and disconnect handling. The runnable `pnpm demo` covers two independent clients integrating separate worktrees. These validate the protocol and adapter boundary; native client versions must also pass the opt-in [client validation runner](client-validation.md). GUI behavior and other releases still need separate checks. Follow [Claude's hook reference](https://code.claude.com/docs/en/hooks) and [MCP guide](https://code.claude.com/docs/en/mcp) when adapting the generated configuration.
+
+Codex reads project settings only for trusted projects. Review `.codex/config.toml` and trust the repository through Codex before connecting. Approve Kith tools in your client as needed; unattended Codex rejects tools requiring approval even when its process exits zero. Generated settings preserve the client approval policy. Existing custom Kith TOML tables are preserved with a warning when capability forwarding needs review.
+
+Generated Claude pre-hooks use `onFailure: "block"` so a missing executable, timeout or abnormal hook exit cannot silently permit an edit on clients supporting this field. Run init again to upgrade prior generated hooks. Validate your installed client version before relying on hook failure handling.
+
+
+## Enforcement modes
+
+```sh
+kith init --only claude,cursor,git,agents --enforcement block --dry-run
+kith init --only claude,cursor,git,agents --enforcement block
+```
+
+`block` is the default for optional hooks: conflicting native file writes are denied; unclaimed files are claimed before writes. Risky recognized Git commands are refused while they could replace a peer's shared checkout or shared refs. `warn` permits policy conflicts and returns warnings; it never steals the peer's claim or attributes their file to the warning agent. `off` skips claim/risky-command enforcement. All modes still require valid session ownership and contained file paths. This switch affects hooks, not MCP/CLI ownership, locks or integration checks. Rerun init with a different mode to update recognized Kith hooks without duplicating them or deleting unrelated hooks.
+
+Cursor's native `preToolUse`/`postToolUse` adapter handles `Shell`, `Write` and `Delete` matcher payloads, returns Cursor permission/context JSON, and sets `failClosed:true` on pre-hooks. The generated Claude pre-hook uses `onFailure:"block"`. These fields depend on client versions; see [Cursor's hook reference](https://cursor.com/docs/hooks), [Claude's hook reference](https://code.claude.com/docs/en/hooks), and the [validation matrix](client-validation.md). A pattern-based shell guard cannot parse every shell program or prevent bypasses. Worktrees remain the recommended default.
+
+## 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. 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.
+
+```sh
+kith uninstall --dry-run
+kith uninstall
+```
+
+Uninstall restores the exact original bytes/permissions or deletes files created by tracked setup **only while their contents and permissions still match Kith's recorded write**. Edited files are preserved and listed in `needsReview` (nonzero exit); review/remove their Kith entries manually. State, worktrees, recovery copies and the `.coord/` ignore rule are retained. Empty directories can remain. Files installed by versions predating setup tracking are not guessed at or removed: a later init can record only the state it actually observed. Damaged or redirected backup metadata is refused before configuration restoration. This is reversible configuration cleanup, not a project/worktree deletion command.
+
+
+## Registry installation
+
+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.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

@@ -0,0 +1,45 @@
+# Repository, path and scope rules
+
+## Discovery
+
+CLI, MCP and library entry points discover the canonical Git checkout root from the supplied directory. Subdirectories and symlink aliases select that checkout. Linked checkouts share coordination through Git's physical common directory while retaining their own checkout for Git operations. Ordinary repositories keep existing state in the primary checkout's `.coord/state.db`; separate Git directories use `<common-git-dir>/kith/state.db`. Submodules and nested independent repositories have their own common directories and state.
+
+A session created inside a linked checkout records that checkout as its working path. Resuming a capability retains its recorded working path. Hook paths and file reports use the recorded worktree when present. Git pre-commit checks inspect the invoking checkout's staged index, even if the generated command passes another checkout through `--repo`. Integration targets the branch checked out in the explicitly selected checkout; use `--repo /path/to/integration-target` when completing work into another checkout.
+
+Relative API file paths and scopes are checkout-root-relative, including when the client starts in a subdirectory. Hook clients should send absolute file paths. A non-Git directory has no shared Git identity; pass its intended root explicitly. Bare repositories and broken `.git` markers fail discovery. Setup discovers the root before preparing configuration and retains dry-run behavior.
+
+Stop old Kith clients before upgrading. If the selected directory, an ancestor up to its checkout root, or a linked/separate-Git-directory checkout contains an old independent `.coord/state.db`, discovery refuses it rather than bypassing that state. Preserve its database, worktrees, snapshots and quarantine files before consolidating state manually. Kith does not merge independent databases or delete legacy work automatically.
+
+## Supported scope grammar
+
+The glob language compares case-sensitive strings separated by `/`. On a checkout whose filesystem treats case variants as aliases, lock conflict checks additionally compare normalized case variants, including missing files; they can retain extra conflicts. Symbol identifiers retain their case. Filesystem case behavior is probed read-only and cached for the lifetime of an engine:
+
+| Form | Meaning |
+| --- | --- |
+| `src/auth.ts` | A concrete path |
+| `src/*.ts` | `*` matches zero or more filename characters, without crossing `/` |
+| `src/file?.ts` | `?` matches one Unicode code point, without crossing `/` |
+| `src/**/*.ts` | A whole-segment `**` matches zero or more complete directories |
+| `**` | All nonempty repository file paths |
+| `file:src/routes/[id]/page.tsx` | An explicit literal path; reserved glob characters have no special meaning |
+| `symbol:src/auth.ts#verifyToken` | A named symbol in a concrete file; a whole-file scope overlaps every symbol in that file |
+
+Wildcards include dotfiles. `src/**/*.ts` includes `src/a.ts` and `src/nested/a.ts`. `src/**/left.ts` and `src/**/right.ts` do not overlap. Brace expansion, character classes, extglobs, negation and backslash escaping are unsupported in glob scopes and produce errors. Use separate scopes for alternatives, or `file:` for literal names containing brackets, braces, parentheses, `!`, `*` or `?`. Hook-generated file locks use literal paths automatically. `file:` and `symbol:` are reserved scope prefixes.
+
+Scope strings are limited to 512 characters and 64 segments. Empty paths, control characters, backslashes and `.`/`..` segments after the wildcard prefix are refused. Quote scopes in shells. CLI scopes are comma-separated; literal commas in a scope require the library/MCP array API.
+
+Intersection uses finite-state language intersection rather than sample filenames. Already-persisted unsupported scopes retain exclusion until their owner releases them or their session expires. This can block unrelated work; it never silently declares a malformed scope disjoint.
+
+## Symlinks
+
+Existing literal path prefixes are physically resolved before containment checks, including `..` following a symlink. Internal aliases map to the same scope; outward, dangling and looping links are refused. Missing leaves resolve through their existing ancestors. Coordination directories/database and configuration writes refuse redirected paths. Indexing skips symlink sources and nested repositories.
+
+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. 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
+
+Before staging source changes, integration verifies the agent's registered worktree, common repository and requested branch. Worktree removal refuses normalized-ID collisions and a path registered to another active agent. Executable mode is preserved in shadow reports. Git path lists are NUL-delimited, so conflict paths containing tabs/newlines are not split or interpreted as quoted names.
+
+Git handles clean merges. Any unresolved Git conflict fails integration, including apparently additive source or JSON changes. Kith does not parse or rewrite conflicting contents. The target stays unchanged and the source worktree/checkpoint remains available for explicit repair and retry. Merge the current target into that source branch, resolve and commit the conflict there, then retry completion with a project-specific verification command. Checks must leave the candidate unchanged. A clean Git merge alone does not establish compatibility.