docks-kit 0.16.7 → 0.16.9

package/AGENTS.md

@@ -63,10 +63,10 @@ Codex SoT notes:
 omp SoT notes:
 - `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
 - `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`.
-- `ompSync.ts syncMergedYaml` deep-merges `config.yml` through `mergeOmpConfig`.
+- `ompSync.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards.
 - `cycleOrder` ends with the `fable` role (`modelRoles.fable` = `anthropic/claude-fable-5-1:medium`, `modelTags.fable` visible, `retry.fallbackChains.fable` empty), so the model switcher reaches Fable 5.1 as its fourth stop and never falls back off it. The hidden `switch_fable` role points at the same model and level.
 - `modelRoles.task` is `openai-codex/gpt-6-astra:low`, chosen for 2.60 s TTFT and 4k output tokens per task at cost parity with the previous `gpt-5.6-sol:high`. `task.agentModelOverrides` points four reviewer names at `@task`; only the bundled `reviewer` and `security-reviewer` are discoverable OMP agents, so those two inherit `task`, and the `code-reviewer` and `plan-reviewer` entries are dormant. Artificial Analysis publishes no per-level Astra Coding Agent Index score, so reviewer output is the signal to watch.
-- `SoT/.omp/models.yml` deploys to `~/.omp/agent/models.yml` through the same `mergeOmpConfig` merge as `config.yml`. A user file may carry provider credentials, so whole-file replacement is wrong. It restricts the `gpt-6-astra` effort ladder to `low`, so every Astra subagent runs `low` while `task.maxEffort: high` lets `scout` and `sonic` reach Luna `high` with `effort: hi`. `ompSync.ts syncMergedYaml` owns both YAML deployments. `cli/docs/omp-models.md` records the verification.
+- `SoT/.omp/models.yml` deploys to `~/.omp/agent/models.yml` through `mergeOmpModels`, which keeps every deployed-only key. A user file may carry provider credentials, so whole-file replacement is wrong. It restricts the `gpt-6-astra` effort ladder to `low`, so every Astra subagent runs `low` while `task.maxEffort: high` lets `scout` and `sonic` reach Luna `high` with `effort: hi`. `cli/docs/omp-models.md` records the verification.
 - `SoT/.omp/AGENTS.md` carries the rule `Please remove all mannered prose.` Anthropic's Fable 5.1 prompting guide documents mannered prose as a Fable 5.1 behavior and gives that sentence as its short-version fix: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
 - `cli/docs/omp-models.md` (topic `omp-models`) records the role map rationale and the Artificial Analysis snapshot behind it. Model choices change with published benchmarks, so update that topic in the same commit as a role change.
 - Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope.
@@ -78,6 +78,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 ## Engineering rules
 
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
+- **Failed harness-CLI operations fail the sync.** A kit-managed marketplace or plugin command that exits non-zero is recorded through `failures.ts recordFailure` — it still warns in place, and `index.ts engineSync, failure ledger` lists every entry under `--- Failures ---` after the summary, then returns exit 1. A skip is not a failure: a missing harness CLI, missing git, a missing `SoT/toolchain.json` pin, and an unavailable plugin inventory stay warn-only with exit 0, and `ompSync.ts syncMarketplace, probe guard` returns before spawning so a host without omp never records one. Aggregate roll-up warnings (`N plugin operation(s) failed`) stay warns, because each counted site already records itself.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
 - **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.109` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.11` (inside the `@effect/vitest` peer range `>=4.1.0 <5.0.0`; 4.1.11 fixes GHSA-82fw-gwwq-j7x9). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
 - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.

package/cli/docs/plugins.md

@@ -21,6 +21,17 @@ is absent from user settings.
 5. Re-assert SoT enabled-state (undoes install's enable side effect on
    false-keyed plugins)
 
+## Failed operations fail the sync
+
+A marketplace or plugin command that exits non-zero is warned in place AND
+recorded, then listed under a `--- Failures ---` block after the summary; the
+sync exits 1. A stale plugin therefore no longer looks like a clean sync.
+
+Not a failure: a missing harness CLI, missing git, a missing
+`SoT/toolchain.json` pin, and an unavailable plugin inventory. Those stay
+warn-and-skip with exit 0, so a host without Claude, Codex, or omp installed
+still syncs its deployed config cleanly.
+
 ## Optional opt-ins
 
 Situational plugins are kept OUT of the SoT and opted in per machine:

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

