docks-kit 0.15.0 → 0.15.2

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

@@ -59,14 +59,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)
@@ -153,8 +152,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 +186,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 +292,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) {
@@ -536,7 +537,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 +659,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 +677,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 +693,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 +709,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 +843,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 +859,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 +877,7 @@ async function syncLspServers(ctx: Ctx): Promise<void> {
     }
     return
   }
+  if (missing.length === 0) return
 
   const specs = missing.join(" ")
   if (ctx.dryRun) {

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

@@ -70,7 +70,10 @@ async function ensureBubblewrap(ctx: Ctx): Promise<void> {
     return
   }
 
-  if ((await spawnProcess("unshare", ["-Ur", "true"], { stdio: "ignore" })).exitCode === 0) {
+  const namespaceProbe = await spawnProcess("unshare", ["-Ur", "true"], { stdio: "ignore" })
+  if (namespaceProbe.error !== undefined) {
+    warn(`Could not run unshare to check user namespaces: ${namespaceProbe.error.message}`)
+  } else if (namespaceProbe.exitCode === 0) {
     change(`bubblewrap installed and functional (${await ctx.services.deps.version("bwrap")})`)
   } else {
     warn(
@@ -100,10 +103,14 @@ function bwrapDetectPmInstallCmd(ctx: Ctx): string {
 
 function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  const sotConfig = payloadDisplayPath("SoT/.codex/config.toml", ctx.repoDir)
+  const sotConfig = payloadDisplayPath("SoT/.codex/config.toml")
 
   if (ctx.dryRun) {
-    echo(`[dry-run] merge ${sotConfig} -> ${userConfig}`)
+    if (existsSync(userConfig)) {
+      echo(`[dry-run] merge ${sotConfig} -> ${userConfig}`)
+    } else {
+      echo(`[dry-run] install ${sotConfig} -> ${userConfig}`)
+    }
     return
   }
 
@@ -119,7 +126,8 @@ function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string): void {
   // overwrite the recovery copy with already-merged content.
   const before = readFileSync(userConfig, "utf8")
   const staging = `${userConfig}.merge.tmp`
-  writeFileSync(staging, before)
+  // Normalize once before record transforms because CR bytes change table-header identity.
+  writeFileSync(staging, before.replace(/\r\n/g, "\n"))
 
   scrubDeprecatedFeatures(ctx, staging)
   removeRetiredPluginTables(ctx, staging)
@@ -146,15 +154,20 @@ export function scrubDeprecatedFeaturesText(content: string): string {
   let header = ""
   let body = ""
   let keep = false
+  let changed = false
   for (const line of lines) {
     if (inFeatures) {
       if (line.startsWith("[")) {
         inFeatures = false
         if (keep) out += `${header}\n${body}`
+        else changed = true
         out += `${line}\n`
         continue
       }
-      if (/^use_legacy_landlock[ \t]*=/.test(line)) continue
+      if (/^use_legacy_landlock[ \t]*=/.test(line)) {
+        changed = true
+        continue
+      }
       body += `${line}\n`
       if (/[^ \t\f\v\r]/.test(line)) keep = true
       continue
@@ -168,17 +181,21 @@ export function scrubDeprecatedFeaturesText(content: string): string {
     }
     out += `${line}\n`
   }
-  if (inFeatures && keep) out += `${header}\n${body}`
-  return out
+  if (inFeatures) {
+    if (keep) out += `${header}\n${body}`
+    else changed = true
+  }
+  return changed ? out : content
 }
 
 function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
   const { change } = ctx.services.logger
   if (!existsSync(userConfig)) return
   const content = readFileSync(userConfig, "utf8")
-  if (!content.split("\n").some((l) => /^use_legacy_landlock[ \t]*=/.test(l))) return
+  const next = scrubDeprecatedFeaturesText(content)
+  if (next === content) return
 
-  writeFileSync(`${userConfig}.tmp`, scrubDeprecatedFeaturesText(content))
+  writeFileSync(`${userConfig}.tmp`, next)
   renameSync(`${userConfig}.tmp`, userConfig)
   change("Codex: scrubbed deprecated [features].use_legacy_landlock")
 }
@@ -236,38 +253,134 @@ function mergeTopLevelSettings(sotConfigText: string, userConfig: string): void
   }
 }
 
-function mergeTableSettings(sotConfigText: string, userConfig: string): void {
+interface TomlTableHeader {
+  readonly path: string
+}
+
+const TOML_BASIC_ESCAPES: Readonly<Record<string, string>> = {
+  b: "\b",
+  t: "\t",
+  n: "\n",
+  f: "\f",
+  r: "\r",
+  '"': '"',
+  "\\": "\\"
+}
+
+function tomlBasicEscape(line: string, offset: number): { readonly next: number; readonly value: string } | undefined {
+  const escaped = line[offset]
+  const simple = escaped === undefined ? undefined : TOML_BASIC_ESCAPES[escaped]
+  if (simple !== undefined) return { next: offset + 1, value: simple }
+  const digits = escaped === "u" ? 4 : escaped === "U" ? 8 : 0
+  if (digits === 0) return undefined
+  const hex = line.slice(offset + 1, offset + 1 + digits)
+  if (hex.length !== digits || !/^[0-9A-Fa-f]+$/.test(hex)) return undefined
+  const codePoint = Number.parseInt(hex, 16)
+  if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) return undefined
+  return { next: offset + 1 + digits, value: String.fromCodePoint(codePoint) }
+}
+
+/** Decode a table header to the TOML path that determines managed ownership. */
+function tomlTableHeader(line: string): TomlTableHeader | undefined {
+  let offset = 0
+  const skipWhitespace = (): void => {
+    while (line[offset] === " " || line[offset] === "\t") offset++
+  }
+
+  skipWhitespace()
+  if (line[offset] !== "[") return undefined
+  offset++
+  const array = line[offset] === "["
+  if (array) offset++
+
+  const keys: Array<string> = []
+  while (true) {
+    skipWhitespace()
+    const quote = line[offset]
+    let key = ""
+    if (quote === '"' || quote === "'") {
+      offset++
+      let closed = false
+      while (offset < line.length) {
+        const char = line[offset]!
+        if (char === quote) {
+          offset++
+          closed = true
+          break
+        }
+        if (quote === '"' && char === "\\") {
+          const escape = tomlBasicEscape(line, offset + 1)
+          if (escape === undefined) return undefined
+          key += escape.value
+          offset = escape.next
+          continue
+        }
+        if (char === "\n" || char === "\r") return undefined
+        key += char
+        offset++
+      }
+      if (!closed) return undefined
+    } else {
+      const start = offset
+      while (offset < line.length && /[A-Za-z0-9_-]/.test(line[offset]!)) offset++
+      if (offset === start) return undefined
+      key = line.slice(start, offset)
+    }
+    keys.push(key)
+
+    skipWhitespace()
+    if (line[offset] === ".") {
+      offset++
+      continue
+    }
+    if (line[offset] !== "]") return undefined
+    offset++
+    if (array) {
+      if (line[offset] !== "]") return undefined
+      offset++
+    }
+    skipWhitespace()
+    if (offset < line.length && line[offset] !== "#") return undefined
+    return { path: JSON.stringify(keys) }
+  }
+}
+
+function mergeTableSettingsText(sotConfigText: string, userConfigText: string): string {
   const sotLines = sotConfigText.split("\n")
-  for (const tableHeader of sotLines.filter((l) => /^\[[^\]]+\]/.test(l))) {
-    // Extract the SoT block: from the exact header line to (excluding) the
-    // next table header; `$(...)` strips trailing newlines.
-    let printing = false
+  let merged = userConfigText
+  for (let tableOffset = 0; tableOffset < sotLines.length; tableOffset++) {
+    const managedHeader = tomlTableHeader(sotLines[tableOffset]!)
+    if (managedHeader === undefined) continue
+
     const block: Array<string> = []
-    for (const line of sotLines) {
-      if (line === tableHeader) printing = true
-      else if (printing && line.startsWith("[")) break
-      if (printing) block.push(line)
+    for (let blockOffset = tableOffset; blockOffset < sotLines.length; blockOffset++) {
+      const line = sotLines[blockOffset]!
+      if (blockOffset !== tableOffset && tomlTableHeader(line) !== undefined) break
+      block.push(line)
     }
     const tableBlock = block.join("\n").replace(/\n+$/, "")
 
-    // Remove the existing block from the user config…
-    const userLines = readFileSync(userConfig, "utf8").split("\n")
+    const userLines = merged.split("\n")
     if (userLines[userLines.length - 1] === "") userLines.pop()
     let skip = false
     const kept: Array<string> = []
     for (const line of userLines) {
-      if (line === tableHeader) {
-        skip = true
-        continue
+      const header = tomlTableHeader(line)
+      if (header !== undefined) {
+        skip = header.path === managedHeader.path
+        if (skip) continue
       }
-      if (skip && line.startsWith("[")) skip = false
       if (!skip) kept.push(line)
     }
-    // …and append the SoT block (printf '\n'; printf '%s\n' "$block").
-    const next = `${kept.join("\n")}\n\n${tableBlock}\n`
-    writeFileSync(`${userConfig}.tmp`, next)
-    renameSync(`${userConfig}.tmp`, userConfig)
+    merged = `${kept.join("\n")}\n\n${tableBlock}\n`
   }
+  return merged
+}
+
+function mergeTableSettings(sotConfigText: string, userConfig: string): void {
+  const next = mergeTableSettingsText(sotConfigText, readFileSync(userConfig, "utf8"))
+  writeFileSync(`${userConfig}.tmp`, next)
+  renameSync(`${userConfig}.tmp`, userConfig)
 }
 
 // ------------------------------------------------------- rules + agents ----
@@ -276,7 +389,7 @@ function syncRules(ctx: Ctx, sotRules: ReadonlyArray<PayloadPath>, userRulesDir:
   const { change, echo, verbose } = ctx.services.logger
   const firstRule = sotRules[0]
   if (firstRule === undefined) return
-  const firstDisplay = payloadDisplayPath(firstRule, ctx.repoDir)
+  const firstDisplay = payloadDisplayPath(firstRule)
   const sotRulesDir = firstDisplay.slice(0, firstDisplay.lastIndexOf("/"))
 
   if (ctx.dryRun) {
@@ -306,7 +419,7 @@ function syncRules(ctx: Ctx, sotRules: ReadonlyArray<PayloadPath>, userRulesDir:
 
 function syncAgentsMd(ctx: Ctx, sotAgentsMdText: string, userAgentsMd: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  const sotAgentsMd = payloadDisplayPath("SoT/.codex/AGENTS.md", ctx.repoDir)
+  const sotAgentsMd = payloadDisplayPath("SoT/.codex/AGENTS.md")
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotAgentsMd} -> ${userAgentsMd}`)
@@ -326,26 +439,32 @@ function syncAgentsMd(ctx: Ctx, sotAgentsMdText: string, userAgentsMd: string):
 // ---------------------------------------------------------- marketplace ----
 
 function syncMarketplace(ctx: Ctx, sotMarketplaceText: string, userMarketplace: string): void {
-  const { change, echo, err, verbose } = ctx.services.logger
-  const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json", ctx.repoDir)
+  const { change, echo, verbose } = ctx.services.logger
+  const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json")
+  const repo = parseJson(sotMarketplaceText)
+  if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`)
+
+  const userText = existsSync(userMarketplace) ? readFileSync(userMarketplace, "utf8") : undefined
+  const user = userText === undefined ? undefined : parseJson(userText)
+  if (userText !== undefined && user === undefined) {
+    throw new Error(`invalid deployed Codex marketplace JSON: ${userMarketplace}. Fix or delete it.`)
+  }
+  const out = user === undefined ? undefined : jqStringify(mergeMarketplace(repo, user))
 
   if (ctx.dryRun) {
-    echo(`[dry-run] cp ${sotMarketplace} -> ${userMarketplace}`)
+    if (userText === undefined) {
+      echo(`[dry-run] cp ${sotMarketplace} -> ${userMarketplace}`)
+    } else if (out === userText) {
+      verbose("Codex marketplace already in sync")
+    } else {
+      echo(`[dry-run] merge ${sotMarketplace} -> ${userMarketplace} (backup at ${userMarketplace}.bak)`)
+    }
     return
   }
 
   mkdirSync(p(ctx.agentsDir, "plugins"), { recursive: true })
-  const repo = parseJson(sotMarketplaceText)
-  if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`)
-
-  if (existsSync(userMarketplace)) {
-    const user = parseJson(readFileSync(userMarketplace, "utf8"))
-    if (user === undefined) {
-      err(`Skipping marketplace sync: ${userMarketplace} is not valid JSON. Fix or delete it.`)
-      return
-    }
-    const out = jqStringify(mergeMarketplace(repo, user))
-    if (out === readFileSync(userMarketplace, "utf8")) {
+  if (userText !== undefined && out !== undefined) {
+    if (out === userText) {
       verbose("Codex marketplace already in sync")
       return
     }

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

@@ -5,7 +5,7 @@
  * historical record-oriented behavior.
  */
 import { p } from "./exec"
-import { readFileSync, renameSync, writeFileSync } from "node:fs"
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs"
 
 import { resolveEffort } from "../efforts"
 import type { Ctx } from "./index"
@@ -61,17 +61,22 @@ function syncCodexSetting(ctx: Ctx, edit: CodexSettingEdit): void {
   const { change, echo, verbose, warn } = ctx.services.logger
   const userCodexSettings = p(ctx.home, ".codex", "config.toml")
 
-  if (ctx.dryRun) {
-    echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
+  if (!existsSync(userCodexSettings)) {
+    // A dry-run sync already previewed installing the file, so the edit is not skipped.
+    // The `docks-kit model codex <m>` command creates no file, so the skip stands.
+    if (ctx.dryRun && ctx.syncCodex) {
+      echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
+      return
+    }
+    warn(`(${edit.tag}) ${userCodexSettings} missing — skipped`)
     return
   }
 
-  try {
-    readFileSync(userCodexSettings)
-  } catch {
-    warn(`(${edit.tag}) ${userCodexSettings} missing — skipped`)
+  if (ctx.dryRun) {
+    echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
     return
   }
+
   if (replaceTopLevelSettingInFile(userCodexSettings, edit.key, `${edit.key} = "${edit.value}"`)) {
     change(edit.changed)
     ctx.nextStepTriggers.codexRestart = true

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

@@ -107,11 +107,11 @@ const home = (): string => {
   return envHome !== undefined && envHome !== "" ? envHome : homedir()
 }
 
-
-// The resolved path gets persisted into global direct-exec hooks, so a
-// relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
-// break outside the sync working directory.
-
+/**
+ * The resolved path gets persisted into global direct-exec hooks, so a
+ * relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
+ * break outside the sync working directory.
+ */
 const findBun = (exec: ProbeExecutor): { command: string; path: string } | undefined => {
   const onPath = exec.which("bun")
   if (onPath !== "" && isAbsolute(onPath)) {
@@ -141,22 +141,20 @@ const resolveEffectSolutions = (exec: ProbeExecutor): ProbeResult => {
     : { state: "missing" }
 }
 
-const versionBunCommand = (exec: ProbeExecutor): string =>
-  exec.commandExists("bun") ? "bun" : p(home(), ".bun", "bin", "bun")
-
 const versionEffectSolutions = async (exec: ProbeExecutor): Promise<string> => {
-  const bun = versionBunCommand(exec)
-  if (bun !== "bun" && exec.which(bun) === "") return ""
-  const match = /effect-solutions@([0-9][0-9.]*)/.exec(await exec.capture(bun, ["pm", "-g", "ls"]))
+  const bun = findBun(exec)
+  if (bun === undefined) return ""
+  const match = /effect-solutions@([0-9][0-9.]*)/.exec(await exec.capture(bun.command, ["pm", "-g", "ls"]))
   return match?.[1] ?? ""
 }
 
 const locateEffectSolutions = async (exec: ProbeExecutor): Promise<DependencyLocation> => {
   const strictBun = findBun(exec)
   const pathBun = exec.which("bun")
-  const bun = strictBun ?? (pathBun !== "" ? { command: "bun", path: pathBun } : undefined)
-  if (bun === undefined) return { path: "", binDir: "" }
-  const globalBin = await exec.capture(bun.command, ["pm", "-g", "bin"])
+  // This site may accept a relative hit because it does not persist the Bun path.
+  const bunForGlobalBin = strictBun?.command ?? (pathBun !== "" ? "bun" : undefined)
+  if (bunForGlobalBin === undefined) return { path: "", binDir: "" }
+  const globalBin = await exec.capture(bunForGlobalBin, ["pm", "-g", "bin"])
   const path = globalBin !== "" ? p(globalBin, "effect-solutions") : ""
   const resolved = path !== "" && exec.which(path) !== "" ? path : ""
   return { path: resolved, binDir: globalBin }
@@ -233,7 +231,11 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     () => "curl -fsSL https://bun.sh/install | bash",
     {
       resolve: resolveBun,
-      version: (exec) => exec.capture(versionBunCommand(exec), ["--version"]),
+      version: async (exec) => {
+        const bun = findBun(exec)
+        if (bun === undefined) return ""
+        return await exec.capture(bun.command, ["--version"])
+      },
       locate: async (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
     }
   ),