docks-kit 0.16.9 → 0.16.11

package/AGENTS.md

@@ -82,7 +82,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 - **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.
-- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
+- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **Per-machine harness selection.** `~/.docks-kit/state.json` drives a flag-less sync. A missing file selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection file. `docks-kit harnesses` is the only command that writes the selection.
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.

package/cli/docs/flags.md

@@ -19,7 +19,7 @@ docks-kit sync claude agents        # two
 | `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
 | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
 | `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
-| `--skip-plugin-refresh` | Install missing Claude/Codex plugins but skip refresh-only updates; `docks-kit update` uses this automatically |
+| `--skip-plugin-refresh` | Install missing Claude/Codex plugins but skip refresh-only updates |
 | `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
 
 ## Environment overrides

package/cli/docs/install.md

@@ -80,7 +80,7 @@ installer bootstraps Bun when absent. It then runs
 ## Keeping the kit up to date
 
 ```
-docks-kit update            # autodetect + update + install-missing-only sync
+docks-kit update            # autodetect + update + full sync (refreshes plugins)
 docks-kit update --no-sync  # update only
 ```
 

package/cli/src/commands/update.ts

@@ -68,11 +68,7 @@ const chainSync = (argv0: string, args: Array<string>): Effect.Effect<void> =>
     if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1)
   })
 
-export const updateSyncArgs = (home: string): Array<string> => [
-  p(home, "cli/src/main.ts"),
-  "sync",
-  "--skip-plugin-refresh"
-]
+export const updateSyncArgs = (home: string): Array<string> => [p(home, "cli/src/main.ts"), "sync"]
 
 const readPackageVersion = (home: string): string => {
   try {
@@ -211,28 +207,33 @@ const updateCheckout = (home: string, skipSync: boolean) =>
     if (!pull.ok) return yield* bail(`git pull --ff-only failed (diverged history?):\n${pull.out}`)
     const after = git(home, ["rev-parse", "HEAD"]).out
 
-    if (before === after) {
-      return yield* Console.log(`Already at the latest version (${after.slice(0, 7)}, upstream ${upstream.out}).`)
-    }
-
-    const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out
-    yield* Console.log(`Updated ${before.slice(0, 7)}..${after.slice(0, 7)} (${count} commit(s) from ${upstream.out}).`)
+    // A current kit still syncs: the plugin passes deliver marketplace and
+    // plugin updates that move independently of the kit's own version.
+    const changed = before !== after
+    if (changed) {
+      const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out
+      yield* Console.log(`Updated ${before.slice(0, 7)}..${after.slice(0, 7)} (${count} commit(s) from ${upstream.out}).`)
 
-    const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n")
-    if (touched.includes("bun.lock") || touched.includes("package.json")) {
-      const res = spawnUpdate("bun", ["install", "--frozen-lockfile"], { cwd: home, stdio: "inherit" })
-      if (res.error !== undefined || res.status !== 0) {
-        return yield* bail("dependencies changed but 'bun install --frozen-lockfile' failed - fix that, then run docks-kit sync", 1)
+      const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n")
+      if (touched.includes("bun.lock") || touched.includes("package.json")) {
+        const res = spawnUpdate("bun", ["install", "--frozen-lockfile"], { cwd: home, stdio: "inherit" })
+        if (res.error !== undefined || res.status !== 0) {
+          return yield* bail("dependencies changed but 'bun install --frozen-lockfile' failed - fix that, then run docks-kit sync", 1)
+        }
       }
+    } else {
+      yield* Console.log(`Already at the latest version (${after.slice(0, 7)}, upstream ${upstream.out}).`)
     }
 
     if (compiled) {
       return yield* Console.log(
-        "This compiled binary still runs the previous version - the checkout launcher will use updated source next time. Run: ./docks-kit sync (rebuild with bash cli/build-binaries.sh to restore the binary fast path)."
+        changed
+          ? "This compiled binary still runs the previous version - the checkout launcher will use updated source next time. Run: ./docks-kit sync (rebuild with bash cli/build-binaries.sh to restore the binary fast path)."
+          : "This compiled binary cannot chain the sync. Run: ./docks-kit sync"
       )
     }
-    if (skipSync) return yield* Console.log("Kit updated. Run: docks-kit sync")
-    yield* Console.log("Kit updated - running sync with the new version...")
+    if (skipSync) return yield* Console.log(changed ? "Kit updated. Run: docks-kit sync" : "Run: docks-kit sync")
+    yield* Console.log(changed ? "Kit updated - running sync with the new version..." : "Syncing to deliver plugin and config updates...")
     return yield* chainSync(process.execPath, updateSyncArgs(home))
   })
 
@@ -267,9 +268,12 @@ const updatePackage = (home: string, skipSync: boolean) =>
     }
     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...")
+    if (skipSync) return yield* Console.log(result.alreadyCurrent ? "Run: docks-kit sync" : "Kit updated. Run: docks-kit sync")
+    yield* Console.log(
+      result.alreadyCurrent
+        ? "Syncing to deliver plugin and config updates..."
+        : "Kit updated - running sync with the new version..."
+    )
     return yield* chainSync(process.execPath, updateSyncArgs(updated.home))
   })
 
@@ -288,6 +292,6 @@ export const updateCommand = Command.make("update", { noSync }, (config) =>
   })
 ).pipe(
   Command.withDescription(
-    "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest) and chains an install-missing-only sync with the new version (--no-sync to skip)."
+    "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest), then chains a flag-less sync that also refreshes plugin marketplaces and plugins, even when the kit was already current (--no-sync to skip)."
   )
 )

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

@@ -11,9 +11,19 @@ import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, readJso
 import { field } from "./toolchain"
 import { payloadText } from "../payload"
 
-async function cli(args: Array<string>): Promise<{ ok: boolean; out: string }> {
+async function cli(args: Array<string>): Promise<{ ok: boolean; out: string; detail: string }> {
   const res = await spawnProcess("claude", args, { stdio: ["ignore", "pipe", "pipe"] })
-  return { ok: res.error === undefined && res.exitCode === 0, out: `${res.stdout}${res.stderr}` }
+  // A spawn error carries its cause in `error`, not in either stream, and that
+  // is the case a failure message cannot afford to drop: it names an
+  // unresolvable launcher instead of a rejected command.
+  const out = res.error !== undefined ? res.error.message : `${res.stdout}${res.stderr}`
+  const detail = out.split("\n").map((line) => line.trim()).find((line) => line !== "") ?? "unknown error"
+  return { ok: res.error === undefined && res.exitCode === 0, out, detail }
+}
+
+/** Failure message tail: the cause, then the command to re-run by hand. */
+function manually(detail: string, args: Array<string>): string {
+  return `${detail}; run manually: claude ${args.join(" ")}`
 }
 
 function sortedKeys(obj: Json | undefined): Array<string> {
@@ -96,7 +106,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (marketplaceResult.ok) {
       addedMp++
     } else {
-      recordFailure(ctx, `Failed to add marketplace: ${mpName} (${repo})`)
+      recordFailure(
+        ctx,
+        `Failed to add marketplace: ${mpName} (${repo}): ${manually(marketplaceResult.detail, ["plugin", "marketplace", "add", repo])}`
+      )
       f1++
     }
   }
@@ -117,7 +130,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       const refreshResult = await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
       if (!refreshResult.ok) {
-        recordFailure(ctx, `Failed to refresh marketplace: ${mpName}`)
+        recordFailure(
+          ctx,
+          `Failed to refresh marketplace: ${mpName}: ${manually(refreshResult.detail, ["plugin", "marketplace", "update", mpName])}`
+        )
         f3++
       }
       refreshedMarketplaces.add(mpName)
@@ -128,7 +144,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (installResult.ok) {
       addedPl++
     } else {
-      recordFailure(ctx, `Failed to install plugin: ${pluginId}`)
+      recordFailure(
+        ctx,
+        `Failed to install plugin: ${pluginId}: ${manually(installResult.detail, ["plugin", "install", pluginId])}`
+      )
       f2++
     }
   }
@@ -162,7 +181,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       clearProgress()
       refreshedMarketplaces.add(mpName)
       if (!refreshResult.ok) {
-        recordFailure(ctx, `Failed to refresh marketplace: ${mpName}`)
+        recordFailure(
+          ctx,
+          `Failed to refresh marketplace: ${mpName}: ${manually(refreshResult.detail, ["plugin", "marketplace", "update", mpName])}`
+        )
         f3++
       }
     }
@@ -173,7 +195,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       const updateResult = await cli(["plugin", "update", pluginId, "--scope", "user"])
       clearProgress()
       if (!updateResult.ok) {
-        recordFailure(ctx, `Failed to update plugin: ${pluginId}`)
+        recordFailure(
+          ctx,
+          `Failed to update plugin: ${pluginId}: ${manually(updateResult.detail, ["plugin", "update", pluginId, "--scope", "user"])}`
+        )
         f4++
       } else if (updateResult.out.includes("Successfully updated")) {
         updatedPl++
@@ -196,7 +221,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       if (uninstallResult.ok) {
         removedPl++
       } else {
-        recordFailure(ctx, `Failed to uninstall plugin: ${pluginId}`)
+        recordFailure(
+          ctx,
+          `Failed to uninstall plugin: ${pluginId}: ${manually(uninstallResult.detail, ["plugin", "uninstall", "-y", "--scope", "user", pluginId])}`
+        )
         f5++
       }
     }
@@ -212,7 +240,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       if (removeResult.ok) {
         removedMp++
       } else {
-        recordFailure(ctx, `Failed to remove marketplace: ${mpName}`)
+        recordFailure(
+          ctx,
+          `Failed to remove marketplace: ${mpName}: ${manually(removeResult.detail, ["plugin", "marketplace", "remove", mpName])}`
+        )
         f6++
       }
     }
@@ -247,10 +278,14 @@ async function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, us
     const user = readJsonFile(userSettingsFile)
     const enabled = user !== undefined && isObject(user) && isObject(user["enabledPlugins"]) ? (user["enabledPlugins"] as { [k: string]: Json })[pluginId] : undefined
     if (enabled !== true) continue
-    if ((await cli(["plugin", "disable", pluginId])).ok) {
+    const disableResult = await cli(["plugin", "disable", pluginId])
+    if (disableResult.ok) {
       cliDisabled = true
     } else {
-      recordFailure(ctx, `Failed to disable SoT-false plugin: ${pluginId} (will retry next sync)`)
+      recordFailure(
+        ctx,
+        `Failed to disable SoT-false plugin: ${pluginId} (will retry next sync): ${manually(disableResult.detail, ["plugin", "disable", pluginId])}`
+      )
     }
   }
 

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.9"
+export const GENERATED_PACKAGE_VERSION = "0.16.11"
 
 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",

package/package.json

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