@@ -5,6 +5,7 @@
  */
 import { existsSync, renameSync, writeFileSync } from "node:fs"
 import { p, spawnProcess } from "./exec"
+import { recordFailure } from "./failures"
 import type { Ctx } from "./index"
 import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, readJsonFile, type Json } from "./jq"
 import { field } from "./toolchain"
@@ -95,7 +96,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (marketplaceResult.ok) {
       addedMp++
     } else {
-      warn(`Failed to add marketplace: ${mpName} (${repo})`)
+      recordFailure(ctx, `Failed to add marketplace: ${mpName} (${repo})`)
       f1++
     }
   }
@@ -104,6 +105,8 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   // refreshing each source marketplace once so the install resolves a current snapshot.
   let addedPl = 0
   let f2 = 0
+  let f3 = 0
+  let f4 = 0
   const refreshedMarketplaces = new Set<string>()
   for (const pluginId of sortedKeys(sotPlugins)) {
     if (pluginUserScopeInstalled(installedPlugins, pluginId)) continue
@@ -111,8 +114,12 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     const mpName = separator > 0 ? pluginId.slice(separator + 1) : ""
     if (mpName !== "" && !refreshedMarketplaces.has(mpName)) {
       progress(`Refreshing marketplace ${mpName}...`)
-      await cli(["plugin", "marketplace", "update", mpName])
+      const refreshResult = await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
+      if (!refreshResult.ok) {
+        recordFailure(ctx, `Failed to refresh marketplace: ${mpName}`)
+        f3++
+      }
       refreshedMarketplaces.add(mpName)
     }
     progress(`Installing plugin ${pluginId}...`)
@@ -121,7 +128,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (installResult.ok) {
       addedPl++
     } else {
-      warn(`Failed to install plugin: ${pluginId}`)
+      recordFailure(ctx, `Failed to install plugin: ${pluginId}`)
       f2++
     }
   }
@@ -143,12 +150,21 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   }
 
   // Pass 3 — refresh the kit-owned marketplaces unless the update command
-  // selected its install-missing-only fast path.
+  // selected its install-missing-only fast path. Pass 2 already refreshed the
+  // source marketplace of every plugin it installed, so skip those: a second
+  // fetch seconds later cannot resolve a newer snapshot, and re-running it
+  // would duplicate one failure in the ledger and in the failed-operation count.
   if (!ctx.skipPluginRefresh) {
     for (const mpName of [...kitMarketplaces].sort(compareCodepoints)) {
+      if (refreshedMarketplaces.has(mpName)) continue
       progress(`Refreshing marketplace ${mpName}...`)
-      await cli(["plugin", "marketplace", "update", mpName])
+      const refreshResult = await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
+      refreshedMarketplaces.add(mpName)
+      if (!refreshResult.ok) {
+        recordFailure(ctx, `Failed to refresh marketplace: ${mpName}`)
+        f3++
+      }
     }
     // Pass 4 — update the kit-owned installed plugins.
     for (const pluginId of [...kitPluginIds].sort(compareCodepoints)) {
@@ -156,7 +172,12 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       progress(`Updating plugin ${pluginId}...`)
       const updateResult = await cli(["plugin", "update", pluginId, "--scope", "user"])
       clearProgress()
-      if (updateResult.out.includes("Successfully updated")) updatedPl++
+      if (!updateResult.ok) {
+        recordFailure(ctx, `Failed to update plugin: ${pluginId}`)
+        f4++
+      } else if (updateResult.out.includes("Successfully updated")) {
+        updatedPl++
+      }
     }
   }
 
@@ -175,7 +196,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       if (uninstallResult.ok) {
         removedPl++
       } else {
-        warn(`Failed to uninstall plugin: ${pluginId}`)
+        recordFailure(ctx, `Failed to uninstall plugin: ${pluginId}`)
         f5++
       }
     }
@@ -191,7 +212,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       if (removeResult.ok) {
         removedMp++
       } else {
-        warn(`Failed to remove marketplace: ${mpName}`)
+        recordFailure(ctx, `Failed to remove marketplace: ${mpName}`)
         f6++
       }
     }
