docks-kit 0.15.1 → 0.15.3

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 — the single `process.platform` reader (`platformName`, `isLinux`, shell-rc applicability) |
+| `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

@@ -1,28 +1,47 @@
-import { rmSync } from "node:fs"
+import { mkdtempSync, rmSync } from "node:fs"
 import { tmpdir } from "node:os"
 
-import { p, spawnProcess } from "./exec"
+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 =
   | { readonly kind: "ready"; readonly executable: string }
-  | { readonly kind: "deferred"; readonly reason: "missing-curl" | "install-failed" }
+  | {
+      readonly kind: "deferred"
+      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 =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: "download-failed" | "installer-failed"; readonly detail: string }
+
+function processFailure(result: AsyncProcessResult): string {
+  const details = [result.error?.message, result.stderr.trim()].filter((value): value is string => value !== undefined && value !== "")
+  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<void> {
-  const download = await spawnProcess("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], { stdio: "ignore" })
-  if (download.error === undefined && download.exitCode === 0) {
-    await spawnProcess("bash", [installer, `bun-v${pin}`], { stdio: "ignore" })
+async function installBun(pin: string, directory: string, host: HostOs = hostOs()): Promise<BunInstallResult> {
+  const options: AsyncProcessOptions = { stdio: ["ignore", "ignore", "pipe"] }
+  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(installer.run.command, installer.run.args, options)
+  if (install.error !== undefined || install.exitCode !== 0) {
+    return { ok: false, reason: "installer-failed", detail: processFailure(install) }
   }
+  return { ok: true }
 }
 
 export function bunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunRuntimeState> {
@@ -33,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 }
@@ -47,16 +67,24 @@ 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 installer = p(tmpdir(), `bun-install-${process.pid}.sh`)
+  const temporaryDir = mkdtempSync(p(tmpdir(), "docks-kit-bun-"))
+  let result: BunInstallResult
   try {
-    await installBun(pin, installer)
+    result = await installBun(pin, temporaryDir, host)
   } finally {
-    rmSync(installer, { force: true })
+    rmSync(temporaryDir, { recursive: true, force: true })
+  }
+  if (!result.ok) {
+    const stage = result.reason === "download-failed" ? "installer download" : "installer"
+    services.logger.warn(
+      `Bun ${stage} failed (${result.detail}). Install Bun manually from https://bun.sh/docs/installation, then re-run sync.`
+    )
+    return { kind: "deferred", reason: result.reason }
   }
 
   const installed = await services.deps.path("bun")

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/claudeSettingsModifiers.ts

@@ -4,6 +4,7 @@ import { readFileSync, renameSync, writeFileSync } from "node:fs"
 
 import { resolveEffort } from "../efforts"
 import type { Ctx } from "./index"
