docks-kit 0.15.2 → 0.15.3

package/cli/src/commands/update.ts

@@ -1,20 +1,62 @@
 import { Command, Flag } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
-import { spawnSync } from "node:child_process"
+import { spawnSync, type SpawnSyncOptions, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process"
 import { existsSync, readFileSync } from "node:fs"
-import { join } from "node:path"
 import { bail, compiled } from "../engine"
 import { kitHome } from "../kitHome"
+import { p, which } from "../engine-native/exec"
+import { hostOs, type HostOs, type Invocation } from "../engine-native/os"
 
 const noSync = Flag.boolean("no-sync").pipe(
   Flag.withDescription("Update the kit only; skip the chained flag-less sync")
 )
 
-const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {
-  const res = spawnSync("git", ["-C", home, ...args], {
+/** A tool this host cannot resolve, shaped like the failed spawn it replaces. */
+const notFound = (command: string): SpawnSyncReturns<string> => ({
+  pid: 0,
+  output: [],
+  stdout: "",
+  stderr: "",
+  status: null,
+  signal: null,
+  error: new Error(`command not found on PATH: ${command}`)
+})
+
+/**
+ * Every child in this command starts here, because two host facts must never be
+ * separated from the argv they describe: a Windows shim invocation is only
+ * correct with the verbatim-arguments flag, and a pathless name would let
+ * CreateProcess search the parent's current directory before the system one.
+ */
+export const spawnUpdate = (
+  command: string,
+  args: ReadonlyArray<string>,
+  overrides: SpawnSyncOptions = {},
+  host: HostOs = hostOs()
+): SpawnSyncReturns<string> => {
+  const resolvesSuffixes = host.executableSuffixes.some((suffix) => suffix !== "")
+  const executablePath = resolvesSuffixes ? which(command, host.executableSuffixes) : command
+  if (executablePath === "") return notFound(command)
+  let invocation: Invocation
+  try {
+    invocation = host.invoke(executablePath, args)
+  } catch (cause) {
+    // A value this host cannot put on a command line at all. Print the encoder's
+    // reason and exit, matching how this command reports a failed child.
+    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`)
+    return process.exit(2)
+  }
+  const options: SpawnSyncOptionsWithStringEncoding = {
+    stdio: ["ignore", "pipe", "pipe"],
+    ...overrides,
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
-  })
+    windowsVerbatimArguments: invocation.windowsVerbatimArguments
+  }
+  return spawnSync(invocation.command, [...invocation.args], options)
+}
+
+const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {
+  const res = spawnUpdate("git", ["-C", home, ...args])
   return { ok: res.error === undefined && res.status === 0, out: `${res.stdout ?? ""}${res.stderr ?? ""}`.trim() }
 }
 
@@ -22,19 +64,19 @@ const git = (home: string, args: Array<string>): { ok: boolean; out: string } =>
  * version loaded, so the chained sync must be a new process. */
 const chainSync = (argv0: string, args: Array<string>): Effect.Effect<void> =>
   Effect.sync(() => {
-    const res = spawnSync(argv0, args, { stdio: "inherit" })
+    const res = spawnUpdate(argv0, args, { stdio: "inherit" })
     if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1)
   })
 
 export const updateSyncArgs = (home: string): Array<string> => [
-  join(home, "cli/src/main.ts"),
+  p(home, "cli/src/main.ts"),
   "sync",
   "--skip-plugin-refresh"
 ]
 
 const readPackageVersion = (home: string): string => {
   try {
-    const doc: unknown = JSON.parse(readFileSync(join(home, "package.json"), "utf8"))
+    const doc: unknown = JSON.parse(readFileSync(p(home, "package.json"), "utf8"))
     if (doc === null || typeof doc !== "object" || !("version" in doc)) return ""
     return typeof doc.version === "string" ? doc.version : ""
   } catch {
@@ -56,10 +98,7 @@ type CapturePackageRoot = (
 ) => PackageRootCapture
 
 const capturePackageRoot: CapturePackageRoot = (command, args) => {
-  const res = spawnSync(command, [...args], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
-  })
+  const res = spawnUpdate(command, args)
   return {
     status: res.status,
     stdout: res.stdout ?? "",
@@ -67,15 +106,27 @@ const capturePackageRoot: CapturePackageRoot = (command, args) => {
   }
 }
 
+/**
+ * A Bun global home is `<root>/.bun/install/global/node_modules/<pkg>`. Windows
+ * reports that path with backslashes, so containment is tested on a normalized
+ * copy — but only on Windows, because a backslash is a legal POSIX filename
+ * character and must never be read as a separator there.
+ */
 export const packageManagerForHome = (
   home: string,
-  environment: NodeJS.ProcessEnv = process.env
+  environment: NodeJS.ProcessEnv = process.env,
+  host: HostOs = hostOs()
 ): PackageManager => {
+  const normalize = (value: string): string =>
+    host.id === "windows" ? value.replaceAll("\\", "/") : value
+  const normalizedHome = normalize(home)
   const underEnvironmentRoot = (name: "BUN_INSTALL_GLOBAL_DIR" | "BUN_INSTALL"): boolean => {
     const root = environment[name]?.trim()
-    return root !== undefined && root !== "" && (home === root || home.startsWith(`${root}/`))
+    if (root === undefined || root === "") return false
+    const normalizedRoot = normalize(root)
+    return normalizedHome === normalizedRoot || normalizedHome.startsWith(`${normalizedRoot}/`)
   }
-  return home.includes("/.bun/") ||
+  return normalizedHome.includes("/.bun/") ||
     underEnvironmentRoot("BUN_INSTALL_GLOBAL_DIR") ||
     underEnvironmentRoot("BUN_INSTALL")
     ? "bun"
@@ -107,7 +158,7 @@ export const resolveGlobalPackageHome = (
     const root = result.stdout.trim()
     return root === ""
       ? { ok: false, diagnostic: "npm root -g failed: empty output" }
-      : { ok: true, home: join(root, "docks-kit") }
+      : { ok: true, home: p(root, "docks-kit") }
   }
 
   const globalHeader = result.stdout
@@ -120,7 +171,7 @@ export const resolveGlobalPackageHome = (
       : /^(.*) node_modules(?: \(\d+\))?$/.exec(globalHeader)?.[1]
   return globalDir === undefined || globalDir === ""
     ? { ok: false, diagnostic: "bun pm -g ls did not report its global package root" }
-    : { ok: true, home: join(globalDir, "node_modules", "docks-kit") }
+    : { ok: true, home: p(globalDir, "node_modules", "docks-kit") }
 }
 
 export const packageUpdateResult = (
@@ -143,7 +194,7 @@ export const packageUpdateResult = (
 
 const updateCheckout = (home: string, skipSync: boolean) =>
   Effect.gen(function* () {
-    if (spawnSync("git", ["--version"], { stdio: "ignore" }).status !== 0) {
+    if (spawnUpdate("git", ["--version"], { stdio: "ignore" }).status !== 0) {
       return yield* bail("git not found - cannot update the kit checkout")
     }
     const dirty = git(home, ["status", "--porcelain"])
@@ -169,7 +220,7 @@ const updateCheckout = (home: string, skipSync: boolean) =>
 
     const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n")
     if (touched.includes("bun.lock") || touched.includes("package.json")) {
-      const res = spawnSync("bun", ["install", "--frozen-lockfile"], { cwd: home, stdio: "inherit" })
+      const res = spawnUpdate("bun", ["install", "--frozen-lockfile"], { cwd: home, stdio: "inherit" })
       if (res.error !== undefined || res.status !== 0) {
         return yield* bail("dependencies changed but 'bun install --frozen-lockfile' failed - fix that, then run docks-kit sync", 1)
       }
@@ -189,10 +240,10 @@ const updatePackage = (home: string, skipSync: boolean) =>
   Effect.gen(function* () {
     const manager = packageManagerForHome(home)
     const beforeVersion = readPackageVersion(home)
-    const res =
-      manager === "bun"
-        ? spawnSync("bun", ["add", "-g", "docks-kit@latest"], { stdio: "inherit" })
-        : spawnSync("npm", ["install", "-g", "docks-kit@latest"], { stdio: "inherit" })
+    const updateArgs = manager === "bun"
+      ? ["add", "-g", "docks-kit@latest"]
+      : ["install", "-g", "docks-kit@latest"]
+    const res = spawnUpdate(manager, updateArgs, { stdio: "inherit" })
     if (res.error !== undefined || res.status !== 0) {
       return yield* bail(
         `global package update failed (${manager === "bun" ? "bun add -g" : "npm install -g"} docks-kit@latest)`,
@@ -210,7 +261,7 @@ const updatePackage = (home: string, skipSync: boolean) =>
     const afterVersion = readPackageVersion(updated.home)
     if (afterVersion === "") {
       return yield* bail(
-        `global package update completed, but ${join(updated.home, "package.json")} has no readable version`,
+        `global package update completed, but ${p(updated.home, "package.json")} has no readable version`,
         1
       )
     }
@@ -225,7 +276,7 @@ const updatePackage = (home: string, skipSync: boolean) =>
 export const updateCommand = Command.make("update", { noSync }, (config) =>
   Effect.gen(function* () {
     const home = kitHome()
-    if (existsSync(join(home, ".git"))) {
+    if (existsSync(p(home, ".git"))) {
       return yield* updateCheckout(home, config.noSync)
     }
     if (home.includes("node_modules")) {

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

@@ -38,8 +38,8 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
   serial, and summaries retain canonical Claude, Codex, skills order.
 - **External CLIs stay external.** `claude`, `codex`, `npx`, `npm`, `bun`,
   `curl`, and platform package managers are spawned with argv arrays,
-  not shell command strings except where the external installer contract is a
-  shell script.
+  not shell command strings except where an external installer contract
+  requires a script interpreter.
 - **Backups precede mutation.** Deployed settings/config files write `.bak`
   backups before replacement.
 - **Runtime payload is in memory.** `SoT/` remains the reviewed authoring tree;
@@ -97,7 +97,7 @@ each such skip is an intentional behavior change named in its golden diff.
 Exactly one deduplicated warn per requested missing tool per run, uniform shape:
 `[warn] <tool> not installed — <platform-correct install command>`, sourced
 from the dependency registry (`deps.ts`). jq and curl are optional report rows:
-jq has no runtime consumer, while curl warns only when a requested POSIX Bun
+jq has no runtime consumer, while curl warns only when a requested Bun
 bootstrap needs an installer download. A missing Bun defers Claude runtime
 migration without deleting working legacy hooks or statusline files.
 
@@ -116,10 +116,11 @@ changed → restart line; skills changed → discovery line) or under `--verbose
 
 ### Platform seam
 
-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.
+All host detection routes through `os/index.ts`, which holds the engine's only
+`process.platform` read and keeps platform normalization injectable for tests.
+Per-OS facts live in `os/linux.ts`, `os/darwin.ts`, and `os/windows.ts` behind
+`HostOs`; consumers select those facts through the package rather than branching
+on the host directly.
 
 ### Verbosity plumbing
 
@@ -139,43 +140,51 @@ active logger binding.
 | `index.ts` | sync orchestration, target dispatch, run summary and next-step blocks |
 | `../payload.ts` | generated text/byte payload reads and presentation-only source labels |
 | `claudeSync.ts` | Claude pipeline: Bun bootstrap, 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 statusline commands |
+| `bun.ts` | per-run memoized Bun resolution/bootstrap shared by the Claude runtime and direct toolchain ensure |
+| `claudeRuntime.ts` | sentinel validation, absolute runtime paths, no-cutover settings projection, and per-host statusline and failure-hook command materialization |
 | `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 |
 | `codexToml.ts` | line-based top-level TOML replacement and deployed Codex model modifier |
-| `skillsSync.ts` | universal skill install/prune, Claude symlink healing, effect-solutions callback, managed-skill snapshot |
-| `toolchain.ts` | tool presence/version probes, verified-version gate, managed install/upgrade orchestration, report table |
+| `skillsSync.ts` | universal skill install/prune, ordered symlink/junction/copy fallback, Claude entry healing, managed-skill snapshot |
+| `toolchain.ts` | tool presence/version probes, verified-version floor reporting, report table |
 | `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` | slash-stable path helpers, POSIX command probes, capture/spawn wrappers, and change-detecting write/copy helpers |
+| `exec.ts` | slash-stable path helpers, host-aware PATH probes and invocation, 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, supported-host install hints, per-manager missing-tool dedup; callers supply the current run Logger to `warnMissing` |
-| `os.ts` | platform capability seam — host reader and injected platform normalization (`rawPlatform`, `platformName`) |
+| `os/` | host reader, injected platform normalization, and per-OS `HostOs` fact modules |
 | `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` |
 
 ## Platform Support
 
-- EngineNative supports Linux and macOS on x64 and arm64.
+- EngineNative supports Linux, macOS, and Windows 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.
+- Claude runtime settings use absolute Bun/script paths and materialize
+  statusline and failure-hook commands through the selected `HostOs`.
+- Directory linking is capability-driven. The host module supplies only the
+  order while the runtime decides the outcome: symlink, then a Windows junction
+  with an absolute target, then a recursive copy. Copies carry a kit marker so
+  later sync can heal them back to a real link and prune can reclaim them
+  without touching user-owned directories.
 
 ## Tests
 
-- `bun run test:unit` covers pure JSON merge semantics and jq-oracle cases.
+- `bun run test:unit` covers pure JSON merge semantics, jq-oracle cases, and
+  the three `HostOs` modules independently of the current host.
 - `bun run golden:dryrun` compares live native dry-run output to
   `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 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.
+- `.github/workflows/parity.yml` runs its portable lane on `ubuntu-24.04`,
+  `macos-26`, and `windows-2025`: typecheck, unit tests, host-specific runtime
+  command checks, and compilation and execution of the native host artifact.
+  The Linux-canonical snapshot lane stays on Ubuntu and runs both golden suites
+  plus their prove-red checks.
+- `.github/workflows/release-cli.yml` publishes six binaries for Linux, macOS,
+  and Windows on x64 and arm64, plus `SHA256SUMS` and the npm package.
 
 ## Non-Goals
 

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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os"
 import { p, spawnProcess, type AsyncProcessOptions, type AsyncProcessResult } from "./exec"
 import type { Ctx } from "./index"
 import type { EngineServices } from "./services"
+import { hostOs, type HostOs } from "./os"
 import { field } from "./toolchain"
 
 export type BunRuntimeState =
@@ -13,11 +14,11 @@ export type BunRuntimeState =
       readonly reason: "missing-curl" | "download-failed" | "installer-failed" | "install-failed"
     }
 
-function predictedExecutable(ctx: Ctx): string {
+function predictedExecutable(ctx: Ctx, host: HostOs = hostOs()): string {
   const root = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
     ? process.env["BUN_INSTALL"]!
     : p(ctx.home, ".bun")
-  return p(root, "bin", "bun")
+  return p(root, "bin", host.bunExecutableName)
 }
 
 type BunInstallResult =
@@ -29,13 +30,14 @@ function processFailure(result: AsyncProcessResult): string {
   return details.join(": ") || (result.exitCode === null ? "the process ended without an exit code" : `exit code ${result.exitCode}`)
 }
 
-async function installBun(pin: string, installer: string): Promise<BunInstallResult> {
+async function installBun(pin: string, directory: string, host: HostOs = hostOs()): Promise<BunInstallResult> {
   const options: AsyncProcessOptions = { stdio: ["ignore", "ignore", "pipe"] }
-  const download = await spawnProcess("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], options)
+  const installer = host.bunInstaller(pin, directory)
+  const download = await spawnProcess(installer.download.command, installer.download.args, options)
   if (download.error !== undefined || download.exitCode !== 0) {
     return { ok: false, reason: "download-failed", detail: processFailure(download) }
   }
-  const install = await spawnProcess("bash", [installer, `bun-v${pin}`], options)
+  const install = await spawnProcess(installer.run.command, installer.run.args, options)
   if (install.error !== undefined || install.exitCode !== 0) {
     return { ok: false, reason: "installer-failed", detail: processFailure(install) }
   }
@@ -50,6 +52,7 @@ export function bunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunRun
 }
 
 async function runBunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunRuntimeState> {
+  const host = hostOs(services.platform.name())
 
   const existing = await services.deps.path("bun")
   if (existing !== "") return { kind: "ready", executable: existing }
@@ -64,16 +67,15 @@ async function runBunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunR
     return { kind: "deferred", reason: "missing-curl" }
   }
   if (ctx.dryRun) {
-    const executable = predictedExecutable(ctx)
+    const executable = predictedExecutable(ctx, host)
     services.logger.echo(`[dry-run] install Bun ${pin} (kit-verified) -> ${executable}`)
     return { kind: "ready", executable }
   }
   services.logger.warn(`Bun not found — installing Bun ${pin} (kit-verified)...`)
   const temporaryDir = mkdtempSync(p(tmpdir(), "docks-kit-bun-"))
-  const installer = p(temporaryDir, "install.sh")
   let result: BunInstallResult
   try {
-    result = await installBun(pin, installer)
+    result = await installBun(pin, temporaryDir, host)
   } finally {
     rmSync(temporaryDir, { recursive: true, force: true })
   }

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

@@ -1,5 +1,6 @@
 import { p } from "./exec"
 import { isObject, parseJson, type Json } from "./jq"
+import { hostOs, type HostOs } from "./os"
 
 const BUN_SENTINEL = "__DOCKS_KIT_BUN__"
 const SESSION_START_SENTINEL = "__DOCKS_KIT_SESSION_START__"
@@ -83,23 +84,30 @@ function validateTemplate(template: Json): void {
   }
 }
 
-function posixLiteral(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`
-}
 
-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 statusLineCommand(runtime: ClaudeRuntimePaths, host: HostOs = hostOs()): string {
+  return host.statusLineCommand(runtime.bun, runtime.statusline)
 }
 
 export function materializeClaudeSettings(
   template: Json,
-  runtime: ClaudeRuntimePaths | undefined
+  runtime: ClaudeRuntimePaths | undefined,
+  host: HostOs = hostOs()
 ): Json {
   validateTemplate(template)
   const result = cloneJson(template)
   const hooks = hooksObject(result)
+  const failureGroups = hooks["PostToolUseFailure"]
+  if (Array.isArray(failureGroups)) {
+    for (const group of failureGroups) {
+      if (!isObject(group) || !Array.isArray(group["hooks"])) continue
+      for (const handler of group["hooks"]) {
+        if (isObject(handler) && handler["type"] === "command" && typeof handler["command"] === "string") {
+          handler["command"] = host.failureHookCommand(handler["command"])
+        }
+      }
+    }
+  }
   if (runtime === undefined) {
     delete hooks["SessionStart"]
     delete hooks["Notification"]
@@ -113,7 +121,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)
+    result["statusLine"]["command"] = statusLineCommand(runtime, host)
   }
 
   for (const sentinel of [BUN_SENTINEL, SESSION_START_SENTINEL, NOTIFY_SENTINEL, STATUSLINE_SENTINEL]) {

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

@@ -26,6 +26,7 @@ import { p, spawnProcess, writeBytesIfChanged, writeTextIfChanged } from "./exec
 import type { Ctx } from "./index"
 import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, type Json } from "./jq"
 import { ExitError } from "./parseArgs"
+import { hostOs } from "./os"
 import { mergeSettings, reconcileSettings } from "./settings"
 import { field } from "./toolchain"
 import { payloadBytes, payloadDisplayPath, payloadText } from "../payload"
@@ -75,7 +76,7 @@ export async function claudeSync(ctx: Ctx): Promise<ClaudeRuntimeState> {
   syncClaudeEffort(ctx, ctx.claudeEffort)
   syncClaudeAdvisor(ctx, ctx.claudeAdvisor)
   syncClaudeJson(ctx)
-  syncConnectorEnv(ctx)
+  await syncConnectorEnv(ctx)
   await syncPlugins(ctx, claudeDir)
   await syncOptionalPlugins(ctx, claudeDir)
   await syncLspServers(ctx)
@@ -320,36 +321,62 @@ function syncClaudeJson(ctx: Ctx): void {
 
 // -------------------------------------------------------- connector env ----
 
-function syncConnectorEnv(ctx: Ctx): void {
-  const { change, echo, verbose } = ctx.services.logger
-
-  const line = "export ENABLE_CLAUDEAI_MCP_SERVERS=false"
-  const marker = "# docks-kit: disable claude.ai cloud MCP connectors (set =true to keep them)"
-  const candidates = [".zshrc", ".bashrc", ".bash_profile", ".profile", ".zshenv"].map((f) => p(ctx.home, f))
+async function syncConnectorEnv(ctx: Ctx): Promise<void> {
+  const { change, echo, verbose, warn } = ctx.services.logger
+  const name = "ENABLE_CLAUDEAI_MCP_SERVERS"
+  const setting = hostOs().environmentSetting(name, "false")
+
+  switch (setting.kind) {
+    case "profile": {
+      const marker = "# docks-kit: disable claude.ai cloud MCP connectors (set =true to keep them)"
+      const candidates = setting.candidates.map((candidate) => p(ctx.home, candidate))
+
+      for (const f of candidates) {
+        if (existsSync(f) && readFileSync(f, "utf8").includes(name)) {
+          if (ctx.dryRun) {
+            echo(`[dry-run] ${name} already in ${f} — would skip`)
+          } else {
+            verbose(`claude.ai connectors: ${name} already set in ${f} (left as-is)`)
+          }
+          return
+        }
+      }
 
-  for (const f of candidates) {
-    if (existsSync(f) && readFileSync(f, "utf8").includes("ENABLE_CLAUDEAI_MCP_SERVERS")) {
+      const target = p(ctx.home, setting.target(process.env["SHELL"]))
       if (ctx.dryRun) {
-        echo(`[dry-run] ENABLE_CLAUDEAI_MCP_SERVERS already in ${f} — would skip`)
-      } else {
-        verbose(`claude.ai connectors: ENABLE_CLAUDEAI_MCP_SERVERS already set in ${f} (left as-is)`)
+        echo(`[dry-run] append '${setting.line}' to ${target}`)
+        return
       }
+
+      appendFileSync(target, `\n${marker}\n${setting.line}\n`)
+      change(`claude.ai connectors disabled via ${target} (start a new shell to apply)`)
+      ctx.nextStepTriggers.claudeRestart = true
       return
     }
-  }
+    case "command": {
+      const existing = await spawnProcess(setting.probe.command, setting.probe.args, { stdio: "ignore" })
+      if (existing.error === undefined && existing.exitCode === 0) {
+        if (ctx.dryRun) echo(`[dry-run] ${name} already in ${setting.location} — would skip`)
+        else verbose(`claude.ai connectors: ${name} already set in ${setting.location} (left as-is)`)
+        return
+      }
 
-  const shell = process.env["SHELL"] ?? "bash"
-  const shellName = shell.slice(shell.lastIndexOf("/") + 1)
-  const target = shellName === "zsh" ? p(ctx.home, ".zshrc") : shellName === "bash" ? p(ctx.home, ".bashrc") : p(ctx.home, ".profile")
+      const applyCommand = [setting.apply.command, ...setting.apply.args].join(" ")
+      if (ctx.dryRun) {
+        echo(`[dry-run] ${applyCommand} (${setting.location})`)
+        return
+      }
 
-  if (ctx.dryRun) {
-    echo(`[dry-run] append 'export ENABLE_CLAUDEAI_MCP_SERVERS=false' to ${target}`)
-    return
+      const applied = await spawnProcess(setting.apply.command, setting.apply.args, { stdio: "ignore" })
+      if (applied.error === undefined && applied.exitCode === 0) {
+        change(`claude.ai connectors disabled via ${setting.apply.command} (open a new terminal to apply)`)
+        ctx.nextStepTriggers.claudeRestart = true
+      } else {
+        warn(`${applyCommand} failed — ${setting.manualHint}`)
+      }
+      return
+    }
   }
-
-  appendFileSync(target, `\n${marker}\n${line}\n`)
-  change(`claude.ai connectors disabled via ${target} (start a new shell to apply)`)
-  ctx.nextStepTriggers.claudeRestart = true
 }
 
 // ------------------------------------------------------------- removals ----
@@ -366,6 +393,7 @@ const REMOVED_MANIFEST = {
     "env.CLAUDE_CODE_DISABLE_1M_CONTEXT",
     "env.CLAUDE_CODE_FORK_SUBAGENT",
     "env.CLAUDE_CODE_EFFORT_LEVEL",
+    "enabledPlugins.effect-kit@docks",
     "enabledPlugins.session-relay@docks",
     "hooks.PreToolUse"
   ],
@@ -375,7 +403,7 @@ const REMOVED_MANIFEST = {
   },
   claudeJsonKeys: [] as Array<string>,
   /** Home-relative artifacts the kit installed outside ~/.claude. */
-  homeFiles: [".local/bin/session-relay"],
+  homeFiles: [".local/bin/effect-solutions", ".local/bin/session-relay"],
   runtimeReady: {
     hooks: ["notify.sh"],
     files: ["statusline.sh", "fetch-usage.sh"],

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

@@ -9,6 +9,7 @@ import { syncCodexEffort, syncCodexModel, replaceTopLevelSettingInFile } from ".
 import { p, spawnProcess } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
+import { hostOs } from "./os"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
 
 export async function codexSync(ctx: Ctx): Promise<void> {
@@ -84,10 +85,11 @@ async function ensureBubblewrap(ctx: Ctx): Promise<void> {
 
 function bwrapSupportedOs(ctx: Ctx): boolean {
   const { warn } = ctx.services.logger
-  const pn = ctx.services.platform.name()
-  if (pn === "linux") return true
-  if (pn === "darwin") return false
-  warn("Unknown OS — skipping bubblewrap check; Codex sandbox may not work")
+  const os = hostOs(ctx.services.platform.name())
+  if (os.supportsBubblewrap) return true
+  if (os.id === "unknown") {
+    warn("Unknown OS — skipping bubblewrap check; Codex sandbox may not work")
+  }
   return false
 }
 
@@ -202,7 +204,10 @@ function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
 
 const PLUGIN_TABLE_HEADER = /^\[plugins\."([^"]+)"\][ \t]*$/
 /** Plugin ids the kit retired; their deployed tables are stripped on every sync. */
-const RETIRED_PLUGIN_IDS: Readonly<Record<string, true>> = { "session-relay@docks": true }
+const RETIRED_PLUGIN_IDS: Readonly<Record<string, true>> = {
+  "effect-kit@docks": true,
+  "session-relay@docks": true
+}
 
 /** codex::remove_retired_plugin_tables — drop [plugins."<id>"] blocks for retired ids. */
 export function removeRetiredPluginTablesText(content: string): string {