@@ -203,7 +224,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     ctx.nextStepTriggers.claudePlugins = true
   }
 
-  const failed = f1 + f2 + f5 + f6
+  const failed = f1 + f2 + f3 + f4 + 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
@@ -229,7 +250,7 @@ async function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, us
     if ((await cli(["plugin", "disable", pluginId])).ok) {
       cliDisabled = true
     } else {
-      warn(`Failed to disable SoT-false plugin: ${pluginId} (will retry next sync)`)
+      recordFailure(ctx, `Failed to disable SoT-false plugin: ${pluginId} (will retry next sync)`)
     }
   }
 
@@ -250,7 +271,7 @@ async function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, us
 // ------------------------------------------------------ optional plugins ----
 
 async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, marketplaceRepo: string): Promise<boolean> {
-  const { change, clearProgress, progress, verbose, warn } = ctx.services.logger
+  const { change, clearProgress, progress, verbose } = ctx.services.logger
   const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json")
   const knownMarketplaces = p(claudeDir, "plugins", "known_marketplaces.json")
   const mpName = pluginId.slice(pluginId.lastIndexOf("@") + 1)
@@ -261,7 +282,7 @@ async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: strin
     const has = known !== undefined && isObject(known) && known[mpName] !== undefined && known[mpName] !== null && known[mpName] !== false
     if (!has) {
       if (!(await cli(["plugin", "marketplace", "add", marketplaceRepo])).ok) {
-        warn(`Failed to add marketplace ${marketplaceRepo} for ${pluginId}`)
+        recordFailure(ctx, `Failed to add marketplace ${marketplaceRepo} for ${pluginId}`)
         return false
       }
       marketplaceAdded = true
@@ -275,7 +296,7 @@ async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: strin
     clearProgress()
     if (!installResult.ok) {
       if (marketplaceAdded) change(`Optional plugin ${pluginId}: marketplace added (install failed — will retry next sync)`)
-      warn(`Failed to install optional plugin ${pluginId}`)
+      recordFailure(ctx, `Failed to install optional plugin ${pluginId}`)
       return marketplaceAdded
     }
   }
@@ -288,7 +309,7 @@ async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: strin
 
   if (!(await cli(["plugin", "enable", pluginId])).ok) {
     if (marketplaceAdded || !wasInstalled) change(`Optional plugin ${pluginId}: installed (enable failed — will retry next sync)`)
-    warn(`Failed to enable optional plugin ${pluginId}`)
+    recordFailure(ctx, `Failed to enable optional plugin ${pluginId}`)
     return marketplaceAdded || !wasInstalled
   }
   const changed = marketplaceAdded || !wasInstalled || !wasEnabled

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

@@ -7,6 +7,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync,
 
 import { mergeTableSettings, mergeTopLevelSettings, syncCodexEffort, syncCodexModel } from "./codexToml"
 import { p, spawnProcess } from "./exec"
+import { recordFailure } from "./failures"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
 import { hostOs } from "./os"
@@ -466,7 +467,7 @@ function marketplaceSource(marketplace: string, configFile: string): string {
 }
 
 async function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): Promise<void> {
-  const { change, echo, warn } = ctx.services.logger
+  const { change, echo } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] remove legacy configured Codex Docks marketplace when personal marketplace is deployed")
     return
@@ -481,7 +482,7 @@ async function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): Promi
     change("Removed legacy configured Codex Docks marketplace; using personal marketplace file")
     ctx.nextStepTriggers.codexRestart = true
   } else {
-    warn("Failed to remove legacy configured Codex Docks marketplace")
+    recordFailure(ctx, "Failed to remove legacy configured Codex Docks marketplace")
   }
 }
 
