docks-kit 0.14.3 → 0.14.4

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

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

@@ -1,11 +1,22 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+
 /**
- * Leveled stderr logger, transient progress writer, and stdout data writer —
- * the Output Policy contract in DESIGN.md. Filtering is explicit and
+ * Leveled stderr logger, one run-scoped terminal lease, and stdout data
+ * writer — the Output Policy contract in DESIGN.md. Filtering is explicit and
  * synchronous: engine code is imperative, so fiber-scoped Effect log levels
  * cannot see these writes. Transient progress is active only through an
  * injected progress sink or an interactive stderr. The prefixes and ANSI codes
  * are stable golden surface; the level controls visibility only.
  */
+export interface TerminalLease {
+  /** Replace the coordinator-owned transient line. */
+  readonly update: (message: string) => void
+  /** Serialize terminal input owners and suspend transient redraw while held. */
+  readonly withExclusive: <T>(action: () => T | Promise<T>) => Promise<T>
+  /** Clear coordinator progress and return ownership to ordinary progress calls. */
+  readonly release: () => void
+}
+
 
 export interface Logger {
   /** `[ok]` green — an operation actually mutated something. Always visible. */
@@ -20,6 +31,8 @@ export interface Logger {
   readonly err: (msg: string) => void
   /** stdout data line (dry-run report, summary, usage) — never filtered. */
   readonly echo: (line: string) => void
+  /** Acquire the run-scoped coordinator lease for terminal progress and input. */
+  readonly acquireTerminal: (message: string) => TerminalLease
 }
 
 export interface LoggerSinks {
@@ -63,36 +76,123 @@ export function makeLogger(sinks: LoggerSinks): Logger {
       ? (chunk: string) => writeIgnoringEpipe(process.stderr, chunk)
       : undefined)
   let progressPending = false
+  let activeLease: TerminalLease | undefined
+  let exclusiveActive = false
+  const exclusiveContext = new AsyncLocalStorage<{ active: boolean }>()
+  const durableBuffer: Array<() => void> = []
 
-  const clearProgress = (): void => {
+
+  const eraseProgress = (): void => {
     if (!progressPending || progressWrite === undefined) return
     progressWrite("\r\x1b[2K")
     progressPending = false
   }
+  const drawProgress = (message: string): void => {
+    if (progressWrite === undefined) return
+    progressWrite(`\r\x1b[2K\x1b[2m${message}\x1b[0m`)
+    progressPending = true
+  }
+  const clearProgress = (): void => {
+    if (activeLease !== undefined) return
+    eraseProgress()
+  }
+  const writeDurable = (write: () => void): void => {
+    if (exclusiveActive) {
+      durableBuffer.push(write)
+      return
+    }
+    eraseProgress()
+    write()
+  }
+  const flushDurable = (): void => {
+    let firstError: unknown
+    while (durableBuffer.length > 0) {
+      for (const write of durableBuffer.splice(0)) {
+        try {
+          write()
+        } catch (error) {
+          firstError ??= error
+        }
+      }
+    }
+    if (firstError !== undefined) throw firstError
+  }
   const ok = (msg: string): void => {
-    clearProgress()
-    errWrite(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`)
+    writeDurable(() => errWrite(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`))
   }
+
+  const acquireTerminal = (message: string): TerminalLease => {
+    if (activeLease !== undefined) throw new Error("terminal lease already acquired")
+
+    let released = false
+    let coordinatorMessage = message
+    let exclusiveTail = Promise.resolve()
+    let exclusivePending = 0
+    const lease: TerminalLease = {
+      update: (nextMessage) => {
+        if (released) return
+        coordinatorMessage = nextMessage
+        if (exclusivePending === 0) drawProgress(coordinatorMessage)
+      },
+      withExclusive: async <T>(action: () => T | Promise<T>): Promise<T> => {
+        if (exclusiveContext.getStore()?.active === true) {
+          throw new Error("terminal lease withExclusive cannot be re-entered")
+        }
+        if (released) return await action()
+        exclusivePending += 1
+        const previous = exclusiveTail
+        let unlock!: () => void
+        exclusiveTail = new Promise<void>((resolve) => {
+          unlock = resolve
+        })
+        await previous
+        eraseProgress()
+        exclusiveActive = true
+        const owner = { active: true }
+        try {
+          return await exclusiveContext.run(owner, action)
+        } finally {
+          owner.active = false
+          try {
+            flushDurable()
+          } finally {
+            exclusiveActive = false
+            exclusivePending -= 1
+            unlock()
+            if (!released && exclusivePending === 0) drawProgress(coordinatorMessage)
+          }
+        }
+      },
+      release: () => {
+        if (released) return
+        released = true
+        if (activeLease === lease) activeLease = undefined
+        eraseProgress()
+      }
+    }
+    activeLease = lease
+    drawProgress(coordinatorMessage)
+    return lease
+  }
+
   return {
     change: ok,
     verbose: ok,
     progress: (msg) => {
-      if (progressWrite === undefined) return
-      progressWrite(`\r\x1b[2K\x1b[2m${msg}\x1b[0m`)
-      progressPending = true
+      if (activeLease !== undefined) return
+      drawProgress(msg)
     },
     clearProgress,
     warn: (msg) => {
-      clearProgress()
-      errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`)
+      writeDurable(() => errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`))
     },
     err: (msg) => {
-      clearProgress()
+      eraseProgress()
       errWrite(`\x1b[1;31m[err]\x1b[0m ${msg}\n`)
     },
     echo: (line) => {
-      clearProgress()
-      outWrite(`${line}\n`)
-    }
+      writeDurable(() => outWrite(`${line}\n`))
+    },
+    acquireTerminal
   }
 }

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

@@ -108,7 +108,7 @@ function tomlModelText(text: string): string {
   return ""
 }
 
-export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
+export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
   const { err } = ctx.services.logger
   const words = args.filter((a) => !a.startsWith("--"))
   const op = words[0] ?? args[0] ?? "check"
@@ -121,7 +121,7 @@ export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
   }
 
   if (op === "check") {
-    report(ctx)
+    await report(ctx)
     return 0
   }
   if (op !== "ensure") {
@@ -134,9 +134,9 @@ export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
   }
   switch (tool) {
     case "bun":
-      return bunBootstrap(ctx, ctx.services).kind === "ready" ? 0 : 1
+      return (await bunBootstrap(ctx, ctx.services)).kind === "ready" ? 0 : 1
     case "effect-solutions":
-      return ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
+      return await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
     default:
       err("toolchain ensure supports managed tools only (bun, effect-solutions)")
       return 2