docks-kit 0.14.3 → 0.15.0

package/cli/src/commands/sync.ts

@@ -1,18 +1,11 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Effect, Option } from "effect"
 import { spawnSync } from "node:child_process"
 import { existsSync } from "node:fs"
 import { join } from "node:path"
 import { bail, engine } from "../engine"
 import type { Logger } from "../engine-native/logger"
-import {
-  advisorCatalog,
-  advisorFlagGrammar,
-  effortCatalog,
-  effortFlagGrammar
-} from "../efforts"
 import { kitHome } from "../kitHome"
-import { modelCatalog, type Tool } from "../manifests"
 import { LoggerService } from "../services"
 
 /** Best-effort update autodetection: nudge (never block, never fail) when
@@ -38,90 +31,66 @@ const updateNudge = (logger: Logger): void => {
 
 const VALID_TARGETS = ["claude", "codex", "agents"]
 
-// Renamed pre-CLI flags: @effect/cli routes unknown flags into the excess
-// positional args, so the rename hints are mirrored here before EngineNative
-// sees the normalized argv.
-const LEGACY_HINTS: Record<string, string> = {
-  "--force": "--force was renamed to --reconcile",
-  "--remove-plugins":
-    "--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
-  "--680k": "--680k was renamed to --claude-compact-window=680k",
-  "--permissive": "--permissive was renamed to --claude-permissive",
-  "--supabase": "--supabase was renamed to --claude-plugin=supabase",
-  "--n8n": "--n8n was renamed to --claude-plugin=n8n",
-  "--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
-  "--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
-  "--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
-  "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'"
-}
-
-const modelCatalogHint = (t: Tool): string => {
-  const c = modelCatalog(t)
-  const list = c.models
-    .map((m) => `  ${m.id}${m.note !== undefined ? `  — ${m.note}` : ""}`)
-    .join("\n")
-  return `Available ${t} models (kit-verified ${c.verified} — SoT/models.json):\n${list}`
-}
-
-const targets = Args.text({ name: "target" }).pipe(
-  Args.withDescription("Sync targets: claude, codex, agents (default: all three)"),
-  Args.repeated
+const targets = Argument.variadic(
+  Argument.string("target").pipe(
+    Argument.withDescription("Sync targets: claude, codex, agents (default: all three)")
+  )
 )
 
-const dryRun = Options.boolean("dry-run").pipe(
-  Options.withDescription("Preview without applying")
+const dryRun = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Preview without applying")
 )
-const reconcile = Options.boolean("reconcile").pipe(
-  Options.withDescription("Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)")
+const reconcile = Flag.boolean("reconcile").pipe(
+  Flag.withDescription("Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)")
 )
-const prune = Options.boolean("prune").pipe(
-  Options.withDescription("Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)")
+const prune = Flag.boolean("prune").pipe(
+  Flag.withDescription("Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)")
 )
-const skipBubblewrap = Options.boolean("skip-bubblewrap").pipe(
-  Options.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)")
+const skipBubblewrap = Flag.boolean("skip-bubblewrap").pipe(
+  Flag.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)")
 )
-const skipPluginRefresh = Options.boolean("skip-plugin-refresh").pipe(
-  Options.withDescription("Install missing plugins but skip refresh-only updates for existing plugins")
+const skipPluginRefresh = Flag.boolean("skip-plugin-refresh").pipe(
+  Flag.withDescription("Install missing plugins but skip refresh-only updates for existing plugins")
 )
-const yes = Options.boolean("yes").pipe(
-  Options.withDescription("Auto-accept toolchain prompts (containers/CI)")
+const yes = Flag.boolean("yes").pipe(
+  Flag.withDescription("Auto-accept toolchain prompts (containers/CI)")
 )
-const verbose = Options.boolean("verbose").pipe(
-  Options.withAlias("v"),
-  Options.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)")
+const verbose = Flag.boolean("verbose").pipe(
+  Flag.withAlias("v"),
+  Flag.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)")
 )
-const claudeModel = Options.text("claude-model").pipe(
-  Options.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
-  Options.optional
+const claudeModel = Flag.string("claude-model").pipe(
+  Flag.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
+  Flag.optional
 )
-const claudeEffort = Options.text("claude-effort").pipe(
-  Options.withDescription("Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)"),
-  Options.optional
+const claudeEffort = Flag.string("claude-effort").pipe(
+  Flag.withDescription("Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)"),
+  Flag.optional
 )
-const claudeAdvisor = Options.text("claude-advisor").pipe(
-  Options.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
-  Options.optional
+const claudeAdvisor = Flag.string("claude-advisor").pipe(
+  Flag.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
+  Flag.optional
 )
-const claudeCompactWindow = Options.text("claude-compact-window").pipe(
-  Options.withDescription("Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)"),
-  Options.optional
+const claudeCompactWindow = Flag.string("claude-compact-window").pipe(
+  Flag.withDescription("Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)"),
+  Flag.optional
 )
-const claudePermissive = Options.boolean("claude-permissive").pipe(
-  Options.withDescription("Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)")
+const claudePermissive = Flag.boolean("claude-permissive").pipe(
+  Flag.withDescription("Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)")
 )
-const claudePlugin = Options.text("claude-plugin").pipe(
-  Options.withDescription(
+const claudePlugin = Flag.string("claude-plugin").pipe(
+  Flag.withDescription(
     "Sticky opt-in plugin(s); repeatable and/or comma-separated (known: supabase, n8n)"
   ),
-  Options.repeated
+  Flag.atLeast(0)
 )
-const codexModel = Options.text("codex-model").pipe(
-  Options.withDescription("Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)"),
-  Options.optional
+const codexModel = Flag.string("codex-model").pipe(
+  Flag.withDescription("Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)"),
+  Flag.optional
 )
-const codexEffort = Options.text("codex-effort").pipe(
-  Options.withDescription("Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)"),
-  Options.optional
+const codexEffort = Flag.string("codex-effort").pipe(
+  Flag.withDescription("Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)"),
+  Flag.optional
 )
 
 export const syncCommand = Command.make(
@@ -146,24 +115,6 @@ export const syncCommand = Command.make(
   },
   (config) =>
     Effect.gen(function* () {
-      for (const t of config.targets) {
-        if (VALID_TARGETS.includes(t)) continue
-        if (t === "--claude-model" || t === "--codex-model") {
-          const tool: Tool = t === "--claude-model" ? "claude" : "codex"
-          return yield* bail(`${modelCatalogHint(tool)}\n${t} requires a value: ${t}=<model>`)
-        }
-        if (t === "--claude-effort" || t === "--codex-effort") {
-          const tool: Tool = t === "--claude-effort" ? "claude" : "codex"
-          return yield* bail(`${effortCatalog(tool)}\n${t} requires a value: ${effortFlagGrammar(tool)}`)
-        }
-        if (t === "--claude-advisor") {
-          return yield* bail(`${advisorCatalog()}\n${t} requires a value: ${advisorFlagGrammar()}`)
-        }
-        const hint = LEGACY_HINTS[t]
-        if (hint !== undefined) {
-          return yield* bail(hint)
-        }
-      }
       const bad = config.targets.filter((t) => !VALID_TARGETS.includes(t))
       if (bad.length > 0) {
         return yield* bail(

package/cli/src/commands/toolchain.ts

@@ -1,23 +1,23 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Effect, Option } from "effect"
 import { bail, engine } from "../engine"
 
 const MANAGED = ["bun", "effect-solutions"]
 
-const op = Args.text({ name: "op" }).pipe(
-  Args.withDescription("check (default) | ensure <tool>"),
-  Args.optional
+const op = Argument.string("op").pipe(
+  Argument.withDescription("check (default) | ensure <tool>"),
+  Argument.optional
 )
-const tool = Args.text({ name: "tool" }).pipe(
-  Args.withDescription(`Managed tool for ensure: ${MANAGED.join(", ")}`),
-  Args.optional
+const tool = Argument.string("tool").pipe(
+  Argument.withDescription(`Managed tool for ensure: ${MANAGED.join(", ")}`),
+  Argument.optional
 )
-const yes = Options.boolean("yes").pipe(
-  Options.withDescription("Auto-accept above-verified installs")
+const yes = Flag.boolean("yes").pipe(
+  Flag.withDescription("Auto-accept above-verified installs")
 )
-const verbose = Options.boolean("verbose").pipe(
-  Options.withAlias("v"),
-  Options.withDescription("Also print no-op confirmations (present, up to date)")
+const verbose = Flag.boolean("verbose").pipe(
+  Flag.withAlias("v"),
+  Flag.withDescription("Also print no-op confirmations (present, up to date)")
 )
 
 export const toolchainCommand = Command.make("toolchain", { op, tool, yes, verbose }, (config) =>

package/cli/src/commands/update.ts

@@ -1,4 +1,4 @@
-import { Command, Options } from "@effect/cli"
+import { Command, Flag } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
 import { spawnSync } from "node:child_process"
 import { existsSync, readFileSync } from "node:fs"
@@ -6,8 +6,8 @@ import { join } from "node:path"
 import { bail, compiled } from "../engine"
 import { kitHome } from "../kitHome"
 
-const noSync = Options.boolean("no-sync").pipe(
-  Options.withDescription("Update the kit only; skip the chained flag-less sync")
+const noSync = Flag.boolean("no-sync").pipe(
+  Flag.withDescription("Update the kit only; skip the chained flag-less sync")
 )
 
 const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {

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

@@ -31,6 +31,11 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
   materialized settings, writes runtime assets, commits settings, then performs
   readiness-gated legacy cleanup. Modifiers run after the base commit, removals
   before plugins, and LSP checks after plugin state.
+- **Pipeline concurrency is bounded.** Selected Claude, Codex, and skills
+  pipelines overlap through one input-ordered pool. The production default is
+  3; `DOCKS_KIT_SYNC_CONCURRENCY=1` restores serial execution for golden tests
+  and debugging (`2` allows two-way overlap). Each individual pipeline remains
+  serial, and summaries retain canonical Claude, Codex, skills order.
 - **External CLIs stay external.** `claude`, `codex`, `npx`, `npm`, `bun`,
   `curl`, and platform package managers are spawned with argv arrays,
   not shell command strings except where the external installer contract is a
@@ -69,10 +74,16 @@ warnings, and the summary. Status-quo confirmations exist but are opt-in.
   stderr sink exists and `process.stderr.isTTY` is `true`. It disables progress
   in every other case. Injected golden sinks therefore keep their existing
   bytes unless the harness supplies a progress sink.
-- Each progress write replaces one terminal line. `clearProgress()` erases a
-  pending line and does nothing when no line is pending. Every durable
-  `change`, `verbose`, `warn`, `err`, or `echo` write erases the pending line
-  before it writes durable output.
+- Each progress write replaces one terminal line. Every durable `change`,
+  `verbose`, `warn`, `err`, or `echo` write erases a visible transient before
+  its own write.
+- During sync, the coordinator holds one run-scoped terminal lease and owns
+  the transient line. Terminal-exclusive sections serialize input ownership
+  by acquisition order and suspend progress redraw while an inherited-stdio
+  installer or blocking prompt holds the lease.
+- Automated tests cannot exercise real input contention: golden children use
+  ignored stdin, so `process.stdin.isTTY` is false. The simultaneous-prompt
+  path requires hand verification in a real TTY.
 
 ### Change detection
 

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

@@ -1,8 +1,7 @@
-import { spawnSync } from "node:child_process"
 import { rmSync } from "node:fs"
 import { tmpdir } from "node:os"
 
-import { p } from "./exec"
+import { p, spawnProcess } from "./exec"
 import type { Ctx } from "./index"
 import type { EngineServices } from "./services"
 import { field } from "./toolchain"
@@ -11,10 +10,6 @@ export type BunRuntimeState =
   | { readonly kind: "ready"; readonly executable: string }
   | { readonly kind: "deferred"; readonly reason: "missing-curl" | "install-failed" }
 
-function remember(ctx: Ctx, state: BunRuntimeState): BunRuntimeState {
-  ctx.bunRuntime = state
-  return state
-}
 
 function predictedExecutable(ctx: Ctx): string {
   const root = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
@@ -23,47 +18,53 @@ function predictedExecutable(ctx: Ctx): string {
   return p(root, "bin", "bun")
 }
 
-function installBun(pin: string, installer: string): void {
-  const download = spawnSync("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], { stdio: "ignore" })
-  if (download.error === undefined && download.status === 0) {
-    spawnSync("bash", [installer, `bun-v${pin}`], { stdio: "ignore" })
+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" })
   }
 }
 
-export function bunBootstrap(ctx: Ctx, services: EngineServices): BunRuntimeState {
+export function bunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunRuntimeState> {
   if (ctx.bunRuntime !== undefined) return ctx.bunRuntime
+  const pending = runBunBootstrap(ctx, services)
+  ctx.bunRuntime = pending
+  return pending
+}
+
+async function runBunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunRuntimeState> {
 
-  const existing = services.deps.path("bun")
-  if (existing !== "") return remember(ctx, { kind: "ready", executable: existing })
+  const existing = await services.deps.path("bun")
+  if (existing !== "") return { kind: "ready", executable: existing }
 
   const pin = field(ctx, "bun", "verified")
   if (pin === "") {
     services.logger.warn("Bun bootstrap aborted — SoT/toolchain.json has no verified Bun pin")
-    return remember(ctx, { kind: "deferred", reason: "install-failed" })
+    return { kind: "deferred", reason: "install-failed" }
   }
   if (services.deps.probe("curl").state === "missing") {
     services.deps.warnMissing("curl", services.logger, "cannot bootstrap Bun; install Bun manually, then re-run sync")
-    return remember(ctx, { kind: "deferred", reason: "missing-curl" })
+    return { kind: "deferred", reason: "missing-curl" }
   }
   if (ctx.dryRun) {
     const executable = predictedExecutable(ctx)
     services.logger.echo(`[dry-run] install Bun ${pin} (kit-verified) -> ${executable}`)
-    return remember(ctx, { kind: "ready", executable })
+    return { kind: "ready", executable }
   }
   services.logger.warn(`Bun not found — installing Bun ${pin} (kit-verified)...`)
   const installer = p(tmpdir(), `bun-install-${process.pid}.sh`)
   try {
-    installBun(pin, installer)
+    await installBun(pin, installer)
   } finally {
     rmSync(installer, { force: true })
   }
 
-  const installed = services.deps.path("bun")
+  const installed = await services.deps.path("bun")
   if (installed === "") {
     services.logger.warn("Bun install failed. Install manually from https://bun.sh/docs/installation, then re-run sync.")
-    return remember(ctx, { kind: "deferred", reason: "install-failed" })
+    return { kind: "deferred", reason: "install-failed" }
   }
-  const version = services.deps.version("bun")
+  const version = await services.deps.version("bun")
   services.logger.change(`Bun installed (${version !== "" ? version : "version unknown"})`)
-  return remember(ctx, { kind: "ready", executable: installed })
+  return { kind: "ready", executable: installed }
 }

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

@@ -4,7 +4,6 @@
  * plugins. Message strings, guard order, JSON semantics, and spawned argv are
  * golden-tested.
  */