@@ -592,13 +593,15 @@ async function syncPlugins(ctx: Ctx, sotConfigText: string): Promise<void> {
     if (res.error === undefined && res.exitCode === 0) {
       refreshed++
     } else if (addOut.includes("could not find a Codex CLI binary")) {
-      warn(
+      recordFailure(
+        ctx,
         `Codex plugin refresh hit a stale launcher/wrapper on PATH - install current standalone Codex with: ${standaloneInstallCommand(ctx)}`
       )
       failed++
     } else {
       const failureLine = addOut.split("\n")[0] ?? ""
-      warn(
+      recordFailure(
+        ctx,
         `Codex plugin refresh failed for ${pluginId}: ${failureLine !== "" ? failureLine : "unknown error"}; run manually: codex plugin add ${pluginId}`
       )
       failed++

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

@@ -0,0 +1,16 @@
+/**
+ * Failure ledger for harness-CLI operations. A kit-managed marketplace or
+ * plugin command that exits non-zero is recorded here so engineSync can list
+ * it and exit non-zero instead of reporting a clean sync.
+ */
+import type { Ctx } from "./index"
+
+/**
+ * Record a failed harness-CLI operation. The warning still prints immediately so
+ * position in the output is preserved; the recorded message also lets engineSync
+ * list the failure in the summary and exit non-zero.
+ */
+export function recordFailure(ctx: Ctx, message: string): void {
+  ctx.failures.push(message)
+  ctx.services.logger.warn(message)
+}

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

@@ -117,6 +117,8 @@ export interface Ctx {
     skillsRestart: boolean
     ompRestart: boolean
   }
+  /** Harness-CLI operations that failed this run; a non-empty list fails the sync. */
+  readonly failures: Array<string>
 }
 
 /** Globals default from env using the historical ${VAR:-default} contract. */
@@ -170,7 +172,8 @@ function makeCtx(services: EngineServices): Ctx {
       codexRestart: false,
       skillsRestart: false,
       ompRestart: false
-    }
+    },
+    failures: []
   }
 }
 
@@ -291,6 +294,12 @@ async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number
     echo("")
     for (const line of advice) echo(line)
   }
+  if (ctx.failures.length > 0) {
+    echo("")
+    echo("--- Failures ---")
+    for (const failure of ctx.failures) echo(`- ${failure}`)
+    return 1
+  }
   return 0
 }
 

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

@@ -1,7 +1,8 @@
 /**
- * EngineNative `sync omp` pipeline. config.yml and models.yml merge through
- * mergeOmpConfig to preserve user-only keys. Paths come from ompPaths because
- * profiles, PI_CONFIG_DIR, PI_CODING_AGENT_DIR, and XDG roots each move them.
+ * EngineNative `sync omp` pipeline. config.yml merges through mergeOmpConfig
+ * and models.yml through mergeOmpModels. Both preserve user-only keys.
+ * Paths come from ompPaths because profiles, PI_CONFIG_DIR,
+ * PI_CODING_AGENT_DIR, and XDG roots each move them.
  * Resolution stays within the environment and filesystem probes so no omp
  * subcommand runs under ctx.dryRun.
  */
@@ -11,10 +12,11 @@ import { basename, isAbsolute, resolve } from "node:path"
 import { payloadDisplayPath, payloadText, type PayloadPath } from "../payload"
 import { bunBootstrap } from "./bun"
 import { p, spawnProcess, type AsyncProcessResult } from "./exec"
+import { recordFailure } from "./failures"
 import type { Ctx } from "./index"
 import { isObject, parseJson } from "./jq"
 import { ompPaths } from "./ompPaths"
-import { mergeOmpConfig } from "./ompYaml"
+import { mergeOmpConfig, mergeOmpModels } from "./ompYaml"
 import { field } from "./toolchain"
 
 const MARKETPLACE_NAME = "docks"