+import { ExitError } from "./parseArgs"
 import { isObject, jqStringify, parseJson } from "./jq"
 
 interface ClaudeSettingEdit {
@@ -19,27 +20,44 @@ function syncClaudeSetting(ctx: Ctx, edit: ClaudeSettingEdit): void {
   const { change, echo, err, verbose, warn } = ctx.services.logger
   const userSettings = p(ctx.home, ".claude", "settings.json")
 
-  if (ctx.dryRun) {
-    echo(`[dry-run] (${edit.tag}) ${edit.dryRun} in ${userSettings}`)
-    return
-  }
-
   let text: string
   try {
     text = readFileSync(userSettings, "utf8")
-  } catch {
-    warn(`(${edit.tag}) ${userSettings} missing — skipped`)
-    return
+  } catch (error) {
+    if (error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      // A dry-run sync writes nothing, so an absent file here does not mean the
+      // edit is skipped: the same run already previewed installing the file,
+      // and the real run applies the edit to it. Outside a sync, such as
+      // `docks-kit model claude <m>`, nothing creates the file and the skip
+      // stands.
+      if (ctx.dryRun && ctx.syncClaude) {
+        echo(`[dry-run] (${edit.tag}) ${edit.dryRun} in ${userSettings}`)
+        return
+      }
+      warn(`(${edit.tag}) ${userSettings} missing — skipped`)
+      return
+    }
+    const cause = error instanceof Error ? error.message : String(error)
+    err(`(${edit.tag}) could not read ${userSettings}: ${cause}`)
+    throw new ExitError(1)
   }
   const doc = parseJson(text)
   if (doc === undefined) {
     err(`(${edit.tag}) ${userSettings} is not valid JSON — skipped`)
     return
   }
-  if (isObject(doc)) {
-    if (edit.value === undefined) delete doc[edit.key]
-    else doc[edit.key] = edit.value
+  if (!isObject(doc)) {
+    err(`(${edit.tag}) ${userSettings} must contain a JSON object — aborting`)
+    throw new ExitError(1)
   }
+
+  if (ctx.dryRun) {
+    echo(`[dry-run] (${edit.tag}) ${edit.dryRun} in ${userSettings}`)
+    return
+  }
+
+  if (edit.value === undefined) delete doc[edit.key]
+  else doc[edit.key] = edit.value
   const out = jqStringify(doc)
   if (out === text) {
     verbose(edit.unchanged)

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"
@@ -59,14 +60,13 @@ export async function claudeSync(ctx: Ctx): Promise<ClaudeRuntimeState> {
     template,
     runtime.kind === "ready" ? runtime.paths : undefined
   )
-  const prepared = ctx.dryRun ? undefined : prepareClaudeSettings(ctx, claudeDir, materialized)
+  const prepared = prepareClaudeSettings(ctx, claudeDir, materialized)
 
   syncClaudeRuntime(ctx, runtime)
   syncClaudeMd(ctx, claudeDir)
   if (ctx.dryRun) {
     describeSettingsSync(ctx, claudeDir)
   } else {
-    if (prepared === undefined) throw new Error("Claude settings were not prepared")
     commitClaudeSettings(ctx, prepared)
   }
   syncRemovals(ctx, claudeDir, runtime)
@@ -76,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)
@@ -153,8 +153,9 @@ export function prepareClaudeSettings(ctx: Ctx, claudeDir: string, repo: Json):
 
   const previousBytes = readFileSync(path, "utf8")
   const user = parseJson(previousBytes)
-  if (user === undefined) {
-    ctx.services.logger.err(`Skipping settings sync: ${path} is not valid JSON. Fix it manually or delete it to reinstall.`)
+  if (user === undefined || !isObject(user)) {
+    const reason = user === undefined ? "is not valid JSON" : "must contain a JSON object"
+    ctx.services.logger.err(`Aborting sync: ${path} ${reason}. Fix it manually or delete it to reinstall.`)
     throw new ExitError(1)
   }
   const merged = ctx.reconcile ? reconcileSettings(repo, user) : mergeSettings(repo, user)
@@ -186,7 +187,7 @@ export function commitClaudeSettings(ctx: Ctx, prepared: PreparedClaudeSettings)
 
 function describeSettingsSync(ctx: Ctx, claudeDir: string): void {
   const { echo } = ctx.services.logger
-  const repoSettings = payloadDisplayPath("SoT/.claude/settings.json", ctx.repoDir)
+  const repoSettings = payloadDisplayPath("SoT/.claude/settings.json")
   const userSettings = p(claudeDir, "settings.json")
 
   if (!existsSync(userSettings)) {
@@ -292,11 +293,12 @@ function syncClaudeJson(ctx: Ctx): void {
   if (existsSync(claudeJson)) {
     const before = readFileSync(claudeJson, "utf8")
     const doc = parseJson(before)
-    if (doc === undefined) {
-      err("Skipping ~/.claude.json edit: not valid JSON. Fix or delete it.")
+    if (doc === undefined || !isObject(doc)) {
+      const reason = doc === undefined ? "not valid JSON" : "root must be a JSON object"
+      err(`Skipping ~/.claude.json edit: ${reason}. Fix or delete it.`)
       return
     }
-    const obj = isObject(doc) ? doc : {}
+    const obj = doc
     applyFilter(obj)
     const out = jqStringify(obj)
     if (out === before) {
@@ -319,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 ----
@@ -365,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"
   ],
@@ -374,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"],
@@ -536,7 +565,7 @@ function sortedKeys(obj: Json | undefined): Array<string> {
 }
 
 /** claude::_plugin_user_scope_installed. */
-function pluginUserScopeInstalled(installedPlugins: string, pluginId: string): boolean {
+export function pluginUserScopeInstalled(installedPlugins: string, pluginId: string): boolean {
   const doc = readJsonFile(installedPlugins)
   if (doc === undefined || !isObject(doc) || !isObject(doc["plugins"])) return false
   const rec = (doc["plugins"] as { [k: string]: Json })[pluginId]
@@ -658,14 +687,15 @@ async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (separator > 0) kitMarketplaces.add(pluginId.slice(separator + 1))
   }
 
-  // Pass 3 — refresh the kit-owned marketplaces and plugins unless the update
-  // command selected its install-missing-only fast path.
+  // Pass 3 — refresh the kit-owned marketplaces unless the update command
+  // selected its install-missing-only fast path.
   if (!ctx.skipPluginRefresh) {
     for (const mpName of [...kitMarketplaces].sort(compareCodepoints)) {
       progress(`Refreshing marketplace ${mpName}...`)
       await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
     }
+    // Pass 4 — update the kit-owned installed plugins.
     for (const pluginId of [...kitPluginIds].sort(compareCodepoints)) {
       if (!pluginUserScopeInstalled(installedPlugins, pluginId)) continue
       progress(`Updating plugin ${pluginId}...`)
@@ -675,14 +705,14 @@ async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     }
   }
 
-  // Passes 4 + 5 — prune-gated uninstall + marketplace removal.
+  // Pass 5 — prune-gated user-scope plugin uninstall.
   let removedPl = 0
   let removedMp = 0
-  let f4 = 0
   let f5 = 0
+  let f6 = 0
   if (ctx.prune) {
     for (const pluginId of installedKeys) {
-      if (isObject(sotPlugins) && Object.prototype.hasOwnProperty.call(sotPlugins, pluginId)) continue
+      if (kitPluginIds.has(pluginId)) continue
       if (!pluginUserScopeInstalled(installedPlugins, pluginId)) continue
       progress(`Uninstalling plugin ${pluginId}...`)
       const uninstallResult = await cli(["plugin", "uninstall", "-y", "--scope", "user", pluginId])
@@ -691,15 +721,15 @@ async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
         removedPl++
       } else {
         warn(`Failed to uninstall plugin: ${pluginId}`)
-        f4++
+        f5++
       }
     }
+    // Pass 6 — prune-gated marketplace removal.
     const known = readJsonFile(knownMarketplaces)
     for (const mpName of sortedKeys(known)) {
       if (mpName === "claude-plugins-official") continue
       if (nonUserMarketplaces.has(mpName)) continue
-      const declared = isObject(sotMarketplaces) ? sotMarketplaces[mpName] : undefined
-      if (declared !== undefined && declared !== null && declared !== false) continue
+      if (kitMarketplaces.has(mpName)) continue
       progress(`Removing marketplace ${mpName}...`)
       const removeResult = await cli(["plugin", "marketplace", "remove", mpName])
       clearProgress()
@@ -707,18 +737,18 @@ async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
         removedMp++
       } else {
         warn(`Failed to remove marketplace: ${mpName}`)
-        f5++
+        f6++
       }
     }
   }
 
-  // Pass 6 — re-assert SoT enabled-state in the user settings.
+  // Pass 7 — re-assert SoT enabled-state in the user settings.
   if (await reassertEnabledState(ctx, repoObj, p(claudeDir, "settings.json"))) {
     change("Plugin enable-state re-asserted from SoT in settings.json")
     ctx.nextStepTriggers.claudePlugins = true
   }
 
-  const failed = f1 + f2 + f4 + f5
+  const failed = f1 + f2 + f5 + f6
   if (addedMp > 0 || addedPl > 0 || updatedPl > 0 || removedPl > 0 || removedMp > 0) {
     change(`Plugins synced (marketplaces: +${addedMp} -${removedMp}, plugins: +${addedPl} ~${updatedPl} -${removedPl})`)
     ctx.nextStepTriggers.claudePlugins = true
@@ -841,9 +871,11 @@ async function syncOptionalPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
 
 // ---------------------------------------------------------- LSP servers ----
 
-function lspPkg(ctx: Ctx, tool: string, pkg: string): string {
-  const v = field(ctx, tool, "verified")
-  return v !== "" ? `${pkg}@${v}` : pkg
+function lspPkg(ctx: Ctx, tool: string, pkg: string): string | undefined {
+  const version = field(ctx, tool, "verified")
+  if (version !== "") return `${pkg}@${version}`
+  ctx.services.logger.warn(`Skipping ${pkg} install: ${tool} has no verified version in SoT/toolchain.json`)
+  return undefined
 }
 
 async function syncLspServers(ctx: Ctx): Promise<void> {
@@ -855,14 +887,17 @@ async function syncLspServers(ctx: Ctx): Promise<void> {
   const hasTs = Object.prototype.hasOwnProperty.call(enabled, "typescript-lsp@claude-plugins-official")
   if (!hasPhp && !hasTs) return
 
-  const missing: Array<string> = []
-  if (hasPhp && ctx.services.deps.probe("intelephense").state === "missing") missing.push(lspPkg(ctx, "intelephense", "intelephense"))
-  if (hasTs) {
-    if (ctx.services.deps.probe("typescript-language-server").state === "missing") missing.push(lspPkg(ctx, "typescript-language-server", "typescript-language-server"))
-    if (ctx.services.deps.probe("tsc").state === "missing") missing.push(lspPkg(ctx, "tsc", "typescript"))
-  }
-
-  if (missing.length === 0) {
+  const phpMissing = hasPhp && ctx.services.deps.probe("intelephense").state === "missing"
+  const tsServerMissing = hasTs && ctx.services.deps.probe("typescript-language-server").state === "missing"
+  const tscMissing = hasTs && ctx.services.deps.probe("tsc").state === "missing"
+  const missingToolCount = Number(phpMissing) + Number(tsServerMissing) + Number(tscMissing)
+  const missing = [
+    phpMissing ? lspPkg(ctx, "intelephense", "intelephense") : undefined,
+    tsServerMissing ? lspPkg(ctx, "typescript-language-server", "typescript-language-server") : undefined,
+    tscMissing ? lspPkg(ctx, "tsc", "typescript") : undefined
+  ].filter((spec): spec is string => spec !== undefined)
+
+  if (missingToolCount === 0) {
     if (ctx.dryRun) {
       echo("[dry-run] LSP server binaries present")
     } else {
@@ -870,6 +905,7 @@ async function syncLspServers(ctx: Ctx): Promise<void> {
     }
     return
   }
+  if (missing.length === 0) return
 
   const specs = missing.join(" ")
   if (ctx.dryRun) {