-import { spawnSync } from "node:child_process"
 import {
   appendFileSync,
   copyFileSync,
@@ -23,7 +22,7 @@ import {
   syncClaudeModel
 } from "./claudeSettingsModifiers"
 import { claudeRuntimePaths, materializeClaudeSettings, type ClaudeRuntimePaths } from "./claudeRuntime"
-import { p, writeBytesIfChanged, writeTextIfChanged } from "./exec"
+import { p, spawnProcess, writeBytesIfChanged, writeTextIfChanged } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, type Json } from "./jq"
 import { ExitError } from "./parseArgs"
@@ -35,7 +34,7 @@ export type ClaudeRuntimeState =
   | { readonly kind: "ready"; readonly paths: ClaudeRuntimePaths }
   | { readonly kind: "deferred"; readonly reason: "bun-unavailable" }
 
-export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
+export async function claudeSync(ctx: Ctx): Promise<ClaudeRuntimeState> {
   const { err, warn } = ctx.services.logger
   const claudeDir = p(ctx.home, ".claude")
 
@@ -47,7 +46,7 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
     )
   }
 
-  const bun = bunBootstrap(ctx, ctx.services)
+  const bun = await bunBootstrap(ctx, ctx.services)
   const runtime: ClaudeRuntimeState = bun.kind === "ready"
     ? { kind: "ready", paths: claudeRuntimePaths(claudeDir, bun.executable) }
     : { kind: "deferred", reason: "bun-unavailable" }
