docks-kit 0.14.3 → 0.15.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
 
@@ -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(

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

@@ -49,7 +49,7 @@ export interface DependencyLocation {
 
 export interface ProbeExecutor {
   readonly commandExists: (name: string) => boolean
-  readonly capture: (cmd: string, args: ReadonlyArray<string>) => string
+  readonly capture: (cmd: string, args: ReadonlyArray<string>) => Promise<string>
   readonly which: (name: string) => string
 }
 
@@ -60,17 +60,17 @@ export interface DependencySpec {
   /** Platform-correct one-line install command (param injectable for tests). */
   readonly installHint: (platform?: NodeJS.Platform) => string
   readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
-  readonly version?: (exec: ProbeExecutor) => string
-  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => DependencyLocation
-  readonly latest?: (exec: ProbeExecutor) => string
+  readonly version?: (exec: ProbeExecutor) => Promise<string>
+  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => Promise<DependencyLocation>
+  readonly latest?: (exec: ProbeExecutor) => Promise<string>
 }
 
 interface SpecOptions {
   readonly versionArgs?: ReadonlyArray<string>
   readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
-  readonly version?: (exec: ProbeExecutor) => string
-  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => DependencyLocation
-  readonly latest?: (exec: ProbeExecutor) => string
+  readonly version?: (exec: ProbeExecutor) => Promise<string>
+  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => Promise<DependencyLocation>
+  readonly latest?: (exec: ProbeExecutor) => Promise<string>
 }
 
 const spec = (
@@ -99,8 +99,8 @@ const versionProbe = (
   id: string,
   versionArgs: ReadonlyArray<string> = ["--version"],
   parse: (out: string) => string = (out) => out
-): ((exec: ProbeExecutor) => string) =>
-  (exec) => parse(exec.capture(id, versionArgs))
+): ((exec: ProbeExecutor) => Promise<string>) =>
+  async (exec) => parse(await exec.capture(id, versionArgs))
 
 const home = (): string => {
   const envHome = process.env["HOME"]
@@ -144,45 +144,49 @@ const resolveEffectSolutions = (exec: ProbeExecutor): ProbeResult => {
 const versionBunCommand = (exec: ProbeExecutor): string =>
   exec.commandExists("bun") ? "bun" : p(home(), ".bun", "bin", "bun")
 
-const versionEffectSolutions = (exec: ProbeExecutor): string => {
+const versionEffectSolutions = async (exec: ProbeExecutor): Promise<string> => {
   const bun = versionBunCommand(exec)
   if (bun !== "bun" && exec.which(bun) === "") return ""
-  const match = /effect-solutions@([0-9][0-9.]*)/.exec(exec.capture(bun, ["pm", "-g", "ls"]))
+  const match = /effect-solutions@([0-9][0-9.]*)/.exec(await exec.capture(bun, ["pm", "-g", "ls"]))
   return match?.[1] ?? ""
 }
 
-const locateEffectSolutions = (exec: ProbeExecutor): DependencyLocation => {
+const locateEffectSolutions = async (exec: ProbeExecutor): Promise<DependencyLocation> => {
   const strictBun = findBun(exec)
   const pathBun = exec.which("bun")
   const bun = strictBun ?? (pathBun !== "" ? { command: "bun", path: pathBun } : undefined)
   if (bun === undefined) return { path: "", binDir: "" }
-  const globalBin = exec.capture(bun.command, ["pm", "-g", "bin"])
+  const globalBin = await exec.capture(bun.command, ["pm", "-g", "bin"])
   const path = globalBin !== "" ? p(globalBin, "effect-solutions") : ""
   const resolved = path !== "" && exec.which(path) !== "" ? path : ""
   return { path: resolved, binDir: globalBin }
 }
 
-const npmGlobalCache = new WeakMap<ProbeExecutor, { [k: string]: string }>()
+const npmGlobalCache = new WeakMap<ProbeExecutor, Promise<{ [k: string]: string }>>()
 
-const npmGlobalVersions = (exec: ProbeExecutor): { [k: string]: string } => {
+const npmGlobalVersions = (exec: ProbeExecutor): Promise<{ [k: string]: string }> => {
   const hit = npmGlobalCache.get(exec)
   if (hit !== undefined) return hit
-  const out: { [k: string]: string } = {}
-  if (exec.commandExists("npm")) {
-    const doc = parseJson(exec.capture("npm", ["ls", "-g", "--depth=0", "--json"]))
-    const deps = doc !== undefined && isObject(doc) && isObject(doc["dependencies"]) ? doc["dependencies"] : {}
-    for (const [name, value] of Object.entries(deps)) {
-      if (isObject(value) && typeof value["version"] === "string") out[name] = value["version"]
+  const pending = (async (): Promise<{ [k: string]: string }> => {
+    const out: { [k: string]: string } = {}
+    if (exec.commandExists("npm")) {
+      const doc = parseJson(await exec.capture("npm", ["ls", "-g", "--depth=0", "--json"]))
+      const deps = doc !== undefined && isObject(doc) && isObject(doc["dependencies"]) ? doc["dependencies"] : {}
+      for (const [name, value] of Object.entries(deps)) {
+        if (isObject(value) && typeof value["version"] === "string") out[name] = value["version"]
+      }
     }
-  }
-  npmGlobalCache.set(exec, out)
-  return out
+    return out
+  })()
+  npmGlobalCache.set(exec, pending)
+  return pending
 }
 
-const versionNpmGlobal = (pkg: string) => (exec: ProbeExecutor): string => npmGlobalVersions(exec)[pkg] ?? ""
+const versionNpmGlobal = (pkg: string) => async (exec: ProbeExecutor): Promise<string> =>
+  (await npmGlobalVersions(exec))[pkg] ?? ""
 
-const latestNpm = (id: "effect-solutions") => (exec: ProbeExecutor): string =>
-  exec.commandExists("npm") ? exec.capture("npm", ["view", id, "version"]) : ""
+const latestNpm = (id: "effect-solutions") => async (exec: ProbeExecutor): Promise<string> =>
+  exec.commandExists("npm") ? await exec.capture("npm", ["view", id, "version"]) : ""
 
 export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which }
 
@@ -230,7 +234,7 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     {
       resolve: resolveBun,
       version: (exec) => exec.capture(versionBunCommand(exec), ["--version"]),
-      locate: (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
+      locate: async (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
     }
   ),
   bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)", {
@@ -277,21 +281,25 @@ export function resolveDependency(
   return (specification.resolve ?? pathProbe(specification.id))(exec, platform)
 }
 
-export function resolveVersion(specification: DependencySpec, exec: ProbeExecutor): string {
+export async function resolveVersion(specification: DependencySpec, exec: ProbeExecutor): Promise<string> {
   if (resolveDependency(specification, exec).state !== "present") return ""
-  return (specification.version ?? versionProbe(specification.id, specification.versionArgs))(exec)
+  return await (specification.version ?? versionProbe(specification.id, specification.versionArgs))(exec)
 }
 
-export function resolveLocation(
+export async function resolveLocation(
   specification: DependencySpec,
   exec: ProbeExecutor,
   platform: NodeJS.Platform = rawPlatform()
-): DependencyLocation {
-  if (specification.locate !== undefined) return specification.locate(exec, platform)
+): Promise<DependencyLocation> {
+  if (specification.locate !== undefined) return await specification.locate(exec, platform)
   const result = resolveDependency(specification, exec, platform)
   return { path: result.state === "present" ? (result.path ?? exec.which(specification.id)) : "", binDir: "" }
 }
 
-export function resolvePath(specification: DependencySpec, exec: ProbeExecutor, platform?: NodeJS.Platform): string {
-  return resolveLocation(specification, exec, platform).path
+export async function resolvePath(
+  specification: DependencySpec,
+  exec: ProbeExecutor,
+  platform?: NodeJS.Platform
+): Promise<string> {
+  return (await resolveLocation(specification, exec, platform)).path
 }

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

@@ -3,7 +3,7 @@
  * the intended binary with deterministic argv, and capture() mirrors command
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
-import { spawnSync } from "node:child_process"
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
 import { accessSync, chmodSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { delimiter, isAbsolute, join } from "node:path"
 
@@ -12,10 +12,66 @@ export function p(...parts: Array<string>): string {
   return parts.join("/")
 }
 
-export function capture(cmd: string, args: ReadonlyArray<string>): string {
-  const res = spawnSync(cmd, args as Array<string>, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
-  if (res.error !== undefined || res.status !== 0) return ""
-  return (res.stdout ?? "").replace(/[\r\n]+$/, "")
+export interface AsyncProcessResult {
+  readonly exitCode: number | null
+  readonly stdout: string
+  readonly stderr: string
+  readonly error?: Error
+}
+
+export interface AsyncProcessOptions {
+  readonly stdio?: SpawnOptions["stdio"]
+}
+
+export function spawnProcess(
+  cmd: string,
+  args: ReadonlyArray<string>,
+  options: AsyncProcessOptions = {}
+): Promise<AsyncProcessResult> {
+  const { promise, resolve } = Promise.withResolvers<AsyncProcessResult>()
+  let child: ChildProcess
+  try {
+    child = spawn(cmd, [...args], { stdio: options.stdio ?? ["ignore", "pipe", "ignore"] })
+  } catch (cause) {
+    const error = cause instanceof Error ? cause : new Error(String(cause))
+    resolve({ exitCode: null, stdout: "", stderr: "", error })
+    return promise
+  }
+  let stdout = ""
+  let stderr = ""
+  let error: Error | undefined
+
+  if (child.stdout !== null) {
+    child.stdout.setEncoding("utf8")
+    child.stdout.on("data", (chunk: string) => {
+      stdout += chunk
+    })
+    child.stdout.on("error", (cause) => {
+      error ??= cause
+    })
+  }
+  if (child.stderr !== null) {
+    child.stderr.setEncoding("utf8")
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk
+    })
+    child.stderr.on("error", (cause) => {
+      error ??= cause
+    })
+  }
+  child.once("error", (cause) => {
+    error ??= cause
+  })
+  child.once("close", (exitCode) => {
+    resolve({ exitCode, stdout, stderr, ...(error !== undefined ? { error } : {}) })
+  })
+  return promise
+}
+
+export async function capture(cmd: string, args: ReadonlyArray<string>): Promise<string> {
+  const res = await spawnProcess(cmd, args, { stdio: ["ignore", "pipe", "ignore"] })
+  if (res.error !== undefined || res.exitCode !== 0) return ""
+  return res.stdout.replace(/[\r\n]+$/, "")
 }
 
 /** `command -v` — resolve an executable name on PATH. */

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

@@ -9,11 +9,13 @@ import { p } from "./exec"
 import { homedir } from "node:os"
 
 import { kitHome } from "../kitHome"
+import { payloadText } from "../payload"
 import { makeEngineServices, type EngineServices, type Logger } from "./services"
+import type { TerminalLease } from "./logger"
 import type { BunRuntimeState } from "./bun"
 import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
-import { skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync"
+import { normalizeManifest, skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
 import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
 
@@ -24,6 +26,54 @@ export type ModifierFlag =
   | "--codex-model"
   | "--codex-effort"
 
+export type SyncConcurrency = 1 | 2 | 3
+export type SyncTask<T> = () => Promise<T>
+
+/**
+ * Run input-ordered tasks with bounded overlap. Once one task rejects, queued
+ * tasks stay queued while already-started tasks drain; the earliest rejection
+ * in input order is then propagated.
+ */
+export async function runBounded<T>(
+  tasks: ReadonlyArray<SyncTask<T>>,
+  concurrency: SyncConcurrency
+): Promise<Array<T>> {
+  const results = new Array<T>(tasks.length)
+  const failures = new Map<number, unknown>()
+  let nextIndex = 0
+  let stopped = false
+
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, async () => {
+    for (;;) {
+      if (stopped || nextIndex >= tasks.length) return
+      const index = nextIndex
+      nextIndex += 1
+      try {
+        results[index] = await tasks[index]!()
+      } catch (error) {
+        failures.set(index, error)
+        stopped = true
+      }
+    }
+  })
+  await Promise.all(workers)
+
+  for (let index = 0; index < tasks.length; index += 1) {
+    if (failures.has(index)) throw failures.get(index)
+  }
+  return results
+}
+
+export function syncConcurrencyForManifest(
+  configured: SyncConcurrency,
+  manifest: string,
+  claudeSelected: boolean,
+  skillsSelected: boolean
+): SyncConcurrency {
+  if (!claudeSelected || !skillsSelected || normalizeManifest(manifest).length === 0) return configured
+  return 1
+}
+
 export interface Ctx {
   readonly repoDir: string
   readonly home: string
@@ -47,7 +97,9 @@ export interface Ctx {
   modifierFlags?: Set<ModifierFlag>
   /** Injected capability seam (logger/deps/platform) — see services.ts. */
   readonly services: EngineServices
-  bunRuntime?: BunRuntimeState
+  syncConcurrency: SyncConcurrency
+  terminalLease?: TerminalLease
+  bunRuntime?: Promise<BunRuntimeState>
   targetFilterSet: boolean
   syncClaude: boolean
   syncCodex: boolean
@@ -85,6 +137,7 @@ function makeCtx(services: EngineServices): Ctx {
     codexModel: env["CODEX_MODEL"] ?? "",
     codexEffort: "",
     modifierFlags: new Set(),
+    syncConcurrency: 3,
     services,
     targetFilterSet: false,
     syncClaude: false,
@@ -94,40 +147,94 @@ function makeCtx(services: EngineServices): Ctx {
   }
 }
 
-function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
-  const { clearProgress, echo, progress } = ctx.services.logger
+async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
+  const { acquireTerminal, echo, err } = ctx.services.logger
   parseArgs(ctx, args)
   validateModifierFlags(ctx)
 
-  const claudeRan = ctx.syncClaude
-  let claudeRuntime: ClaudeRuntimeState | undefined
-  if (claudeRan) {
-    progress("Syncing Claude...")
-    try {
-      claudeRuntime = claudeSync(ctx)
-    } finally {
-      clearProgress()
-    }
+  const configuredConcurrency = process.env["DOCKS_KIT_SYNC_CONCURRENCY"]
+  if (configuredConcurrency === undefined || configuredConcurrency === "") {
+    ctx.syncConcurrency = 3
+  } else if (
+    configuredConcurrency === "1" ||
+    configuredConcurrency === "2" ||
+    configuredConcurrency === "3"
+  ) {
+    ctx.syncConcurrency = Number(configuredConcurrency) as SyncConcurrency
+  } else {
+    err("DOCKS_KIT_SYNC_CONCURRENCY must be 1, 2, or 3")
+    throw new ExitError(2)
   }
 
-  const codexRan = ctx.syncCodex
-  if (codexRan) {
-    progress("Syncing Codex...")
-    try {
-      codexSync(ctx)
-    } finally {
-      clearProgress()
-    }
+  type PipelineResult =
+    | { readonly kind: "claude"; readonly runtime: ClaudeRuntimeState }
+    | { readonly kind: "codex" }
+    | { readonly kind: "skills"; readonly state: SkillsState }
+  interface SelectedPipeline {
+    readonly name: string
+    readonly run: SyncTask<PipelineResult>
   }
 
-  let skillsState: SkillsState | undefined
+  const selected: Array<SelectedPipeline> = []
+  if (ctx.syncClaude) {
+    selected.push({
+      name: "Claude",
+      run: async () => ({ kind: "claude", runtime: await claudeSync(ctx) })
+    })
+  }
+  if (ctx.syncCodex) {
+    selected.push({
+      name: "Codex",
+      run: async () => {
+        await codexSync(ctx)
+        return { kind: "codex" }
+      }
+    })
+  }
   if (ctx.syncAgents) {
-    progress("Syncing skills...")
-    try {
-      skillsState = skillsSync(ctx)
-    } finally {
-      clearProgress()
-    }
+    selected.push({
+      name: "skills",
+      run: async () => ({ kind: "skills", state: await skillsSync(ctx) })
+    })
+  }
+
+  // A populated skills manifest deploys with `-a claude-code codex`, and symlink healing also writes into Claude's tree.
+  ctx.syncConcurrency = syncConcurrencyForManifest(
+    ctx.syncConcurrency,
+    payloadText("SoT/.agents/skills.txt"),
+    ctx.syncClaude,
+    ctx.syncAgents
+  )
+
+  const remaining = new Set(selected.map(({ name }) => name))
+  const lease = acquireTerminal(`Syncing ${[...remaining].join(", ")}...`)
+  ctx.terminalLease = lease
+  let results: Array<PipelineResult>
+  try {
+    const tasks = selected.map(
+      ({ name, run }): SyncTask<PipelineResult> =>
+        async () => {
+          try {
+            return await run()
+          } finally {
+            remaining.delete(name)
+            if (remaining.size > 0) lease.update(`Syncing ${[...remaining].join(", ")}...`)
+          }
+        }
+    )
+    results = await runBounded(tasks, ctx.syncConcurrency)
+  } finally {
+    lease.release()
+    ctx.terminalLease = undefined
+  }
+
+  const claudeRan = ctx.syncClaude
+  const codexRan = ctx.syncCodex
+  let claudeRuntime: ClaudeRuntimeState | undefined
+  let skillsState: SkillsState | undefined
+  for (const result of results) {
+    if (result.kind === "claude") claudeRuntime = result.runtime
+    else if (result.kind === "skills") skillsState = result.state
   }
 
   echo("")
@@ -150,7 +257,7 @@ function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
 }
 
 
-export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineServices): number {
+export async function runEngineNative(argv: ReadonlyArray<string>, services?: EngineServices): Promise<number> {
   let ctx!: Ctx
   const baseServices = services ?? makeEngineServices()
   const baseLogger = baseServices.logger
@@ -163,7 +270,8 @@ export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineSe
     },
     warn: (msg) => baseLogger.warn(msg),
     err: (msg) => baseLogger.err(msg),
-    echo: (line) => baseLogger.echo(line)
+    echo: (line) => baseLogger.echo(line),
+    acquireTerminal: (message) => baseLogger.acquireTerminal(message)
   }
   const runServices: EngineServices = {
     logger,
@@ -176,11 +284,11 @@ export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineSe
       case "model":
         return modeModel(ctx, argv.slice(1))
       case "toolchain":
-        return modeToolchain(ctx, argv.slice(1))
+        return await modeToolchain(ctx, argv.slice(1))
       case "sync":
-        return engineSync(ctx, argv.slice(1))
+        return await engineSync(ctx, argv.slice(1))
       default:
-        return engineSync(ctx, argv)
+        return await engineSync(ctx, argv)
     }
   } catch (e) {
     if (e instanceof ExitError) return e.code