@@ -35,8 +37,8 @@ export async function ompSync(ctx: Ctx): Promise<OmpState> {
 
   syncWholeFile(ctx, "SoT/.omp/AGENTS.md", p(agentDir, "AGENTS.md"), "omp AGENTS.md already in sync", "omp AGENTS.md synced")
   syncWholeFile(ctx, "SoT/.omp/mcp.json", p(agentDir, "mcp.json"), "omp mcp.json already in sync", "omp mcp.json synced")
-  syncMergedYaml(ctx, "SoT/.omp/config.yml", p(agentDir, "config.yml"))
-  syncMergedYaml(ctx, "SoT/.omp/models.yml", p(agentDir, "models.yml"))
+  syncMergedYaml(ctx, "SoT/.omp/config.yml", p(agentDir, "config.yml"), mergeOmpConfig)
+  syncMergedYaml(ctx, "SoT/.omp/models.yml", p(agentDir, "models.yml"), mergeOmpModels)
 
   const intercomRootSetting = process.env["PI_CODING_AGENT_DIR"]
   const intercomRoot = intercomRootSetting !== undefined && intercomRootSetting !== ""
@@ -112,7 +114,12 @@ function syncWholeFile(
   ctx.nextStepTriggers.ompRestart = true
 }
 
-function syncMergedYaml(ctx: Ctx, sourcePath: OmpTextPayloadPath, target: string): void {
+function syncMergedYaml(
+  ctx: Ctx,
+  sourcePath: OmpTextPayloadPath,
+  target: string,
+  merge: (sotText: string, deployedText: string) => string
+): void {
   const { change, echo, verbose } = ctx.services.logger
   const source = payloadDisplayPath(sourcePath)
   const sotText = payloadText(sourcePath)
@@ -130,7 +137,7 @@ function syncMergedYaml(ctx: Ctx, sourcePath: OmpTextPayloadPath, target: string
   }
 
   const deployedText = readFileSync(target, "utf8")
-  const merged = mergeOmpConfig(sotText, deployedText)
+  const merged = merge(sotText, deployedText)
   if (merged === deployedText) {
     verbose(`omp ${name} already in sync`)
     return
@@ -185,7 +192,7 @@ function firstOutputLine(result: AsyncProcessResult): string {
  * adoption and leaves the active registry present.
  */
 async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFile?: string): Promise<void> {
-  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
+  const { change, clearProgress, echo, progress, verbose } = ctx.services.logger
   const registered = registryHasDocks(registryFile)
   const adoptable = !registered && legacyRegistryFile !== undefined && registryHasDocks(legacyRegistryFile)
 
@@ -201,6 +208,13 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
     return
   }
 
+  // syncPlugins owns the single skip message for both missing CLIs, and it runs
+  // right after this pass. Without omp no marketplace command can run at all,
+  // and without git a marketplace clone cannot resolve, so both are deliberate
+  // skips: return silently instead of spawning and recording a failure.
+  if (ctx.services.deps.probe("omp").state === "missing") return
+  if (ctx.services.deps.probe("git").state === "missing") return
+
   if (!registered && !adoptable) {
     progress("Registering omp docks marketplace...")
     const result = await spawnProcess("omp", ["plugin", "marketplace", "add", MARKETPLACE_SOURCE], {
@@ -210,7 +224,8 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
     if (result.error === undefined && result.exitCode === 0) {
       change("omp docks marketplace registered")
     } else {
-      warn(
+      recordFailure(
+        ctx,
         `omp docks marketplace registration failed: ${firstOutputLine(result)}; run manually: omp plugin marketplace add ${MARKETPLACE_SOURCE}`
       )
     }
@@ -234,7 +249,8 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
     if (listed.error === undefined && listed.exitCode === 0) {
       change("omp docks marketplace registry adopted; refresh-only update skipped")
     } else {
-      warn(
+      recordFailure(
+        ctx,
         `omp docks marketplace adoption failed: ${firstOutputLine(listed)}; run manually: omp plugin marketplace list`
       )
     }
@@ -249,7 +265,8 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
   if (result.error === undefined && result.exitCode === 0) {
     verbose("omp docks marketplace refreshed")
   } else {
-    warn(
+    recordFailure(
+      ctx,
       `omp docks marketplace update failed: ${firstOutputLine(result)}; run manually: omp plugin marketplace update ${MARKETPLACE_NAME}`
     )
   }
@@ -303,13 +320,14 @@ async function runPluginCommand(
   plugin: string,
   args: ReadonlyArray<string>
 ): Promise<boolean> {
-  const { clearProgress, progress, warn } = ctx.services.logger
+  const { clearProgress, progress } = ctx.services.logger
   progress(`Updating omp plugin ${plugin}...`)
   const result = await spawnProcess("omp", args, { stdio: ["ignore", "pipe", "pipe"] })
   clearProgress()
   if (result.error === undefined && result.exitCode === 0) return true
 
-  warn(
+  recordFailure(
+    ctx,
     `omp plugin operation failed for ${plugin}: ${firstOutputLine(result)}; run manually: omp ${args.join(" ")}`
   )
   return false

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

@@ -1,12 +1,18 @@
 /**
- * YAML merge for the omp config.yml and models.yml files.
- * The kit uses the yaml package rather than a line-based merge. Deployed-only keys are
- * retained except for slash-bearing keys directly under retry.fallbackChains:
- * omp treats those as model or provider wildcards ahead of role chains, so a
- * stale wildcard would silently override the kit-managed role chains.
+ * YAML merge for the omp config.yml and models.yml files. omp serialises both
+ * files itself, so the kit uses the yaml package rather than a line-based
+ * merge. Deployed-only keys are retained, except where the file-specific
+ * wrapper drops them: config.yml drops slash-bearing keys directly under
+ * retry.fallbackChains, because omp treats those as model or provider
+ * wildcards ahead of role chains, so a stale wildcard would silently override
+ * the kit-managed role chains. models.yml drops nothing; a user file may carry
+ * provider credentials and custom models the kit never declares.
  */
 import { isMap, isScalar, parseDocument, type YAMLMap } from "yaml"
 
+/** Decides whether a deployed-only key at `path` is dropped instead of kept. */
+type DropDeployedKey = (path: ReadonlyArray<string>, key: string) => boolean
+
 const fallbackChainsPath = ["retry", "fallbackChains"] as const
 
 function stringKey(key: unknown): string | undefined {
@@ -15,29 +21,31 @@ function stringKey(key: unknown): string | undefined {
   return undefined
 }
 
-function isFallbackChains(path: ReadonlyArray<string>): boolean {
-  return (
-    path.length === fallbackChainsPath.length &&
-    path[0] === fallbackChainsPath[0] &&
-    path[1] === fallbackChainsPath[1]
-  )
+function keyName(key: unknown): string {
+  return isScalar(key) ? String(key.value) : String(key)
 }
 
-function pruneFallbackWildcards(mapping: YAMLMap, path: ReadonlyArray<string>): void {
-  const underFallbackChains = isFallbackChains(path)
+const dropFallbackWildcard: DropDeployedKey = (path, key) =>
+  path.length === fallbackChainsPath.length &&
+  path[0] === fallbackChainsPath[0] &&
+  path[1] === fallbackChainsPath[1] &&
+  key.includes("/")
+
+const keepEveryKey: DropDeployedKey = () => false
+
+function pruneMapping(mapping: YAMLMap, path: ReadonlyArray<string>, drop: DropDeployedKey): void {
   for (let index = mapping.items.length - 1; index >= 0; index--) {
     const pair = mapping.items[index]
     if (pair === undefined) continue
 
-    const keyName = isScalar(pair.key) ? String(pair.key.value) : String(pair.key)
-    if (underFallbackChains && keyName.includes("/")) {
+    if (drop(path, keyName(pair.key))) {
       mapping.items.splice(index, 1)
       continue
     }
 
     const key = stringKey(pair.key)
     if (key !== undefined && isMap(pair.value)) {
-      pruneFallbackWildcards(pair.value, [...path, key])
+      pruneMapping(pair.value, [...path, key], drop)
     }
   }
 }
@@ -45,7 +53,8 @@ function pruneFallbackWildcards(mapping: YAMLMap, path: ReadonlyArray<string>):
 function mergeMappings(
   sotMapping: YAMLMap,
   deployedMapping: YAMLMap,
-  path: ReadonlyArray<string>
+  path: ReadonlyArray<string>,
+  drop: DropDeployedKey
 ): void {
   for (const sotPair of sotMapping.items) {
     const key = stringKey(sotPair.key)
@@ -53,7 +62,7 @@ function mergeMappings(
 
     const deployedPair = deployedMapping.items.find((candidate) => stringKey(candidate.key) === key)
     if (deployedPair !== undefined && isMap(sotPair.value) && isMap(deployedPair.value)) {
-      mergeMappings(sotPair.value, deployedPair.value, [...path, key])
+      mergeMappings(sotPair.value, deployedPair.value, [...path, key], drop)
     }
   }
 
@@ -63,22 +72,24 @@ function mergeMappings(
       key !== undefined && sotMapping.items.some((candidate) => stringKey(candidate.key) === key)
     if (isManaged) continue
 
-    const keyName = isScalar(deployedPair.key)
-      ? String(deployedPair.key.value)
-      : String(deployedPair.key)
-    if (isFallbackChains(path) && keyName.includes("/")) continue
+    if (drop(path, keyName(deployedPair.key))) continue
     if (key !== undefined && isMap(deployedPair.value)) {
-      pruneFallbackWildcards(deployedPair.value, [...path, key])
+      pruneMapping(deployedPair.value, [...path, key], drop)
     }
     sotMapping.items.push(deployedPair)
   }
 }
 
-export function mergeOmpConfig(sotText: string, deployedText: string): string {
+function mergeYamlDocuments(
+  sotText: string,
+  deployedText: string,
+  name: string,
+  drop: DropDeployedKey
+): string {
   const deployedDoc = parseDocument(deployedText)
   const deployedError = deployedDoc.errors[0]
   if (deployedError !== undefined) {
-    throw new Error(`Invalid deployed omp YAML: ${deployedError.message}`)
+    throw new Error(`Invalid deployed omp ${name} YAML: ${deployedError.message}`)
   }
 
   const deployedContents = deployedDoc.contents
@@ -90,18 +101,28 @@ export function mergeOmpConfig(sotText: string, deployedText: string): string {
     return sotText
   }
   if (!isMap(deployedContents)) {
-    throw new Error("Deployed omp YAML root must be a mapping")
+    throw new Error(`Deployed omp ${name} YAML root must be a mapping`)
   }
 
   const sotDoc = parseDocument(sotText)
   const sotError = sotDoc.errors[0]
   if (sotError !== undefined) {
-    throw new Error(`Invalid SoT omp YAML: ${sotError.message}`)
+    throw new Error(`Invalid SoT omp ${name} YAML: ${sotError.message}`)
   }
   if (!isMap(sotDoc.contents)) {
-    throw new Error("SoT omp YAML root must be a mapping")
+    throw new Error(`SoT omp ${name} YAML root must be a mapping`)
   }
 
-  mergeMappings(sotDoc.contents, deployedContents, [])
+  mergeMappings(sotDoc.contents, deployedContents, [], drop)
   return sotDoc.toString()
 }
+
+/** config.yml merge: keeps user-only keys, drops stale fallback-chain wildcards. */
+export function mergeOmpConfig(sotText: string, deployedText: string): string {
+  return mergeYamlDocuments(sotText, deployedText, "config.yml", dropFallbackWildcard)
+}
+
+/** models.yml merge: keeps every user-only key, including credentials and custom models. */
+export function mergeOmpModels(sotText: string, deployedText: string): string {
+  return mergeYamlDocuments(sotText, deployedText, "models.yml", keepEveryKey)
+}

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.16.7"
+export const GENERATED_PACKAGE_VERSION = "0.16.9"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",
@@ -21,7 +21,7 @@ export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.omp/config.yml": "symbolPreset: unicode\n\ntheme:\n  dark: titanium\n\nstatusLine:\n  preset: default\n  compactThinkingLevel: false\n  showHookStatus: true\n  sessionAccent: true\n  transparent: false\n\nterminal:\n  showProgress: false\n\ntui:\n  textSizing: false\n  tight: false\n\ndefaultThinkingLevel: high\n\ncycleOrder:\n  - smol\n  - default\n  - slow\n  - fable\n\ntier:\n  openai: none\n  anthropic: none\n\nadvisor:\n  enabled: true\n  syncBacklog: \"1\"\n\ngithub:\n  enabled: true\n\ntask:\n  eager: always\n  showResolvedModelBadge: true\n  softRequestBudget: 200\n  softRequestBudgetNotice: true\n  batch: true\n  enableLsp: true\n  enableEffort: true\n  maxEffort: high\n  maxConcurrency: 16\n  maxRecursionDepth: 2\n  maxRuntimeMs: 3600000\n  agentModelOverrides:\n    reviewer: \"@task\"\n    security-reviewer: \"@task\"\n    code-reviewer: \"@task\"\n    plan-reviewer: \"@task\"\n\nmodelRoles:\n  smol: openai-codex/gpt-5.6-luna:medium\n  advisor: openai-codex/gpt-5.6-sol:medium\n  designer: anthropic/claude-opus-5:high\n  plan: anthropic/claude-opus-5:xhigh\n  commit: openai-codex/gpt-5.6-luna:medium\n  task: openai-codex/gpt-6-astra:low\n  vision: anthropic/claude-opus-5:medium\n  tiny: openai-codex/gpt-5.6-luna:low\n  default: anthropic/claude-opus-5:high\n  slow: anthropic/claude-opus-5:xhigh\n  fable: anthropic/claude-fable-5-1:medium\n  switch_fable: anthropic/claude-fable-5-1:medium\n\nmodelTags:\n  fable:\n    name: Fable 5.1\n  switch_fable:\n    name: Fable switch default\n    hidden: true\n\ndisplay:\n  shimmer: classic\n  showTokenUsage: true\n\nproviders:\n  anthropic:\n    serverSideFallback: false\n  fetch: auto\n  webSearchTimeoutSeconds: 30\n  webSearchOrder:\n    - firecrawl\n    - exa\n    - perplexity\n    - gemini\n    - codex\n\nretry:\n  usageAwareFallback: true\n  fallbackChains:\n    default:\n      - openai-codex/gpt-5.6-sol:high\n    advisor:\n      - anthropic/claude-opus-5:medium\n    task:\n      - anthropic/claude-opus-5:high\n    vision:\n      - openai-codex/gpt-5.6-sol:medium\n    smol:\n      - anthropic/claude-opus-5:low\n    tiny:\n      - anthropic/claude-opus-5:low\n    commit:\n      - anthropic/claude-opus-5:medium\n    switch_fable: []\n    fable: []\n\nomitThinking: false\nincludeWorkspaceTree: false\nautocompleteMaxVisible: 10\nemojiAutocomplete: true\n\nbranchSummary:\n  enabled: true\n\nreadLineNumbers: false\n\ncommands:\n  enableOpencodeProject: false\n  enableOpencodeUser: false\n\nskills:\n  enableClaudeUser: false\n  enableCodexUser: false\n  enableAgentsUser: true\n\nsteeringMode: all\ninterruptMode: immediate\n\ndev:\n  autoqa: false\n  autoqaConsent: denied\n\ncompaction:\n  thresholdTokens: 231200\n  idleEnabled: true\n  handoffSaveToDisk: true\n\ndoubleEscapeAction: tree\nhideThinkingBlock: false\nautoResume: false\ntextVerbosity: low\n\nfeatures:\n  unexpectedStopDetection: smart\n\ncodexResets:\n  autoRedeem: \"no\"\n\nstartup:\n  quiet: true\n  changelogMode: summary\n\ntools:\n  approvalMode: yolo\n",
   "SoT/.omp/intercom.json": "{\n  \"brokerCommand\": \"bun\",\n  \"brokerArgs\": []\n}\n",
   "SoT/.omp/mcp.json": "{\n  \"$schema\": \"https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json\",\n  \"disabledServers\": [\n    \"chrome-devtools\",\n    \"context7:context7\",\n    \"openaiDeveloperDocs\"\n  ]\n}\n",
-  "SoT/.omp/models.yml": "providers:\n  openai-codex:\n    modelOverrides:\n      gpt-6-astra:\n        thinking:\n          mode: effort\n          efforts: [low]\n          defaultLevel: low\n"
+  "SoT/.omp/models.yml": "providers:\n  openai-codex:\n    modelOverrides:\n      gpt-6-astra:\n        thinking:\n          mode: effort\n          efforts:\n            - low\n          defaultLevel: low\n"
 } as const
 
 export const GENERATED_PAYLOAD_BASE64 = {
@@ -50,4 +50,4 @@ export const GENERATED_PAYLOAD_PATHS = [
   "notification.mp3"
 ] as const
 
-export const GENERATED_PAYLOAD_HASH = "a6afdeb3a37285dda06cb48bcf39b5a42702e8d06bf9c47f590047ba6c767bc9"
+export const GENERATED_PAYLOAD_HASH = "5f9f8b3d00c15f6611af2bd8d92bbfcd12481442ff6e0e249846ac2e320b4e37"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.16.7",
+  "version": "0.16.9",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",