docks-kit 0.15.1 → 0.15.2

package/AGENTS.md

@@ -91,9 +91,43 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 
 ## Plans
 
-Use direct implementation for one clear reversible low-risk local diff with one bounded acceptance path; it creates no plan, reviewer, or automatic commit. Canonical plans live in `docs/plans/active/`; lifecycle is frontmatter, and `docs/plans/finished/` is terminal. Exactly three skills own the workflow: `plan-workspace` maintains the workspace, main-context `plan-manager` owns classify → draft/review/one repair → start → implement/delegate → observed acceptance → finish/archive, and internal `plan-reviewer` returns read-only `PlanReviewV1` evidence from one immutable bundle. Only the reviewer has wrappers.
+Use direct implementation for one clear, reversible, low-risk local diff with one
+bounded acceptance path; it creates no tracked plan, reviewer, or automatic
+commit. Use a canonical plan for explicit planning, multi-commit or
+cross-repository work, cold handoff, an unresolved decision, a cross-subsystem or
+public-contract change, security-sensitive or destructive work, or any
+non-`local` effect.
 
-The current record is one compact-JCS `Plan-run: PlanRunV1` line. Schemas 1–6 are historical validation/quarantine only. Every Steps row has `Effect: local|probe|production_access|publish|push|release|deploy`; a persisted requested effect is never live authority. The complete transaction, review-budget, checkpoint, legacy-quarantine, and external-authority contract lives in `docs/plans/AGENTS.md`; `docs/plans/CLAUDE.md` contains only `@AGENTS.md`.
+<constraint>
+Canonical plans live in `docs/plans/active/`; status is frontmatter and
+`docs/plans/finished/` is terminal. Exactly three skills own the workflow:
+`plan-workspace` maintains the workspace; main-context `plan-manager` runs six
+phases — decide, draft, research, one plan review, implement, code review — and
+archives; internal `plan-reviewer` returns a readable pre-implementation verdict.
+Two read-only reviewer wrappers ship, `plan-reviewer` and `code-reviewer`, and
+nothing else in the lifecycle has a wrapper.
+</constraint>
+
+The record is markdown only: `plan_contract: v2` frontmatter plus eight `##`
+sections — `## Goal`, `## Research`, `## Steps`, `## Acceptance`,
+`## Do not touch`, `## Open questions`, `## Review`, `## Verification Results`.
+There are no hashes, permits, run identities, locks, bundles, or `v2`/`vN` plan
+files, and the `plan.mjs` shipped inside the installed `plan-lifecycle` plugin
+is the only lifecycle tool. This lifecycle creates zero commits and never
+pushes; commit when the user asks, under `docks:commit-discipline`.
+
+Every Steps row carries an `Effect` of exactly
+`local|probe|production_access|publish|push|release|deploy`. A step whose
+`Effect` is not `local` requires an in-session `ask` confirmation immediately
+before it runs; when `ask` is unavailable the step is set `blocked` with
+`blocked_reason` naming the unconfirmed effect. Persisted effects record intent
+only.
+
+A plan carrying a `Plan-run:` line is a v1 plan: render it, never parse or
+migrate it, and finish it by hand by moving the file byte-unchanged to
+`docs/plans/finished/<YYYY-MM-DD>-<slug>.md` with a `## Retirement` section
+appended. The complete contract lives in `docs/plans/AGENTS.md`;
+`docs/plans/CLAUDE.md` contains only `@AGENTS.md`.
 
 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

@@ -134,7 +134,7 @@ Details: `docks-kit docs platforms`.
 Tagging `cli-v*` builds four standalone binaries (Linux x64/arm64 and macOS
 x64/arm64) plus `SHA256SUMS` and attaches them to the GitHub release; npm
 publishes the exact package tarball through trusted publishing with OIDC provenance.
-Package `docks-kit` 0.15.1 bundles the CLI + generated payload, so npm releases
+Package `docks-kit` 0.15.2 bundles the CLI + generated payload, so npm releases
 are versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs

package/cli/src/commands/model.ts

