docks-kit 0.14.2 → 0.14.4

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

@@ -1,9 +1,9 @@
 /**
- * EngineNative `sync claude` pipeline. Step order is load-bearing: rtk BEFORE
- * the settings merge, modifiers after it, removals before plugins. Message
- * strings, guard order, JSON semantics, and spawned argv are golden-tested.
+ * EngineNative `sync claude` pipeline. Step order is load-bearing: the Bun
+ * bootstrap BEFORE the settings merge, modifiers after it, removals before
+ * plugins. Message strings, guard order, JSON semantics, and spawned argv are
+ * golden-tested.
  */
-import { spawnSync } from "node:child_process"
 import {
   appendFileSync,
   copyFileSync,
@@ -15,7 +15,6 @@ import {
   rmSync,
   writeFileSync
 } from "node:fs"
-import { tmpdir } from "node:os"
 import { bunBootstrap } from "./bun"
 import {
   syncClaudeAdvisor,
@@ -23,20 +22,19 @@ 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 type { EngineServices } from "./services"
 import { ExitError } from "./parseArgs"
 import { mergeSettings, reconcileSettings } from "./settings"
-import { ensure, field } from "./toolchain"
+import { field } from "./toolchain"
 import { payloadBytes, payloadDisplayPath, payloadText } from "../payload"
 
 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")
 
@@ -48,8 +46,7 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
     )
   }
 
-  syncRtk(ctx, claudeDir)
-  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" }
@@ -80,92 +77,12 @@ 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
 }
 
