docks-kit 0.8.2 → 0.10.0

package/AGENTS.md

@@ -4,24 +4,29 @@ Canonical instructions for coding agents working on this project. Compatible wit
 
 ## Repository purpose
 
-Portable configuration kit for AI coding agents. Per-tool Single Source of Truth (SoT) directories get deployed to each tool's user-config location via `./docks-kit sync` — clone once, sync to your home directory, get a consistent AI-assisted dev environment everywhere. The kit focuses on **token efficiency without sacrificing quality**: every setting and hook is tuned to minimize token consumption while preserving rigorous output. When adding or editing anything, ask: *does this change reduce tokens without weakening correctness?*
+Portable configuration kit for AI coding agents. Per-tool Single Source of Truth (SoT) directories get deployed to each tool's user-config location via `./docks-kit sync` — clone once and get a consistent AI-assisted dev environment across supported Linux and macOS hosts. The kit focuses on **token efficiency without sacrificing quality**: every setting and hook is tuned to minimize token consumption while preserving rigorous output. When adding or editing anything, ask: *does this change reduce tokens without weakening correctness?*
 
 Tool-specific instructions live alongside this file:
 - **`CLAUDE.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, RTK, status line, session management, permission mode, open concerns.
 - Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
 
+
+docks-kit runtime, standalone binary, and Session Relay prebuilt support is
+exactly Linux x64/arm64 and macOS x64/arm64. Unsupported hosts fail before the
+launcher can fall back to Bun source.
+
 ## Repository layout (cross-cutting)
 
 | Path | Purpose |
 |------|---------|
-| `docks-kit` | CLI launcher: runs the platform binary in `cli/dist/` only when its `--version` matches `package.json`, otherwise Bun-from-source (auto-installs Bun + `node_modules`). No-Bun recovery is the standalone platform release binary |
+| `docks-kit` | CLI launcher: on supported hosts, runs the platform binary in `cli/dist/` only when its `--version` matches `package.json`, otherwise Bun-from-source (auto-installs Bun + `node_modules`). Unsupported hosts fail before source fallback. No-Bun recovery is the standalone platform release binary |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, `workflow`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
 | `cli/` | Effect-TS CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified model catalog plus the strict Docks workflow-role registry |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
 | `install.sh` | Global installer |
-| `.github/workflows/release-cli.yml` | `cli-v*` release binaries + npm publish |
+| `.github/workflows/release-cli.yml` | `cli-v*` release: four Linux/macOS x64/arm64 binaries, `SHA256SUMS`, and npm publish |
 | `README.md` | Front door |
 | `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
 | `SoT/.agents/skills.txt` | Universal-skill manifest, intentionally empty by default. Adding an [agentskills.io](https://agentskills.io/specification) slug opts it into EngineNative's shared `~/.agents/skills/` bootstrap and Claude symlink. |
@@ -36,6 +41,7 @@ Codex SoT notes:
 - `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved.
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
 - `docks-kit status` verifies Session Relay only through the supported `codex plugin list --json` inventory. `ready` means installed and enabled for a newly started Codex session; it is not evidence about an old process, lifecycle state, receive-path health, or worker quiescence. The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
+- Claude and Codex sync call `sessionRelayCli.ts ensureSessionRelayCli` immediately before their plugin passes. It installs the exact source-pinned precompiled command at `~/.local/bin/session-relay` for Linux/macOS x64/arm64 only, requires committed digest = same-release `SHA256SUMS` row = downloaded bytes, smoke-tests the staged version, and atomically replaces the stable path. `agents`-only sync never enters this boundary. The four pinned production digests correspond to the stable `session-relay--v0.12.0` assets and its `SHA256SUMS`.
 - Both global prompt SoTs carry one byte-identical compact `Docks-workflow-models:` record. Root `--model-orchestrator` / `--model-reviewer` / `--model-implementer` / review-bound flags update only that deployed record; `docks-kit models workflow` lists the closed selectors, and a flag-less sync restores defaults.
 - Codex workflow selectors use the closed `<tool>:<model>@<effort>[+fast]` routing grammar. Fast is intentionally absent from the global SoT: no suffix means Standard and keeps the backward-compatible schema-1 record; `+fast` emits a schema-2 candidate with `service_tier: "fast"`. Docks and Session Relay consumers must explicitly launch unsuffixed Codex roles with the default service tier so a user's global Fast preference cannot leak into workflows.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
@@ -52,7 +58,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 - **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-rtk`, `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.
-- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns the verified-version gate over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own tool-specific sync logic. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
+- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns the verified-version gate over `SoT/toolchain.json`; `sessionRelayCli.ts` owns the closed release manifest, platform mapping, checksum/smoke transaction, and atomic Session Relay replacement; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own tool-specific sync logic. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
 - **Small, reviewable changes.** Bundled multi-concern PRs are harder to review and revert. Split an engine/CLI change and a per-tool config change unless the change requires atomicity.
 - **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in the per-tool file) before invoking `--reconcile` or `--prune`. User-added permissions / env vars / plugins absent from SoT will be discarded.
 - **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md` and `SoT/.codex/AGENTS.md` are loaded into every agent session's prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `CLAUDE.md` / `AGENTS.md` at the repo root (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: would removing it cause the agent to make mistakes? If not, cut it — over-instruction degrades adherence on current frontier models.
@@ -91,7 +97,7 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 Multi-commit work plans live in `docs/plans/active/` (status is a frontmatter field) and `docs/plans/finished/` (archive). Every plan file is a complete cold-handoff document — goal, context & rationale, environment & how-to-run, steps with exact paths, executable acceptance criteria, and a binary cold-handoff checklist — so any agent (or a weaker model) can pick one up cold without guessing. Skills handle every operation: `plan-init` (bootstrap/migrate), `plan-manager` (list/show/start/block/ship/new, auto-commit on transition, self-review on draft), `plan-review` (verification). Trigger by natural language or the matching `plan-*` skill. `active/` is multi-occupancy.
 </constraint>
 
-The full convention (frontmatter schema, body sections, one-pass local self-review, bounded strong-default X/S review receipts, workflow roles, open-questions, age tokens) lives in `docs/plans/AGENTS.md`. `docs/plans/CLAUDE.md` is a one-line `@AGENTS.md` import for Claude Code's nested discovery. If `.codex/agents/plan-manager.toml` and `.codex/agents/plan-review.toml` exist, Codex may use them for explicit subagent delegation; otherwise run the matching `plan-*` skill inline.
+The full convention (frontmatter schema, body sections, one-pass local checklist self-review, schema-5 role `primary`, GPT-5.6-sol/high/`service_tier:"default"` (Standard) → Fable/high → Opus/xhigh availability-only fallback, exact eight-criterion evidence checklist, primary-role waivers, one full round plus at most one accepted-blocker repair, open questions, and age tokens) lives in `docs/plans/AGENTS.md`. `docs/plans/CLAUDE.md` is a one-line `@AGENTS.md` import for Claude Code's nested discovery. If `.codex/agents/plan-manager.toml` and `.codex/agents/plan-review.toml` exist, Codex may use them for explicit subagent delegation; otherwise run the matching `plan-*` skill inline.
 
 Distinct from per-tool **Open Concerns** sections (wait-on-upstream
 blockers tied to a vendor shipping a fix — these live inside the per-tool

package/README.md

@@ -2,8 +2,8 @@
 
 Portable configuration kit for AI coding agents. Per-tool **Single Source of
 Truth (SoT)** directories are deployed to each tool's user-config location —
-clone once, sync everywhere, get a consistent AI-assisted dev environment on
-every machine. Tuned for **token efficiency without sacrificing quality**.
+clone once and get a consistent AI-assisted dev environment across supported
+Linux and macOS machines. Tuned for **token efficiency without sacrificing quality**.
 
 Supported tools: **Claude Code**, **Codex**, and any agent consuming
 [agentskills.io](https://agentskills.io) universal skills.
@@ -17,10 +17,12 @@ cd ~/projects/public
 ./docks-kit status          # doctor view: drift, toolchain, plugins, skills
 ```
 
-The `./docks-kit` launcher prefers a compiled binary (`cli/dist/`) only when
-its version matches the checkout, then runs from source via Bun — auto-installing
-Bun and dependencies when missing. Stale ignored build artifacts cannot mask
-newer checkout code.
+The `./docks-kit` launcher supports Linux x64/arm64 and macOS x64/arm64.
+On those hosts it prefers a compiled binary (`cli/dist/`) only when its version
+matches the checkout, then runs from source via Bun—auto-installing Bun and
+dependencies when missing. Unsupported hosts fail immediately and never fall
+back to Bun source. Stale ignored build artifacts cannot mask newer checkout
+code.
 
 Other install paths (global `bun add -g docks-kit`, curl installer) —
 see `./docks-kit docs install`.
@@ -32,7 +34,7 @@ The executable carries the generated sync payload; no checkout or adjacent
 `SoT/` directory is required.
 
 Prerequisites for source/global installs: Bun; Node/npm for npm-global tools.
-`jq` is optional doctor/test tooling. `curl` is used only at requested POSIX
+`jq` is optional doctor/test tooling. `curl` is used only at requested Linux/macOS
 RTK/Bun download boundaries, not as a global sync prerequisite.
 
 ## CLI
@@ -102,6 +104,13 @@ current valid values, while a later flag-less sync restores all defaults.
   versions above the kit-verified pin prompt before installing
   (`--yes` accepts; non-TTY falls back to the pinned verified version
   when possible). `docks-kit toolchain check` shows the full table.
+- **Session Relay CLI** — Claude/Codex syncs ensure the source-pinned
+  precompiled `session-relay` command in `~/.local/bin` immediately before
+  Session Relay plugin reconciliation. Linux/macOS x64/arm64 assets must match
+  both the committed digest and their release `SHA256SUMS`, then pass an exact
+  staged version smoke before atomic replacement; failures preserve any prior
+  command. The four production digests are pinned for the stable
+  `session-relay--v0.12.0` assets and match the same-release `SHA256SUMS`.
 - **Model catalog** — `SoT/models.json` is the research-verified source for
   model validation, listings, pickers, and the Docks workflow-role registry.
 - **Claude runtime** — sync materializes three dependency-free Bun `.mjs`
@@ -129,19 +138,21 @@ current valid values, while a later flag-less sync restores all defaults.
 
 ## Platform support
 
-| Platform | CLI | Sync engine |
-|----------|-----|-------------|
-| Linux | ✅ native | ✅ native |
-| macOS (x64/arm64) | ✅ native | ✅ native |
-| Windows | ✅ native binary (`.exe` and `bun add -g` CI-verified) | ✅ EngineNative (TS, default engine — no Git Bash); real-machine verified 2026-07-09 — RTK hooks are native too (rtk ≥0.37.2) |
+| Platform | Architecture | docks-kit binary | Session Relay prebuilt | Sync engine |
+|----------|--------------|------------------|------------------------|-------------|
+| Linux | x64 | ✅ | ✅ | ✅ native |
+| Linux | arm64 | ✅ | ✅ | ✅ native |
+| macOS | x64 | ✅ | ✅ | ✅ native |
+| macOS | arm64 | ✅ | ✅ | ✅ native |
 
 Details: `docks-kit docs platforms`.
 
 ## Releases
 
-Tagging `cli-v*` builds five standalone binaries (+ SHA256SUMS) and attaches
-them to the GitHub release; npm publish runs when the `NPM_TOKEN` secret is
-configured. Package bundles the CLI + generated payload, so npm releases are
+Tagging `cli-v*` builds four standalone binaries (Linux x64/arm64 and macOS
+x64/arm64) plus `SHA256SUMS` and attaches them to the GitHub release; npm
+publish runs when the `NPM_TOKEN` secret is configured.
+Package bundles the CLI + generated payload, so npm releases are
 versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs

package/cli/docs/install.md

@@ -1,5 +1,8 @@
 # Installing docks-kit
 
+Supported hosts are Linux x64/arm64 and macOS x64/arm64. Unsupported hosts
+fail before the launcher can fall back to Bun source.
+
 ## 1. Repo checkout (development / current users)
 
 ```
@@ -8,10 +11,11 @@ cd ~/projects/public
 ./docks-kit sync
 ```
 
-The `./docks-kit` launcher prefers a compiled binary in `cli/dist/` only when
-its reported version matches `package.json`, then falls back to Bun-from-source
-(auto-installing Bun via download-then-run and `bun install --frozen-lockfile`
-when needed). An ignored stale build is reported and bypassed.
+On a supported host, the `./docks-kit` launcher prefers a compiled binary in
+`cli/dist/` only when its reported version matches `package.json`, then falls
+back to Bun-from-source (auto-installing Bun via download-then-run and
+`bun install --frozen-lockfile` when needed). An ignored stale build is reported
+and bypassed.
 
 ## 2. Global via Bun (effect-solutions-style)
 
@@ -51,7 +55,7 @@ install; `docks-kit --version`, model catalogs, toolchain checks, and real sync
 remain functional with the script blocked. CI pins the one-package/one-command
 identity above and will fail if the script-bearing set changes.
 
-## 3. curl installer (Unix-only)
+## 3. curl installer (Linux/macOS)
 
 ```
 curl -fsSL https://raw.githubusercontent.com/DocksDocks/public/main/install.sh -o /tmp/docks-kit-install.sh
@@ -61,20 +65,7 @@ bash /tmp/docks-kit-install.sh && rm /tmp/docks-kit-install.sh
 Download-then-run, never `curl | bash` — stream truncation has bitten this
 kit before. The installer bootstraps Bun when absent, runs
 `bun add -g docks-kit`, and links the binary into `~/.local/bin`.
-**Linux/macOS only** — on Windows use the compiled `.exe` or `bun add -g`
-(both CI-verified; see below).
-
-## Windows entrypoints
-
-Two supported paths (CI-verified on windows-2025, native PowerShell):
-
-- **Compiled binary** — `docks-kit-windows-x64.exe` release asset. No Bun,
-  no Git Bash: the exe embeds the runtime and generated payload, and
-  EngineNative runs in-process from any working directory.
-- **`bun add -g docks-kit`** — bun creates a working shim for the
-  `#!/usr/bin/env bun` bin; the package carries the same generated payload.
-
-`install.sh` is not a Windows path.
+This installer supports Linux and macOS only.
 
 ## Keeping the kit up to date
 
@@ -105,6 +96,6 @@ sync/config reads.
 - Bun for source/global installs; release binaries embed the runtime
 - Node/npm for npm-global tools (agent-browser, LSP servers)
 - jq is optional doctor/test tooling; sync has no jq runtime dependency
-- curl is required only when a requested POSIX RTK/Bun bootstrap must download
+- curl is required only when a requested Linux/macOS RTK/Bun bootstrap must download
   an installer; an already-present Bun does not require it
 - See `docks-kit toolchain check` for the full picture on this machine

package/cli/docs/platforms.md

@@ -1,46 +1,18 @@
 # Platform support
 
-| Platform | CLI (docks-kit) | Sync engine | Notes |
-|----------|-----------------|-------------|-------|
-| Linux | native | EngineNative (TS) | Primary target |
-| macOS | native (x64 + arm64) | EngineNative (TS) | Release binary or Bun source path |
-| Windows | native (`.exe` / `bun add -g`, CI-verified) | EngineNative (TS) — no Git Bash | Real-machine verified 2026-07-09 |
-
-EngineNative is the only supported engine on all platforms. `DOCKS_KIT_ENGINE=bash`
-now exits with the removed-engine message and points at the `bash-engine-final`
-tag for historical recovery.
-
-## Windows detail
-
-Supported entrypoints (both verified in CI on windows-2025 under native
-PowerShell — see `.github/workflows/windows-entrypoints.yml`):
-
-- **`docks-kit-windows-x64.exe`** (release asset) — the no-toolchain path.
-  No Bun, no Git Bash; the exe embeds the runtime and generated payload, and
-  EngineNative runs in-process from any working directory.
-- **`bun add -g docks-kit`** — bun creates a working Windows shim for the
-  `#!/usr/bin/env bun` bin; the package carries the same generated payload.
-- `install.sh` is **Unix-only** and not a Windows path.
-
-The managed tools all run natively on Windows: Claude Code (requires Git
-Bash for its own Bash tool — that requirement is Claude Code's, not this
-kit's), Codex CLI (native PowerShell + Windows sandbox), RTK (native
-binaries; since rtk 0.37.2 the PreToolUse hook is a native binary command —
-`rtk hook claude`, no shell or jq. Only the kit's *auto-installer* is
-Unix-only: install rtk natively, then sync).
-
-CI coverage (all on the pinned windows-2025 label): EngineNative PowerShell
-smoke with `HOME` unset — `%USERPROFILE%` path resolution, `.cmd` tool
-spawning (npm), toolchain gate branches (`.github/workflows/parity.yml`,
-`native-windows` job); the two entrypoints above (`windows-entrypoints.yml`).
-Deployed SessionStart/Notification hooks directly exec an absolute real
-`bun.exe`. Claude still shell-evaluates the statusline, so its stored command is
-an encoded PowerShell missing-file guard that behaves identically when the outer
-shell is native PowerShell or Git Bash. CI executes both outer-shell paths and
-pins output bytes/channels plus latency ceilings.
-
-**Status: supported** — real-machine verified 2026-07-09 (Claude Code loads
-the synced `%USERPROFILE%\.claude`; full sync, self-update, plugin passes,
-universal skills, and agent-browser all green on native PowerShell). Needs
-git on PATH for plugin marketplaces; rtk installs natively via its Windows
-release (the kit's auto-install is Unix-only).
+The supported host matrix is exact:
+
+| Platform | Architecture | docks-kit binary | Session Relay prebuilt | Sync engine |
+|----------|--------------|------------------|------------------------|-------------|
+| Linux | x64 | `docks-kit-linux-x64` | `x86_64-unknown-linux-musl` | EngineNative (TS) |
+| Linux | arm64 | `docks-kit-linux-arm64` | `aarch64-unknown-linux-musl` | EngineNative (TS) |
+| macOS | x64 | `docks-kit-darwin-x64` | `x86_64-apple-darwin` | EngineNative (TS) |
+| macOS | arm64 | `docks-kit-darwin-arm64` | `aarch64-apple-darwin` | EngineNative (TS) |
+
+Windows and every other host are unsupported. The launcher fails before any
+Bun-from-source fallback, and Session Relay installation reports the unsupported
+host without downloading an asset.
+
+EngineNative is the only supported engine on supported hosts.
+`DOCKS_KIT_ENGINE=bash` exits with the removed-engine message and points at the
+`bash-engine-final` tag for historical recovery.

package/cli/docs/sync-layers.md

@@ -26,10 +26,15 @@ Order matters — runtime readiness and settings form one transaction:
    `--claude-model`, `--claude-effort`, `--claude-advisor`) — deployed file only.
 7. ~/.claude.json (showTurnDuration, user-scoped MCP servers) and connector env
    export.
-8. **Plugins** — seven idempotent passes via the `claude plugin` CLI
+8. **Session Relay CLI** — ensure the exact source-pinned precompiled command
+   in `~/.local/bin` for the supported host. A staged asset must match both the
+   source digest and same-release `SHA256SUMS`, then report exact version before
+   atomic replacement. Failure stops before Session Relay plugin work and
+   preserves any prior command.
+9. **Plugins** — seven idempotent passes via the `claude plugin` CLI
    (marketplaces → install → update → [--prune: uninstall/remove] → re-assert
    SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
-9. LSP server binaries (npm globals).
+10. LSP server binaries (npm globals).
 
 The statusline reads Claude's native `rate_limits`. There is no OAuth request,
 usage cache, jq/curl runtime dependency, or Stop fetch hook.
@@ -40,12 +45,15 @@ bubblewrap check (Linux), config.toml merge (top-level keys replaced
 per-key, [table] blocks replaced wholesale, user-only keys/tables preserved),
 `--codex-model` then `--codex-effort` modifiers, rules, AGENTS.md, personal
 marketplace file, `codex plugin add` refresh.
+Immediately before `codex plugin add`, the same Session Relay CLI ensure runs;
+an ensure failure prevents the plugin pass.
 
 ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
 
 `npx skills add` per missing manifest slug, Claude symlink healing,
 CLI binaries (agent-browser, effect-solutions — toolchain-gated), and the
 kit-managed snapshot that `--prune` reconciles against.
+This target never ensures or downloads Session Relay.
 
 ## Reconcile flags
 

package/cli/docs/toolchain.md

@@ -4,8 +4,8 @@
 
 | Field | Meaning |
 |-------|---------|
-| `kind` | `check` (doctor visibility) / `managed` (kit installs + upgrades) / `pin` (no binary — a version pin for npx-invoked tools, e.g. `skills-cli`) |
-| `policy` | `track` (upgrade toward latest, gated by `verified`) / `present` (install when missing, never upgrade) |
+| `kind` | `check` (doctor visibility) / `managed` (kit installs + upgrades) / `managed-release` (dedicated source-pinned release transaction) / `pin` (no binary — a version pin for npx-invoked tools, e.g. `skills-cli`) |
+| `policy` | `track` (upgrade toward latest, gated by `verified`) / `present` (install when missing, never upgrade) / `exact` (install the declared release only) |
 | `floor` | Minimum acceptable version (below → upgrade automatically) |
 | `verified` | Last kit-tested version — the gate line |
 | `pinnable` | Whether an exact version can be installed (rtk: `RTK_VERSION=vX.Y.Z`) |
@@ -33,13 +33,24 @@ now kit-approved" act.
 - **bun** — policy `present`: bootstrap only (pinned to `verified` via the
   installer's version argument), never auto-upgraded. `bun.ts` owns one
   per-engine-run memo shared by Claude runtime, effect-solutions, and direct
-  toolchain ensure. Windows resolves only a real absolute `bun.exe` for hooks.
+  toolchain ensure on supported Linux/macOS hosts.
 - **effect-solutions**, **agent-browser** — policy `track`: self-upgrade
   toward npm latest, gated by their `verified` pins.
+- **session-relay** — policy `exact`: Claude/Codex sync and
+  `docks-kit toolchain ensure session-relay` select exactly one of four targets
+  (`x86_64-unknown-linux-musl`, `aarch64-unknown-linux-musl`,
+  `x86_64-apple-darwin`, `aarch64-apple-darwin`). The installer downloads the
+  pinned `session-relay--v0.12.0` asset and same-release `SHA256SUMS`, requires
+  source pin = selected row = downloaded bytes, chmods/smoke-tests only the
+  sibling stage, then renames it over `~/.local/bin/session-relay`. Offline,
+  unsupported-host, checksum, chmod, version, download, or rename failures
+  preserve an existing command byte-for-byte. The four pinned production
+  digests correspond to the stable `session-relay--v0.12.0` assets and match
+  its `SHA256SUMS`.
 
 jq and curl are `check` rows, not global prerequisites. jq is not consumed by
-normal sync. curl is checked only at a requested POSIX RTK/Bun installer
-download boundary; Windows Bun bootstrap uses PowerShell's native download.
+normal sync. curl is checked only at a requested Linux/macOS RTK/Bun installer
+download boundary.
 
 ## Supply-chain stance
 
@@ -55,5 +66,6 @@ probe falls back to the pinned `verified`, never to an ungated latest.
 ```
 docks-kit toolchain check            # doctor table (also inside docks-kit status)
 docks-kit toolchain ensure rtk       # install/upgrade one tool per policy
+docks-kit toolchain ensure session-relay # install exact verified release
 docks-kit sync --yes                 # unattended: auto-accept gates
 ```

package/cli/src/commands/docs.ts

@@ -20,7 +20,7 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
   "toolchain": { summary: "Verified-version floors, gate policy, --yes semantics", body: toolchain },
   "plugins": { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
   "install": { summary: "Install paths: repo checkout, bun add -g, curl installer", body: install },
-  "platforms": { summary: "Platform support: Linux/macOS native, Windows via Git Bash/WSL", body: platforms }
+  "platforms": { summary: "Platform support: Linux/macOS x64 and arm64", body: platforms }
 }
 
 const topic = Args.text({ name: "topic" }).pipe(

package/cli/src/commands/toolchain.ts

@@ -2,7 +2,7 @@ import { Args, Command, Options } from "@effect/cli"
 import { Effect, Option } from "effect"
 import { bail, engine } from "../engine"
 
-const MANAGED = ["rtk", "bun", "effect-solutions", "agent-browser"]
+const MANAGED = ["rtk", "bun", "effect-solutions", "agent-browser", "session-relay"]
 
 const op = Args.text({ name: "op" }).pipe(
   Args.withDescription("check (default) | ensure <tool>"),

package/cli/src/engine-native/DESIGN.md

@@ -96,12 +96,10 @@ hooks/env changed → restart line; skills changed → discovery line) or under
 
 ### Platform seam
 
-All platform branching routes through `os.ts` — the only engine module that
-reads `process.platform`, with one named exemption: `exec.ts`'s path/exec
-primitives (`commandExists` PATHEXT resolution and `X_OK` probing) stay
-self-contained because they sit below the seam. `deps.ts` install hints
-default their platform from `os.ts` and keep the parameter injectable for
-tests.
+All host detection routes through `os.ts`, the engine module that reads
+`process.platform`. `exec.ts` contains only POSIX executable and PATH probes.
+`deps.ts` install hints default their platform from `os.ts` and keep the
+parameter injectable for tests.
 
 ### Verbosity plumbing
 
@@ -122,7 +120,7 @@ active logger binding.
 | `../payload.ts` | generated text/byte payload reads and presentation-only source labels |
 | `claudeSync.ts` | Claude pipeline: RTK, prepared settings transaction, runtime assets, deploy-time modifiers, `~/.claude.json`, readiness-gated removed artifacts, plugins, optional plugins, LSP binaries |
 | `bun.ts` | per-run memoized Bun resolution/bootstrap shared by Claude runtime, effect-solutions, and direct toolchain ensure |
-| `claudeRuntime.ts` | sentinel validation, absolute runtime paths, no-cutover settings projection, and POSIX/encoded-PowerShell statusline commands |
+| `claudeRuntime.ts` | sentinel validation, absolute runtime paths, no-cutover settings projection, and POSIX statusline commands |
 | `settings.ts` | pure Claude settings merge/reconcile semantics and permission-array union |
 | `claudeModel.ts` | deployed Claude model modifier and direct `model claude` write path |
 | `codexSync.ts` | Codex pipeline: bubblewrap check, config merge, rules, AGENTS.md, personal marketplace, plugin refresh |
@@ -132,24 +130,20 @@ active logger binding.
 | `modes.ts` | direct `model` and `toolchain` modes |
 | `models.ts` | model catalog listing and validation |
 | `jq.ts` | JSON helpers that preserve jq-style merge/order/stringify behavior where the deployed file contract needs it |
-| `exec.ts` | path helpers, command probes, capture/spawn wrappers, Windows command resolution, change-detecting write/copy helpers |
+| `exec.ts` | slash-stable path helpers, POSIX command probes, capture/spawn wrappers, and change-detecting write/copy helpers |
 | `logger.ts` | Logger shape + stable raw stdout/stderr sink factory; the run-scoped verbosity gate lives in `index.ts` |
-| `deps.ts` | external-tool registry: identity, requirement class, presence probe, platform-correct install hints, per-manager missing-tool dedup; callers supply the current run Logger to `warnMissing` |
-| `os.ts` | platform capability seam — the single `process.platform` reader (`platformName`, `isWindows`, `isLinux`, shell-rc applicability) |
+| `deps.ts` | external-tool registry: identity, requirement class, presence probe, supported-host install hints, per-manager missing-tool dedup; callers supply the current run Logger to `warnMissing` |
+| `os.ts` | platform capability seam — the single `process.platform` reader (`platformName`, `isLinux`, shell-rc applicability) |
 | `services.ts` | shared raw-Logger + DependencyManager + Platform factory; wrapped in Effect Layers at `cli/src/services.ts`, with the run-scoped Logger gate applied only by `runEngineNative` |
 
-## Windows Specifics
+## Platform Support
 
-- Home resolves through Node's platform APIs; CI deliberately unsets `HOME` so
-  `%USERPROFILE%` is exercised.
-- Paths are built through `node:path`.
-- Connector env uses `setx` on win32; Unix shell rc files are not touched.
-- Symlink creation falls back to copy where the platform or permissions require
-  it.
-- Bubblewrap and shell-rc work are Linux/macOS only.
-- Claude command hooks directly exec the resolved absolute `bun.exe`; the
-  statusline stores an encoded PowerShell missing-file guard because Claude
-  shell-evaluates `statusLine.command` through PowerShell or Git Bash.
+- EngineNative supports Linux and macOS on x64 and arm64.
+- Unsupported hosts fail before launcher fallback, dependency probes, downloads,
+  settings writes, or sync work.
+- Runtime hooks use POSIX commands and absolute Bun paths.
+- Symlink creation remains capability-driven: permission or filesystem failures
+  fall back to copy without predicting the host.
 
 ## Tests
 
@@ -158,12 +152,10 @@ active logger binding.
   `cli/test/goldens/dryrun.json`.
 - `bun run golden:mutation` compares live native mutation snapshots, argv logs,
   output, and TOML invariants to `cli/test/goldens/mutation.json`.
-- `.github/workflows/parity.yml` is now the golden-regression workflow: Linux
-  runs unit + golden + prove-red plus the exact materialized POSIX runtime
-  commands; the `native-windows` job executes the same stored statusline command
-  through PowerShell and Git Bash plus direct Bun hooks.
-- `.github/workflows/windows-entrypoints.yml` verifies the release binary and
-  `bun add -g` entrypoints on Windows.
+- `.github/workflows/parity.yml` is the golden-regression workflow: Linux runs
+  unit + golden + prove-red plus the exact materialized POSIX runtime commands.
+- `.github/workflows/release-cli.yml` publishes the four Linux/macOS x64/arm64
+  binaries, `SHA256SUMS`, and the npm package.
 
 ## Non-Goals
 

package/cli/src/engine-native/bun.ts

@@ -4,7 +4,6 @@ import { tmpdir } from "node:os"
 
 import { p } from "./exec"
 import type { Ctx } from "./index"
-import { encodePowerShellCommand, powerShellLiteral } from "./powershell"
 import type { EngineServices } from "./services"
 import { field } from "./toolchain"
 
@@ -17,31 +16,14 @@ function remember(ctx: Ctx, state: BunRuntimeState): BunRuntimeState {
   return state
 }
 
-function predictedExecutable(ctx: Ctx, services: EngineServices): string {
+function predictedExecutable(ctx: Ctx): string {
   const root = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
     ? process.env["BUN_INSTALL"]!
     : p(ctx.home, ".bun")
-  return p(root, "bin", services.platform.isWindows() ? "bun.exe" : "bun")
+  return p(root, "bin", "bun")
 }
 
-function windowsDownloadScript(installer: string): string {
-  return `$ErrorActionPreference = 'Stop'; Invoke-WebRequest -Uri ${powerShellLiteral("https://bun.sh/install.ps1")} -OutFile ${powerShellLiteral(installer)}`
-}
-
-function installBun(ctx: Ctx, services: EngineServices, pin: string, installer: string): void {
-  if (services.platform.isWindows()) {
-    const encoded = encodePowerShellCommand(windowsDownloadScript(installer))
-    const download = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], { stdio: "ignore" })
-    if (download.error === undefined && download.status === 0) {
-      spawnSync(
-        "powershell.exe",
-        ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", installer, "-Version", pin, "-DownloadWithoutCurl"],
-        { stdio: "ignore" }
-      )
-    }
-    return
-  }
-
+function installBun(pin: string, installer: string): void {
   const download = spawnSync("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], { stdio: "ignore" })
   if (download.error === undefined && download.status === 0) {
     spawnSync("bash", [installer, `bun-v${pin}`], { stdio: "ignore" })
@@ -59,19 +41,19 @@ export function bunBootstrap(ctx: Ctx, services: EngineServices): BunRuntimeStat
     services.logger.warn("Bun bootstrap aborted — SoT/toolchain.json has no verified Bun pin")
     return remember(ctx, { kind: "deferred", reason: "install-failed" })
   }
-  if (!services.platform.isWindows() && services.deps.probe("curl").state === "missing") {
+  if (services.deps.probe("curl").state === "missing") {
     services.deps.warnMissing("curl", services.logger, "cannot bootstrap Bun; install Bun manually, then re-run sync")
     return remember(ctx, { kind: "deferred", reason: "missing-curl" })
   }
   if (ctx.dryRun) {
-    const executable = predictedExecutable(ctx, services)
+    const executable = predictedExecutable(ctx)
     services.logger.echo(`[dry-run] install Bun ${pin} (kit-verified) -> ${executable}`)
     return remember(ctx, { kind: "ready", executable })
   }
   services.logger.warn(`Bun not found — installing Bun ${pin} (kit-verified)...`)
-  const installer = p(tmpdir(), `bun-install-${process.pid}.${services.platform.isWindows() ? "ps1" : "sh"}`)
+  const installer = p(tmpdir(), `bun-install-${process.pid}.sh`)
   try {
-    installBun(ctx, services, pin, installer)
+    installBun(pin, installer)
   } finally {
     rmSync(installer, { force: true })
   }

package/cli/src/engine-native/claudeRuntime.ts

@@ -1,7 +1,5 @@
 import { p } from "./exec"
 import { isObject, parseJson, type Json } from "./jq"
-import { encodePowerShellCommand, powerShellLiteral } from "./powershell"
-import type { Platform } from "./services"
 
 const BUN_SENTINEL = "__DOCKS_KIT_BUN__"
 const SESSION_START_SENTINEL = "__DOCKS_KIT_SESSION_START__"
@@ -89,22 +87,15 @@ function posixLiteral(value: string): string {
   return `'${value.replaceAll("'", `'"'"'`)}'`
 }
 
-export function statusLineCommand(runtime: ClaudeRuntimePaths, platform: Platform): string {
-  if (!platform.isWindows()) {
-    const bun = posixLiteral(runtime.bun)
-    const script = posixLiteral(runtime.statusline)
-    return `test -x ${bun} && test -f ${script} && exec ${bun} ${script} || true`
-  }
-  const bun = powerShellLiteral(runtime.bun.replaceAll("\\", "/"))
-  const script = powerShellLiteral(runtime.statusline.replaceAll("\\", "/"))
-  const guard = `$ProgressPreference = 'SilentlyContinue'; if ((Test-Path -LiteralPath ${bun} -PathType Leaf) -and (Test-Path -LiteralPath ${script} -PathType Leaf)) { & ${bun} ${script} }`
-  return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${encodePowerShellCommand(guard)}`
+export function statusLineCommand(runtime: ClaudeRuntimePaths): string {
+  const bun = posixLiteral(runtime.bun)
+  const script = posixLiteral(runtime.statusline)
+  return `test -x ${bun} && test -f ${script} && exec ${bun} ${script} || true`
 }
 
 export function materializeClaudeSettings(
   template: Json,
-  runtime: ClaudeRuntimePaths | undefined,
-  platform: Platform
+  runtime: ClaudeRuntimePaths | undefined
 ): Json {
   validateTemplate(template)
   const result = cloneJson(template)
@@ -122,7 +113,7 @@ export function materializeClaudeSettings(
     notification["command"] = runtime.bun
     notification["args"] = [runtime.notify]
     if (!isObject(result) || !isObject(result["statusLine"])) throw new Error("Claude statusLine object is missing")
-    result["statusLine"]["command"] = statusLineCommand(runtime, platform)
+    result["statusLine"]["command"] = statusLineCommand(runtime)
   }
 
   for (const sentinel of [BUN_SENTINEL, SESSION_START_SENTINEL, NOTIFY_SENTINEL, STATUSLINE_SENTINEL]) {