@@ -32,6 +32,9 @@ export const modelCommand = Command.make(
       const dry = [...(config.dryRun ? ["--dry-run"] : []), ...(config.verbose ? ["--verbose"] : [])]
 
       if (Option.isSome(config.value)) {
+        if (config.value.value.trim() === "") {
+          return yield* bail("Model value must not be empty or blank")
+        }
         return yield* engine(["model", t, config.value.value, ...dry])
       }
 

package/cli/src/commands/models.ts

@@ -18,6 +18,11 @@ const renderTool = (t: Tool) =>
     for (const m of catalog.models) {
       yield* Console.log(`  ${m.id.padEnd(28)} ${m.kind.padEnd(6)} ${m.note ?? ""}`)
     }
+    yield* Console.log(
+      t === "claude"
+        ? "  (full claude-* model IDs outside the catalog are accepted with a warning)"
+        : "  (well-formed IDs outside the catalog are accepted with a warning)"
+    )
     yield* Console.log("")
   })
 
@@ -37,9 +42,6 @@ export const modelsCommand = Command.make("models", { tool, json }, (config) =>
     for (const t of tools) {
       yield* renderTool(t)
     }
-    yield* Console.log(
-      "Catalog: SoT/models.json (research-verified). Well-formed IDs outside it apply with a warning."
-    )
   })
 ).pipe(
   Command.withDescription("List kit-verified Claude and Codex models (SoT/models.json).")

package/cli/src/commands/status.ts

@@ -1,6 +1,6 @@
 import { Command, Flag } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
-import { engineCapture } from "../engine"
+import { engineCapture, type EngineCaptureError } from "../engine"
 import {
   deployedClaudeSettings,
   deployedCodexModel,
@@ -22,55 +22,168 @@ interface Drift {
   readonly drifted: boolean
 }
 
-const gatherDrift = (): Array<Drift> => {
+type ClaudeDeployment =
+  | { readonly state: "absent" }
+  | { readonly state: "valid"; readonly settings: Record<string, unknown> }
+  | { readonly state: "malformed"; readonly diagnostic: string }
+
+const captureToolchainStatus = () =>
+  engineCapture(["toolchain", "check"]).pipe(
+    Effect.map((table) => ({ state: "valid" as const, table })),
+    Effect.catch((error: EngineCaptureError) =>
+      Effect.succeed({
+        state: "failed" as const,
+        table: "",
+        diagnostic: error.diagnostic,
+        exitCode: error.code
+      })
+    )
+  )
+
+const readClaudeDeployment = (): ClaudeDeployment => {
+  try {
+    const settings: unknown = deployedClaudeSettings()
+    if (settings === undefined) return { state: "absent" }
+    if (settings === null || typeof settings !== "object" || Array.isArray(settings)) {
+      return {
+        state: "malformed",
+        diagnostic: "deployed Claude settings must contain a JSON object"
+      }
+    }
+    return { state: "valid", settings: settings as Record<string, unknown> }
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return {
+      state: "malformed",
+      diagnostic: `deployed Claude settings contain invalid JSON: ${detail}`
+    }
+  }
+}
+
+const gatherDrift = (): {
+  readonly drift: Array<Drift>
+  readonly claudeDeployment: ClaudeDeployment
+} => {
   const sot = sotClaudeSettings()
-  const dep = deployedClaudeSettings() ?? {}
+  const claudeDeployment = readClaudeDeployment()
   const row = (setting: string, deployed: unknown, sotVal: unknown): Drift => {
     const d = String(deployed ?? "(unset)")
     const s = String(sotVal ?? "(unset)")
     return { setting, deployed: d, sot: s, drifted: d !== s }
   }
-  return [
-    row("claude.model", dep.model, sot.model),
-    row("claude.effortLevel", dep.effortLevel, sot.effortLevel),
-    row(
-      "claude.compactWindow",
-      dep.env?.CLAUDE_CODE_AUTO_COMPACT_WINDOW,
-      sot.env?.CLAUDE_CODE_AUTO_COMPACT_WINDOW
-    ),
-    row("codex.model", deployedCodexModel(), sotCodexModel())
-  ]
+  const codex = row("codex.model", deployedCodexModel(), sotCodexModel())
+  if (claudeDeployment.state === "absent") {
+    return {
+      claudeDeployment,
+      drift: [
+        { setting: "claude.settings", deployed: "(absent)", sot: "present", drifted: true },
+        codex
+      ]
+    }
+  }
+  if (claudeDeployment.state === "malformed") {
+    return {
+      claudeDeployment,
+      drift: [
+        { setting: "claude.settings", deployed: "(malformed)", sot: "present", drifted: true },
+        codex
+      ]
+    }
+  }
+
+  const dep = claudeDeployment.settings
+  const env =
+    dep.env !== null && typeof dep.env === "object" && !Array.isArray(dep.env)
+      ? (dep.env as Record<string, unknown>)
+      : {}
+  return {
+    claudeDeployment,
+    drift: [
+      row("claude.model", dep.model, sot.model),
+      row("claude.effortLevel", dep.effortLevel, sot.effortLevel),
+      row(
+        "claude.compactWindow",
+        env.CLAUDE_CODE_AUTO_COMPACT_WINDOW,
+        sot.env?.CLAUDE_CODE_AUTO_COMPACT_WINDOW
+      ),
+      codex
+    ]
+  }
 }
 
 export const statusCommand = Command.make("status", { json }, (config) =>
   Effect.gen(function* () {
-    const drift = gatherDrift()
+    const { drift, claudeDeployment } = gatherDrift()
     const plugins = pluginsView()
     const skills = skillsView()
-    const toolchainTable = yield* engineCapture(["toolchain", "check"])
+    const toolchain = yield* captureToolchainStatus()
+    const diagnostics = new Array<{ source: string; message: string; exitCode: number }>()
+    if (claudeDeployment.state === "malformed") {
+      diagnostics.push({
+        source: "claude.settings",
+        message: claudeDeployment.diagnostic,
+        exitCode: 1
+      })
+    }
+    if (toolchain.state === "failed") {
+      diagnostics.push({
+        source: "toolchain",
+        message: toolchain.diagnostic ?? "toolchain capture failed",
+        exitCode: toolchain.exitCode ?? 1
+      })
+    }
 
     if (config.json) {
-      return yield* Console.log(
-        JSON.stringify({ kitHome: kitHome(), drift, plugins, skills, toolchainTable }, null, 2)
+      const deployment =
+        claudeDeployment.state === "malformed"
+          ? { claude: { state: claudeDeployment.state, diagnostic: claudeDeployment.diagnostic } }
+          : { claude: { state: claudeDeployment.state } }
+      yield* Console.log(
+        JSON.stringify(
+          {
+            kitHome: kitHome(),
+            deployment,
+            drift,
+            plugins,
+            skills,
+            toolchain,
+            diagnostics
+          },
+          null,
+          2
+        )
+      )
+    } else {
+      yield* Console.log(`Kit home: ${kitHome()}\n`)
+      yield* Console.log("Deployed vs SoT (drift is expected for deploy-time modifiers):")
+      for (const d of drift) {
+        const mark = d.drifted ? "≠" : "="
+        yield* Console.log(`  ${d.setting.padEnd(22)} deployed=${d.deployed}  ${mark}  SoT=${d.sot}`)
+      }
+      if (claudeDeployment.state === "malformed") {
+        yield* Console.log(`  ERROR claude.settings: ${claudeDeployment.diagnostic}`)
+      }
+      yield* Console.log("\nToolchain:")
+      if (toolchain.state === "failed") {
+        yield* Console.log(`  ERROR: ${toolchain.diagnostic}`)
+      } else {
+        yield* Console.log(toolchain.table.trimEnd())
+      }
+      const enabled = plugins.filter((p) => p.sot === "true").length
+      yield* Console.log(
+        `\nPlugins: ${plugins.length} known (${enabled} SoT-enabled) — details: docks-kit plugins list`
+      )
+      const installed = skills.filter((s) => s.installed).length
+      yield* Console.log(
+        `Skills:  ${skills.length} known (${installed} installed) — details: docks-kit skills list`
       )
     }
 
-    yield* Console.log(`Kit home: ${kitHome()}\n`)
-    yield* Console.log("Deployed vs SoT (drift is expected for deploy-time modifiers):")
-    for (const d of drift) {
-      const mark = d.drifted ? "≠" : "="
-      yield* Console.log(`  ${d.setting.padEnd(22)} deployed=${d.deployed}  ${mark}  SoT=${d.sot}`)
+    if (diagnostics.length > 0) {
+      yield* Effect.sync(() => {
+        process.exitCode = diagnostics[0]?.exitCode ?? 1
+      })
     }
-    yield* Console.log("\nToolchain:")
-    yield* Console.log(toolchainTable.trimEnd())
-    const enabled = plugins.filter((p) => p.sot === "true").length
-    yield* Console.log(
-      `\nPlugins: ${plugins.length} known (${enabled} SoT-enabled) — details: docks-kit plugins list`
-    )
-    const installed = skills.filter((s) => s.installed).length
-    yield* Console.log(
-      `Skills:  ${skills.length} known (${installed} installed) — details: docks-kit skills list`
-    )
   })
 ).pipe(
   Command.withDescription(

package/cli/src/commands/sync.ts

@@ -138,6 +138,10 @@ export const syncCommand = Command.make(
       Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`))
       Option.map(config.codexEffort, (level) => args.push(`--codex-effort=${level}`))
       for (const occurrence of config.claudePlugin) {
+        if (occurrence.trim() === "") {
+          args.push("--claude-plugin=")
+          continue
+        }
         occurrence
           .split(",")
           .map((p) => p.trim())

package/cli/src/commands/update.ts

@@ -42,11 +42,99 @@ const readPackageVersion = (home: string): string => {
   }
 }
 
+export type PackageManager = "bun" | "npm"
+
+interface PackageRootCapture {
+  readonly status: number | null
+  readonly stdout: string
+  readonly error?: Error
+}
+
+type CapturePackageRoot = (
+  command: string,
+  args: ReadonlyArray<string>
+) => PackageRootCapture
+
+const capturePackageRoot: CapturePackageRoot = (command, args) => {
+  const res = spawnSync(command, [...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  })
+  return {
+    status: res.status,
+    stdout: res.stdout ?? "",
+    ...(res.error === undefined ? {} : { error: res.error })
+  }
+}
+
+export const packageManagerForHome = (
+  home: string,
+  environment: NodeJS.ProcessEnv = process.env
+): PackageManager => {
+  const underEnvironmentRoot = (name: "BUN_INSTALL_GLOBAL_DIR" | "BUN_INSTALL"): boolean => {
+    const root = environment[name]?.trim()
+    return root !== undefined && root !== "" && (home === root || home.startsWith(`${root}/`))
+  }
+  return home.includes("/.bun/") ||
+    underEnvironmentRoot("BUN_INSTALL_GLOBAL_DIR") ||
+    underEnvironmentRoot("BUN_INSTALL")
+    ? "bun"
+    : "npm"
+}
+
+export type GlobalPackageHome =
+  | { readonly ok: true; readonly home: string }
+  | { readonly ok: false; readonly diagnostic: string }
+
+export const resolveGlobalPackageHome = (
+  manager: PackageManager,
+  capture: CapturePackageRoot = capturePackageRoot
+): GlobalPackageHome => {
+  const commandArgs = manager === "bun" ? ["pm", "-g", "ls"] : ["root", "-g"]
+  const result = capture(manager, commandArgs)
+  if (result.error !== undefined || result.status !== 0) {
+    const detail =
+      result.error !== undefined
+        ? result.error.message
+        : `exit ${result.status ?? "without status"}`
+    return {
+      ok: false,
+      diagnostic: `${manager} ${commandArgs.join(" ")} failed: ${detail}`
+    }
+  }
+
+  if (manager === "npm") {
+    const root = result.stdout.trim()
+    return root === ""
+      ? { ok: false, diagnostic: "npm root -g failed: empty output" }
+      : { ok: true, home: join(root, "docks-kit") }
+  }
+
+  const globalHeader = result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => / node_modules(?: \(\d+\))?$/.test(line))
+  const globalDir =
+    globalHeader === undefined
+      ? undefined
+      : /^(.*) 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") }
+}
+
 export const packageUpdateResult = (
   before: string,
-  after: string
+  after: string,
+  samePackageRoot = true
 ): { alreadyCurrent: boolean; message: string } => {
   if (before === "" || after === "") return { alreadyCurrent: false, message: "" }
+  if (!samePackageRoot) {
+    return {
+      alreadyCurrent: false,
+      message: `Installed ${after} in the selected global package root.`
+    }
+  }
   if (before === after) {
     return { alreadyCurrent: true, message: `Already at the latest version (${after}).` }
   }
@@ -99,33 +187,39 @@ const updateCheckout = (home: string, skipSync: boolean) =>
 
 const updatePackage = (home: string, skipSync: boolean) =>
   Effect.gen(function* () {
-    // Bun's global dir is configurable (BUN_INSTALL_GLOBAL_DIR / BUN_INSTALL),
-    // so the ~/.bun path shape alone under-detects Bun installs.
-    const underEnvDir = (v: string): boolean => {
-      const dir = process.env[v]
-      return dir !== undefined && dir !== "" && home.startsWith(dir)
-    }
-    const viaBun =
-      home.includes("/.bun/") ||
-      home.includes("\\.bun\\") ||
-      underEnvDir("BUN_INSTALL_GLOBAL_DIR") ||
-      underEnvDir("BUN_INSTALL")
+    const manager = packageManagerForHome(home)
     const beforeVersion = readPackageVersion(home)
-    const res = viaBun
-      ? spawnSync("bun", ["add", "-g", "docks-kit@latest"], { stdio: "inherit" })
-      : spawnSync("npm", ["install", "-g", "docks-kit@latest"], { stdio: "inherit" })
+    const res =
+      manager === "bun"
+        ? spawnSync("bun", ["add", "-g", "docks-kit@latest"], { stdio: "inherit" })
+        : spawnSync("npm", ["install", "-g", "docks-kit@latest"], { stdio: "inherit" })
     if (res.error !== undefined || res.status !== 0) {
-      return yield* bail(`global package update failed (${viaBun ? "bun add -g" : "npm install -g"} docks-kit@latest)`, 1)
+      return yield* bail(
+        `global package update failed (${manager === "bun" ? "bun add -g" : "npm install -g"} docks-kit@latest)`,
+        1
+      )
     }
 
-    const result = packageUpdateResult(beforeVersion, readPackageVersion(home))
+    const updated = resolveGlobalPackageHome(manager)
+    if (!updated.ok) {
+      return yield* bail(
+        `global package update completed, but the updated package root could not be resolved: ${updated.diagnostic}`,
+        1
+      )
+    }
+    const afterVersion = readPackageVersion(updated.home)
+    if (afterVersion === "") {
+      return yield* bail(
+        `global package update completed, but ${join(updated.home, "package.json")} has no readable version`,
+        1
+      )
+    }
+    const result = packageUpdateResult(beforeVersion, afterVersion, home === updated.home)
     if (result.message !== "") yield* Console.log(result.message)
     if (result.alreadyCurrent) return
     if (skipSync) return yield* Console.log("Kit updated. Run: docks-kit sync")
     yield* Console.log("Kit updated - running sync with the new version...")
-    // Chain through the package dir just updated (global installs update in
-    // place) — a bare `docks-kit` PATH lookup could hit a different shim.
-    return yield* chainSync(process.execPath, updateSyncArgs(home))
+    return yield* chainSync(process.execPath, updateSyncArgs(updated.home))
   })
 
 export const updateCommand = Command.make("update", { noSync }, (config) =>

package/cli/src/efforts.ts

@@ -1,4 +1,4 @@
-import { sotClaudeSettings, type Tool } from "./manifests"
+import { sotClaudeSettings, topLevelTomlString, type Tool } from "./manifests"
 import { payloadText } from "./payload"
 
 export const CLAUDE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh"] as const
@@ -53,12 +53,12 @@ export function validateEffortDefault(tool: Tool, value: unknown): string {
   return value
 }
 
-function codexSotEffort(): string | undefined {
-  return payloadText("SoT/.codex/config.toml").match(/^model_reasoning_effort\s*=\s*"([^"]+)"/m)?.[1]
-}
 
 export function sotEffort(tool: Tool): string {
-  const value = tool === "claude" ? sotClaudeSettings().effortLevel : codexSotEffort()
+  const value =
+    tool === "claude"
+      ? sotClaudeSettings().effortLevel
+      : topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model_reasoning_effort")
   return validateEffortDefault(tool, value)
 }
 

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

@@ -153,7 +153,7 @@ active logger binding.
 | `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, 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.ts` | platform capability seam — host reader and injected platform normalization (`rawPlatform`, `platformName`) |
 | `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

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

@@ -1,15 +1,17 @@
-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 { 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 {
   const root = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
@@ -18,11 +20,26 @@ function predictedExecutable(ctx: Ctx): string {
   return p(root, "bin", "bun")
 }
 
-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" })
+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<BunInstallResult> {
+  const options: AsyncProcessOptions = { stdio: ["ignore", "ignore", "pipe"] }
+  const download = await spawnProcess("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], 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)
+  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> {
@@ -52,11 +69,20 @@ async function runBunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunR
     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-"))
+  const installer = p(temporaryDir, "install.sh")
+  let result: BunInstallResult
   try {
-    await installBun(pin, installer)
+    result = await installBun(pin, installer)
   } 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/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)