docks-kit 0.14.3 → 0.14.4

package/README.md

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

package/cli/docs/flags.md

@@ -23,6 +23,12 @@ docks-kit sync claude agents        # two
 | `--yes` | Auto-accept toolchain above-verified prompts (containers/CI) |
 | `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
 
+## Environment overrides
+
+| Variable | Effect |
+|----------|--------|
+| `DOCKS_KIT_SYNC_CONCURRENCY=1\|2\|3` | Maximum selected sync pipelines running at once. Default `3`; use `1` for serial golden/debug execution. Invalid values fail `sync` with exit 2 but do not affect `model` or `toolchain`. |
+
 ## Per-tool flags
 
 | Flag | Effect |

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 {

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

@@ -3,21 +3,20 @@
  * avoid a TOML library because reformatting user configs would be a behavior
  * change. Guard order, message strings, and backup behavior are golden-tested.
  */
-import { spawnSync } from "node:child_process"
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 
 import { syncCodexEffort, syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
-import { p } from "./exec"
+import { p, spawnProcess } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
 
-export function codexSync(ctx: Ctx): void {
+export async function codexSync(ctx: Ctx): Promise<void> {
   const codexDir = p(ctx.home, ".codex")
   const sotConfig = payloadText("SoT/.codex/config.toml")
   const userConfig = p(codexDir, "config.toml")
 
-  ensureBubblewrap(ctx)
+  await ensureBubblewrap(ctx)
   if (!ctx.dryRun) mkdirSync(codexDir, { recursive: true })
   syncConfig(ctx, sotConfig, userConfig)
   syncCodexModel(ctx, ctx.codexModel)
@@ -25,13 +24,13 @@ export function codexSync(ctx: Ctx): void {
   syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"))
   syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"))
   syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
-  removeLegacyDocksMarketplace(ctx, userConfig)
-  syncPlugins(ctx, sotConfig)
+  await removeLegacyDocksMarketplace(ctx, userConfig)
+  await syncPlugins(ctx, sotConfig)
 }
 
 // ---------------------------------------------------------- bubblewrap ----
 
-function ensureBubblewrap(ctx: Ctx): void {
+async function ensureBubblewrap(ctx: Ctx): Promise<void> {
   const { change, echo, warn } = ctx.services.logger
   if (!bwrapSupportedOs(ctx)) return
 
@@ -58,8 +57,10 @@ function ensureBubblewrap(ctx: Ctx): void {
   }
 
   warn(`bubblewrap not installed - recommended for Codex Linux sandbox. Running: ${pmInstall} (sudo prompt may appear)`)
-  const res = spawnSync("bash", ["-c", pmInstall], { stdio: ["inherit", "inherit", "inherit"] })
-  if (res.status !== 0) {
+  const runInstaller = () =>
+    spawnProcess("bash", ["-c", pmInstall], { stdio: ["inherit", "inherit", "inherit"] })
+  const res = await (ctx.terminalLease?.withExclusive(runInstaller) ?? runInstaller())
+  if (res.exitCode !== 0) {
     warn(`Failed to auto-install bubblewrap. Install manually: ${pmInstall}`)
     return
   }
@@ -69,8 +70,8 @@ function ensureBubblewrap(ctx: Ctx): void {
     return
   }
 
-  if (spawnSync("unshare", ["-Ur", "true"], { stdio: "ignore" }).status === 0) {
-    change(`bubblewrap installed and functional (${ctx.services.deps.version("bwrap")})`)
+  if ((await spawnProcess("unshare", ["-Ur", "true"], { stdio: "ignore" })).exitCode === 0) {
+    change(`bubblewrap installed and functional (${await ctx.services.deps.version("bwrap")})`)
   } else {
     warn(
       "bubblewrap installed but unprivileged user namespaces appear blocked. On Ubuntu 24.04+, prefer loading the AppArmor bwrap-userns-restrict profile; fallback: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0"
@@ -411,7 +412,7 @@ export function marketplaceSource(marketplace: string, configFile: string): stri
   return ""
 }
 
-function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): void {
+async function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): Promise<void> {
   const { change, echo, warn } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] remove legacy configured Codex Docks marketplace when personal marketplace is deployed")
@@ -422,8 +423,8 @@ function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): void {
 
   const source = marketplaceSource("docks", userConfig)
   if (source !== "https://github.com/DocksDocks/docks.git" && source !== "DocksDocks/docks") return
-  const res = spawnSync("codex", ["plugin", "marketplace", "remove", "docks"], { stdio: "ignore" })
-  if (res.error === undefined && res.status === 0) {
+  const res = await spawnProcess("codex", ["plugin", "marketplace", "remove", "docks"], { stdio: "ignore" })
+  if (res.error === undefined && res.exitCode === 0) {
     change("Removed legacy configured Codex Docks marketplace; using personal marketplace file")
     ctx.nextStepTriggers.codexRestart = true
   } else {
@@ -474,13 +475,12 @@ function manualPluginRefreshCommand(sotConfigText: string): string {
   return first !== undefined ? `codex plugin add ${first}` : "codex plugin add <plugin@marketplace>"
 }
 
-function installedPluginIdsFromCli(): Set<string> | undefined {
-  const result = spawnSync("codex", ["plugin", "list", "--json"], {
-    encoding: "utf8",
+async function installedPluginIdsFromCli(): Promise<Set<string> | undefined> {
+  const result = await spawnProcess("codex", ["plugin", "list", "--json"], {
     stdio: ["ignore", "pipe", "ignore"]
   })
-  if (result.error !== undefined || result.status !== 0) return undefined
-  const value = parseJson(result.stdout ?? "")
+  if (result.error !== undefined || result.exitCode !== 0) return undefined
+  const value = parseJson(result.stdout)
   if (value === undefined || !isObject(value) || !Array.isArray(value["installed"])) return undefined
   const ids = new Set<string>()
   for (const row of value["installed"]) {
@@ -490,7 +490,7 @@ function installedPluginIdsFromCli(): Set<string> | undefined {
   return ids
 }
 
-function syncPlugins(ctx: Ctx, sotConfigText: string): void {
+async function syncPlugins(ctx: Ctx, sotConfigText: string): Promise<void> {
   const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
   if (ctx.dryRun) {
     echo(
@@ -520,7 +520,7 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   let pluginIds = desiredPluginIds
   if (ctx.skipPluginRefresh) {
     progress("Checking installed Codex plugins...")
-    const installedPluginIds = installedPluginIdsFromCli()
+    const installedPluginIds = await installedPluginIdsFromCli()
     clearProgress()
     if (installedPluginIds === undefined) {
       warn("Codex plugin inventory unavailable — falling back to the full refresh path")
@@ -533,10 +533,10 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   let failed = 0
   for (const pluginId of pluginIds) {
     progress(`Updating Codex plugin ${pluginId}...`)
-    const res = spawnSync("codex", ["plugin", "add", pluginId], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+    const res = await spawnProcess("codex", ["plugin", "add", pluginId], { stdio: ["ignore", "pipe", "pipe"] })
     clearProgress()
-    const addOut = `${res.stdout ?? ""}${res.stderr ?? ""}`
-    if (res.error === undefined && res.status === 0) {
+    const addOut = `${res.stdout}${res.stderr}`
+    if (res.error === undefined && res.exitCode === 0) {
       refreshed++
     } else if (addOut.includes("could not find a Codex CLI binary")) {
       warn(