-// ------------------------------------------------------------------ rtk ----
-
-type RtkInstaller = ((mode: "install" | "upgrade", version: string, services: EngineServices) => number) & {
-  readonly prerequisite: (services: EngineServices) => number | undefined
-}
-
-/** RTK toolchain install callback with the shared contextual curl boundary. */
-export function rtkInstall(ctx: Ctx, missingCurlContext: string, missingCurlExit: number): RtkInstaller {
-  const prerequisite = (services: EngineServices): number | undefined => {
-    if (services.deps.probe("curl").state === "present") return undefined
-    services.deps.warnMissing("curl", services.logger, missingCurlContext)
-    return missingCurlExit
-  }
-  const install = (mode: "install" | "upgrade", version: string, services: EngineServices): number => {
-    const blocked = prerequisite(services)
-    if (blocked !== undefined) return blocked
-    const { change, err, verbose, warn } = services.logger
-    const installerRef = version !== "" ? `refs/tags/v${version}` : "refs/heads/master"
-
-    if (mode === "upgrade") verbose(`Upgrading RTK${version !== "" ? ` to ${version}` : ""}...`)
-    else warn(`RTK not found. Installing${version !== "" ? ` ${version}` : ""}...`)
-    const installer = p(tmpdir(), `rtk-install-${process.pid}.sh`)
-    const dl = spawnSync("curl", ["-fsSL", `https://raw.githubusercontent.com/rtk-ai/rtk/${installerRef}/install.sh`, "-o", installer], {
-      stdio: "inherit"
-    })
-    if (dl.error === undefined && dl.status === 0) {
-      spawnSync("bash", [installer], {
-        stdio: "inherit",
-        env: { ...process.env, RTK_VERSION: version !== "" ? `v${version}` : "" }
-      })
-    }
-    rmSync(installer, { force: true })
-    process.env["PATH"] = `${ctx.home}/.local/bin:${ctx.home}/.cargo/bin:${process.env["PATH"] ?? ""}`
-    const installed = services.deps.version("rtk")
-    if (services.deps.probe("rtk").state === "present") {
-      change(`RTK ready (${installed !== "" ? installed : "version unknown"})`)
-      return 0
-    }
-    err("RTK install failed. Install manually: https://github.com/rtk-ai/rtk")
-    return 1
-  }
-  return Object.assign(install, { prerequisite })
-}
-
-export function ensureRtk(ctx: Ctx, missingCurlContext: string, missingCurlExit: number): number {
-  const installer = rtkInstall(ctx, missingCurlContext, missingCurlExit)
-  if (ctx.services.deps.probe("rtk").state === "missing") {
-    const blocked = installer.prerequisite(ctx.services)
-    if (blocked !== undefined) return blocked
-  }
-  return ensure(ctx, "rtk", installer)
-}
-
-function syncRtk(ctx: Ctx, claudeDir: string): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
-  if (ctx.skipRtk) {
-    warn("Skipping RTK (--skip-rtk)")
-    return
-  }
-
-  if (ensureRtk(ctx, "cannot download RTK installer; continuing sync without RTK", 0) !== 0) {
-    warn("RTK bootstrap failed — continuing sync without it")
-  }
-
-  if (ctx.services.deps.probe("rtk").state === "missing") return
-  if (!existsSync(p(claudeDir, "RTK.md"))) {
-    if (ctx.dryRun) {
-      echo("[dry-run] rtk init --global (RTK.md missing; runs before the settings merge, which normalizes rtk's settings rewrite)")
-      return
-    }
-    // Plain command under bash set -e: a nonzero `rtk init` aborts the whole
-    // sync before the success log and before any settings/plugin mutation.
-    const res = spawnSync("rtk", ["init", "--global"], { stdio: "inherit" })
-    if (res.error !== undefined || res.status !== 0) throw new ExitError(res.status ?? 1)
-    change("RTK initialized (RTK.md generated; the following settings merge re-asserts the SoT hooks)")
-  } else if (!ctx.dryRun) {
-    verbose("RTK already initialized")
-  }
-}
-
 // ----------------------------------------------------------- runtime ----
 
 function syncClaudeRuntime(ctx: Ctx, runtime: ClaudeRuntimeState): void {
@@ -448,10 +365,11 @@ const REMOVED_MANIFEST = {
     "env.CLAUDE_CODE_DISABLE_1M_CONTEXT",
     "env.CLAUDE_CODE_FORK_SUBAGENT",
     "env.CLAUDE_CODE_EFFORT_LEVEL",
-    "enabledPlugins.session-relay@docks"
+    "enabledPlugins.session-relay@docks",
+    "hooks.PreToolUse"
   ],
   permissionRules: {
-    allow: ["Write(./)"],
+    allow: ["Write(./)", "Bash(rtk *)"],
     deny: ["Write(**/.env)", "Write(**/.env.local)", "Write(**/secrets/**)"]
   },
   claudeJsonKeys: [] as Array<string>,
@@ -604,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 {
@@ -645,8 +563,8 @@ function nonUserScopeMarketplaces(installedDoc: Json | undefined): Set<string> {
   return marketplaces
 }
 
-function syncPlugins(ctx: Ctx, claudeDir: string): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
+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")
 
@@ -687,7 +605,10 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     const known = readJsonFile(knownMarketplaces)
     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"] ?? "") : ""
-    if (cli(["plugin", "marketplace", "add", repo]).ok) {
+    progress(`Adding marketplace ${mpName}...`)
+    const marketplaceResult = await cli(["plugin", "marketplace", "add", repo])
+    clearProgress()
+    if (marketplaceResult.ok) {
       addedMp++
     } else {
       warn(`Failed to add marketplace: ${mpName} (${repo})`)
@@ -695,17 +616,25 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     }
   }
 
-  // Pass 2 — install SoT-enabled plugins missing at user scope (jq keys[] sorts).
+  // Pass 2 — install SoT-enabled plugins missing at user scope (jq keys[] sorts),
+  // refreshing each source marketplace once so the install resolves a current snapshot.
   let addedPl = 0
   let f2 = 0
-  let refreshed = false
+  const refreshedMarketplaces = new Set<string>()
   for (const pluginId of sortedKeys(sotPlugins)) {
     if (pluginUserScopeInstalled(installedPlugins, pluginId)) continue
-    if (!refreshed) {
-      cli(["plugin", "marketplace", "update"])
-      refreshed = true
+    const separator = pluginId.lastIndexOf("@")
+    const mpName = separator > 0 ? pluginId.slice(separator + 1) : ""
+    if (mpName !== "" && !refreshedMarketplaces.has(mpName)) {
+      progress(`Refreshing marketplace ${mpName}...`)
+      await cli(["plugin", "marketplace", "update", mpName])
+      clearProgress()
+      refreshedMarketplaces.add(mpName)
     }
-    if (cli(["plugin", "install", pluginId]).ok) {
+    progress(`Installing plugin ${pluginId}...`)
+    const installResult = await cli(["plugin", "install", pluginId])
+    clearProgress()
+    if (installResult.ok) {
       addedPl++
     } else {
       warn(`Failed to install plugin: ${pluginId}`)
@@ -717,12 +646,32 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
   const installedDoc = readJsonFile(installedPlugins)
   const installedKeys = installedDoc !== undefined && isObject(installedDoc) ? sortedKeys(installedDoc["plugins"]) : []
   const nonUserMarketplaces = nonUserScopeMarketplaces(installedDoc)
-  // Pass 3 — refresh every installed plugin unless the update command
-  // selected its install-missing-only fast path.
+  // Kit-owned plugin IDs: SoT-declared plus this run's --claude-plugin opt-ins.
+  const kitPluginIds = new Set<string>(Object.keys(sotPlugins))
+  if (ctx.claudePlugins.includes("supabase")) kitPluginIds.add("supabase@claude-plugins-official")
+  if (ctx.claudePlugins.includes("n8n")) kitPluginIds.add("n8n-mcp-skills@n8n-mcp-skills")
+
+  // Kit-owned marketplaces: SoT-declared plus every marketplace those plugins come from.
+  const kitMarketplaces = new Set<string>(Object.keys(sotMarketplaces))
+  for (const pluginId of kitPluginIds) {
+    const separator = pluginId.lastIndexOf("@")
+    if (separator > 0) kitMarketplaces.add(pluginId.slice(separator + 1))
+  }
+
+  // Pass 3 — refresh the kit-owned marketplaces and plugins unless the update
+  // command selected its install-missing-only fast path.
   if (!ctx.skipPluginRefresh) {
-    cli(["plugin", "marketplace", "update"])
-    for (const pluginId of installedKeys) {
-      if (cli(["plugin", "update", pluginId]).out.includes("Successfully updated")) updatedPl++
+    for (const mpName of [...kitMarketplaces].sort(compareCodepoints)) {
+      progress(`Refreshing marketplace ${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 = await cli(["plugin", "update", pluginId, "--scope", "user"])
+      clearProgress()
+      if (updateResult.out.includes("Successfully updated")) updatedPl++
     }
   }
 
@@ -735,7 +684,10 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     for (const pluginId of installedKeys) {
       if (isObject(sotPlugins) && Object.prototype.hasOwnProperty.call(sotPlugins, pluginId)) continue
       if (!pluginUserScopeInstalled(installedPlugins, pluginId)) continue
-      if (cli(["plugin", "uninstall", "-y", "--scope", "user", pluginId]).ok) {
+      progress(`Uninstalling plugin ${pluginId}...`)
+      const uninstallResult = await cli(["plugin", "uninstall", "-y", "--scope", "user", pluginId])
+      clearProgress()
+      if (uninstallResult.ok) {
         removedPl++
       } else {
         warn(`Failed to uninstall plugin: ${pluginId}`)
@@ -748,7 +700,10 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
       if (nonUserMarketplaces.has(mpName)) continue
       const declared = isObject(sotMarketplaces) ? sotMarketplaces[mpName] : undefined
       if (declared !== undefined && declared !== null && declared !== false) continue
-      if (cli(["plugin", "marketplace", "remove", mpName]).ok) {
+      progress(`Removing marketplace ${mpName}...`)
+      const removeResult = await cli(["plugin", "marketplace", "remove", mpName])
+      clearProgress()
+      if (removeResult.ok) {
         removedMp++
       } else {
         warn(`Failed to remove marketplace: ${mpName}`)
@@ -758,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
   }
@@ -775,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"] : {}
@@ -786,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)`)
@@ -809,8 +764,8 @@ function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, userSett
 
 // ------------------------------------------------------ optional plugins ----
 
-function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, marketplaceRepo: string): boolean {
-  const { change, verbose, warn } = ctx.services.logger
+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")
   const mpName = pluginId.slice(pluginId.lastIndexOf("@") + 1)
@@ -820,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
       }
@@ -830,7 +785,10 @@ function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, mar
 
   const wasInstalled = pluginUserScopeInstalled(installedPlugins, pluginId)
   if (!wasInstalled) {
-    if (!cli(["plugin", "install", pluginId]).ok) {
+    progress(`Installing plugin ${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)`)
       warn(`Failed to install optional plugin ${pluginId}`)
       return marketplaceAdded
@@ -843,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
@@ -854,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
 
@@ -874,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
   }
 }
 
@@ -888,8 +846,8 @@ function lspPkg(ctx: Ctx, tool: string, pkg: string): string {
   return v !== "" ? `${pkg}@${v}` : pkg
 }
 
-function syncLspServers(ctx: Ctx): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
+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
   if (enabled === undefined) return
@@ -929,7 +887,10 @@ function syncLspServers(ctx: Ctx): void {
   }
 
   verbose(`Installing LSP servers via npm: ${specs}...`)
-  if (spawnSync("npm", ["install", "-g", ...missing], { stdio: "ignore" }).status === 0) {
+  progress(`Installing LSP servers via npm: ${specs}...`)
+  const installResult = await spawnProcess("npm", ["install", "-g", ...missing], { stdio: "ignore" })
+  clearProgress()
+  if (installResult.exitCode === 0) {
     change(`LSP servers installed (${specs})`)
     ctx.nextStepTriggers.claudeRestart = true
   } else {
@@ -949,12 +910,6 @@ export function claudeSummary(ctx: Ctx, runtime: ClaudeRuntimeState): void {
     } else {
       echo("Hooks:    migration deferred (Bun unavailable; existing hook/statusline settings preserved)")
     }
-    if (ctx.services.deps.probe("rtk").state === "present") {
-      const version = ctx.services.deps.version("rtk")
-      echo(`RTK:      ${version !== "" ? version : "installed"}`)
-    } else {
-      echo("RTK:      not installed")
-    }
     if (ctx.services.deps.probe("claude").state === "present") {
       const installed = readJsonFile(p(claudeDir, "plugins", "installed_plugins.json"))
       const count = installed !== undefined && isObject(installed) && isObject(installed["plugins"]) ? Object.keys(installed["plugins"]).length : 0

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
 
@@ -42,9 +41,9 @@ function ensureBubblewrap(ctx: Ctx): void {
 
   if (ctx.services.deps.probe("bwrap").state === "present") return
 
-  if (ctx.skipRtk) {
+  if (ctx.skipBubblewrap) {
     warn(
-      "bubblewrap not installed (--skip-rtk skips auto-install). Codex may use its bundled helper if user namespaces work; recommended install: sudo apt install -y bubblewrap"
+      "bubblewrap not installed (--skip-bubblewrap skips auto-install). Codex may use its bundled helper if user namespaces work; recommended install: sudo apt install -y bubblewrap"
     )
     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,8 +490,8 @@ function installedPluginIdsFromCli(): Set<string> | undefined {
   return ids
 }
 
-function syncPlugins(ctx: Ctx, sotConfigText: string): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
+async function syncPlugins(ctx: Ctx, sotConfigText: string): Promise<void> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
   if (ctx.dryRun) {
     echo(
       ctx.skipPluginRefresh
@@ -519,7 +519,9 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   const desiredPluginIds = enabledPluginIdsFromText(sotConfigText)
   let pluginIds = desiredPluginIds
   if (ctx.skipPluginRefresh) {
-    const installedPluginIds = installedPluginIdsFromCli()
+    progress("Checking installed Codex plugins...")
+    const installedPluginIds = await installedPluginIdsFromCli()
+    clearProgress()
     if (installedPluginIds === undefined) {
       warn("Codex plugin inventory unavailable — falling back to the full refresh path")
     } else {
@@ -530,9 +532,11 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   let refreshed = 0
   let failed = 0
   for (const pluginId of pluginIds) {
-    const res = spawnSync("codex", ["plugin", "add", pluginId], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
-    const addOut = `${res.stdout ?? ""}${res.stderr ?? ""}`
-    if (res.error === undefined && res.status === 0) {
+    progress(`Updating Codex plugin ${pluginId}...`)
+    const res = await spawnProcess("codex", ["plugin", "add", pluginId], { stdio: ["ignore", "pipe", "pipe"] })
+    clearProgress()
+    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(