@@ -78,9 +77,9 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
   syncClaudeAdvisor(ctx, ctx.claudeAdvisor)
   syncClaudeJson(ctx)
   syncConnectorEnv(ctx)
-  syncPlugins(ctx, claudeDir)
-  syncOptionalPlugins(ctx, claudeDir)
-  syncLspServers(ctx)
+  await syncPlugins(ctx, claudeDir)
+  await syncOptionalPlugins(ctx, claudeDir)
+  await syncLspServers(ctx)
   return runtime
 }
 
@@ -523,9 +522,9 @@ function syncRemovals(ctx: Ctx, claudeDir: string, runtime: ClaudeRuntimeState):
 
 // -------------------------------------------------------------- plugins ----
 
-function cli(args: Array<string>): { ok: boolean; out: string } {
-  const res = spawnSync("claude", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
-  return { ok: res.error === undefined && res.status === 0, out: `${res.stdout ?? ""}${res.stderr ?? ""}` }
+async function cli(args: Array<string>): Promise<{ ok: boolean; out: string }> {
+  const res = await spawnProcess("claude", args, { stdio: ["ignore", "pipe", "pipe"] })
+  return { ok: res.error === undefined && res.exitCode === 0, out: `${res.stdout}${res.stderr}` }
 }
 
 function readJsonFile(file: string): Json | undefined {
@@ -564,7 +563,7 @@ function nonUserScopeMarketplaces(installedDoc: Json | undefined): Set<string> {
   return marketplaces
 }
 
-function syncPlugins(ctx: Ctx, claudeDir: string): void {
+async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
   const knownMarketplaces = p(claudeDir, "plugins", "known_marketplaces.json")
   const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json")
@@ -607,7 +606,7 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     if (known !== undefined && isObject(known) && known[mpName] !== undefined && known[mpName] !== null && known[mpName] !== false) continue
     const repo = isObject(mpValue) && isObject(mpValue["source"]) ? String((mpValue["source"] as { [k: string]: Json })["repo"] ?? "") : ""
     progress(`Adding marketplace ${mpName}...`)
-    const marketplaceResult = cli(["plugin", "marketplace", "add", repo])
+    const marketplaceResult = await cli(["plugin", "marketplace", "add", repo])
     clearProgress()
     if (marketplaceResult.ok) {
       addedMp++
@@ -628,12 +627,12 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     const mpName = separator > 0 ? pluginId.slice(separator + 1) : ""
     if (mpName !== "" && !refreshedMarketplaces.has(mpName)) {
       progress(`Refreshing marketplace ${mpName}...`)
-      cli(["plugin", "marketplace", "update", mpName])
+      await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
       refreshedMarketplaces.add(mpName)
     }
     progress(`Installing plugin ${pluginId}...`)
-    const installResult = cli(["plugin", "install", pluginId])
+    const installResult = await cli(["plugin", "install", pluginId])
     clearProgress()
     if (installResult.ok) {
       addedPl++
@@ -664,13 +663,13 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
   if (!ctx.skipPluginRefresh) {
     for (const mpName of [...kitMarketplaces].sort(compareCodepoints)) {
       progress(`Refreshing marketplace ${mpName}...`)
-      cli(["plugin", "marketplace", "update", mpName])
+      await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
     }
     for (const pluginId of [...kitPluginIds].sort(compareCodepoints)) {
       if (!pluginUserScopeInstalled(installedPlugins, pluginId)) continue
       progress(`Updating plugin ${pluginId}...`)
-      const updateResult = cli(["plugin", "update", pluginId, "--scope", "user"])
+      const updateResult = await cli(["plugin", "update", pluginId, "--scope", "user"])
       clearProgress()
       if (updateResult.out.includes("Successfully updated")) updatedPl++
     }
@@ -686,7 +685,7 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
       if (isObject(sotPlugins) && Object.prototype.hasOwnProperty.call(sotPlugins, pluginId)) continue
       if (!pluginUserScopeInstalled(installedPlugins, pluginId)) continue
       progress(`Uninstalling plugin ${pluginId}...`)
-      const uninstallResult = cli(["plugin", "uninstall", "-y", "--scope", "user", pluginId])
+      const uninstallResult = await cli(["plugin", "uninstall", "-y", "--scope", "user", pluginId])
       clearProgress()
       if (uninstallResult.ok) {
         removedPl++
@@ -702,7 +701,7 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
       const declared = isObject(sotMarketplaces) ? sotMarketplaces[mpName] : undefined
       if (declared !== undefined && declared !== null && declared !== false) continue
       progress(`Removing marketplace ${mpName}...`)
-      const removeResult = cli(["plugin", "marketplace", "remove", mpName])
+      const removeResult = await cli(["plugin", "marketplace", "remove", mpName])
       clearProgress()
       if (removeResult.ok) {
         removedMp++
@@ -714,7 +713,7 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
   }
 
   // Pass 6 — re-assert SoT enabled-state in the user settings.
-  if (reassertEnabledState(ctx, repoObj, p(claudeDir, "settings.json"))) {
+  if (await reassertEnabledState(ctx, repoObj, p(claudeDir, "settings.json"))) {
     change("Plugin enable-state re-asserted from SoT in settings.json")
     ctx.nextStepTriggers.claudePlugins = true
   }
@@ -731,7 +730,7 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
   }
 }
 
-function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, userSettingsFile: string): boolean {
+async function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, userSettingsFile: string): Promise<boolean> {
   const { warn } = ctx.services.logger
   if (!existsSync(userSettingsFile)) return false
   const sotPlugins = isObject(repoObj["enabledPlugins"]) ? repoObj["enabledPlugins"] : {}
@@ -742,7 +741,7 @@ function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, userSett
     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 (cli(["plugin", "disable", pluginId]).ok) {
+    if ((await cli(["plugin", "disable", pluginId])).ok) {
       cliDisabled = true
     } else {
       warn(`Failed to disable SoT-false plugin: ${pluginId} (will retry next sync)`)
@@ -765,7 +764,7 @@ function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, userSett
 
 // ------------------------------------------------------ optional plugins ----
 
-function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, marketplaceRepo: string): boolean {
+async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, marketplaceRepo: string): Promise<boolean> {
   const { change, clearProgress, progress, verbose, warn } = ctx.services.logger
   const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json")
   const knownMarketplaces = p(claudeDir, "plugins", "known_marketplaces.json")
@@ -776,7 +775,7 @@ function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, mar
     const known = readJsonFile(knownMarketplaces)
     const has = known !== undefined && isObject(known) && known[mpName] !== undefined && known[mpName] !== null && known[mpName] !== false
     if (!has) {
-      if (!cli(["plugin", "marketplace", "add", marketplaceRepo]).ok) {
+      if (!(await cli(["plugin", "marketplace", "add", marketplaceRepo])).ok) {
         warn(`Failed to add marketplace ${marketplaceRepo} for ${pluginId}`)
         return false
       }
@@ -787,7 +786,7 @@ function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, mar
   const wasInstalled = pluginUserScopeInstalled(installedPlugins, pluginId)
   if (!wasInstalled) {
     progress(`Installing plugin ${pluginId}...`)
-    const installResult = cli(["plugin", "install", pluginId])
+    const installResult = await cli(["plugin", "install", pluginId])
     clearProgress()
     if (!installResult.ok) {
       if (marketplaceAdded) change(`Optional plugin ${pluginId}: marketplace added (install failed — will retry next sync)`)
@@ -802,7 +801,7 @@ function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, mar
       ? (settingsDoc["enabledPlugins"] as { [k: string]: Json })[pluginId] === true
       : false
 
-  if (!cli(["plugin", "enable", pluginId]).ok) {
+  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}`)
     return marketplaceAdded || !wasInstalled
@@ -813,7 +812,7 @@ function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, mar
   return changed
 }
 
-function syncOptionalPlugins(ctx: Ctx, claudeDir: string): void {
+async function syncOptionalPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   const { echo, warn } = ctx.services.logger
   if (ctx.claudePlugins.length === 0) return
 
@@ -833,10 +832,10 @@ function syncOptionalPlugins(ctx: Ctx, claudeDir: string): void {
   }
 
   if (ctx.claudePlugins.includes("supabase")) {
-    if (enableOptionalPlugin(ctx, claudeDir, "supabase@claude-plugins-official", "")) ctx.nextStepTriggers.claudePlugins = true
+    if (await enableOptionalPlugin(ctx, claudeDir, "supabase@claude-plugins-official", "")) ctx.nextStepTriggers.claudePlugins = true
   }
   if (ctx.claudePlugins.includes("n8n")) {
-    if (enableOptionalPlugin(ctx, claudeDir, "n8n-mcp-skills@n8n-mcp-skills", "czlonkowski/n8n-skills")) ctx.nextStepTriggers.claudePlugins = true
+    if (await enableOptionalPlugin(ctx, claudeDir, "n8n-mcp-skills@n8n-mcp-skills", "czlonkowski/n8n-skills")) ctx.nextStepTriggers.claudePlugins = true
   }
 }
 
@@ -847,7 +846,7 @@ function lspPkg(ctx: Ctx, tool: string, pkg: string): string {
   return v !== "" ? `${pkg}@${v}` : pkg
 }
 
-function syncLspServers(ctx: Ctx): void {
+async function syncLspServers(ctx: Ctx): Promise<void> {
   const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
   const sot = parseJson(payloadText("SoT/.claude/settings.json"))
   const enabled = sot !== undefined && isObject(sot) && isObject(sot["enabledPlugins"]) ? sot["enabledPlugins"] : undefined
@@ -889,9 +888,9 @@ function syncLspServers(ctx: Ctx): void {
 
   verbose(`Installing LSP servers via npm: ${specs}...`)
   progress(`Installing LSP servers via npm: ${specs}...`)
-  const installResult = spawnSync("npm", ["install", "-g", ...missing], { stdio: "ignore" })
+  const installResult = await spawnProcess("npm", ["install", "-g", ...missing], { stdio: "ignore" })
   clearProgress()
-  if (installResult.status === 0) {
+  if (installResult.exitCode === 0) {
     change(`LSP servers installed (${specs})`)
     ctx.nextStepTriggers.claudeRestart = true
   } else {