docks-kit 0.14.2 → 0.14.4

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

@@ -1,35 +1,198 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+
 /**
- * Leveled stderr logger + 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. The prefixes and
- * ANSI codes are stable golden surface; the level controls visibility only.
+ * 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. */
   readonly change: (msg: string) => void
+  /** Dim, transient single-line status for blocking work. */
+  readonly progress: (msg: string) => void
+  /** Erase a pending transient status line. */
+  readonly clearProgress: () => void
   /** `[ok]` green — status-quo confirmation; visible only with verbosity on. */
   readonly verbose: (msg: string) => void
   readonly warn: (msg: string) => void
   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 {
   readonly stderr?: (chunk: string) => void
+  readonly progress?: (chunk: string) => void
   readonly stdout?: (chunk: string) => void
 }
 
+interface WritableStreamLike {
+  write: (chunk: string) => unknown
+  on?: (event: "error", listener: (error: unknown) => void) => unknown
+}
+
+const epipeGuarded = new WeakSet<WritableStreamLike>()
+
+/**
+ * A downstream reader may close the pipe early (`docks-kit toolchain check |
+ * head`). That is a normal end of consumption, not a CLI failure, so both the
+ * synchronous throw and the asynchronous error event are ignored for EPIPE.
+ */
+export function writeIgnoringEpipe(stream: WritableStreamLike, chunk: string): void {
+  if (!epipeGuarded.has(stream)) {
+    epipeGuarded.add(stream)
+    stream.on?.("error", (error) => {
+      if ((error as NodeJS.ErrnoException | null)?.code !== "EPIPE") throw error
+    })
+  }
+  try {
+    stream.write(chunk)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code !== "EPIPE") throw error
+  }
+}
+
 export function makeLogger(sinks: LoggerSinks): Logger {
-  const errWrite = sinks.stderr ?? ((chunk: string) => void process.stderr.write(chunk))
-  const outWrite = sinks.stdout ?? ((chunk: string) => void process.stdout.write(chunk))
-  const ok = (msg: string): void => errWrite(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`)
+  const errWrite = sinks.stderr ?? ((chunk: string) => writeIgnoringEpipe(process.stderr, chunk))
+  const outWrite = sinks.stdout ?? ((chunk: string) => writeIgnoringEpipe(process.stdout, chunk))
+  const progressWrite =
+    sinks.progress ??
+    (sinks.stderr === undefined && process.stderr.isTTY === true
+      ? (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 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 => {
+    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,
-    warn: (msg) => errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`),
-    err: (msg) => errWrite(`\x1b[1;31m[err]\x1b[0m ${msg}\n`),
-    echo: (line) => outWrite(`${line}\n`)
+    progress: (msg) => {
+      if (activeLease !== undefined) return
+      drawProgress(msg)
+    },
+    clearProgress,
+    warn: (msg) => {
+      writeDurable(() => errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`))
+    },
+    err: (msg) => {
+      eraseProgress()
+      errWrite(`\x1b[1;31m[err]\x1b[0m ${msg}\n`)
+    },
+    echo: (line) => {
+      writeDurable(() => outWrite(`${line}\n`))
+    },
+    acquireTerminal
   }
 }

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

@@ -11,9 +11,8 @@ import { syncCodexModel } from "./codexToml"
 import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
-import { ensureRtk } from "./claudeSync"
 import { bunBootstrap } from "./bun"
-import { agentBrowserInstall, effectSolutionsInstall } from "./skillsSync"
+import { effectSolutionsInstall } from "./skillsSync"
 import { ensure, report } from "./toolchain"
 
 export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
@@ -109,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"
@@ -122,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,16 +133,12 @@ export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
     return 2
   }
   switch (tool) {
-    case "rtk":
-      return ensureRtk(ctx, "cannot download RTK installer; toolchain ensure rtk aborted", 1)
     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))
-    case "agent-browser":
-      return ensure(ctx, "agent-browser", agentBrowserInstall)
+      return await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
     default:
-      err("toolchain ensure supports managed tools only (rtk, bun, effect-solutions, agent-browser)")
+      err("toolchain ensure supports managed tools only (bun, effect-solutions)")
       return 2
   }
 }

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

@@ -50,7 +50,7 @@ function usage(ctx: Ctx): void {
   echo(
     "  --prune           uninstall kit-managed installs not in SoT (plugins, marketplaces, skills in SoT/.agents/skills.txt)"
   )
-  echo("  --skip-rtk        skip optional tool bootstrap (RTK, bubblewrap)")
+  echo("  --skip-bubblewrap skip optional bubblewrap bootstrap (Codex Linux sandbox)")
   echo("  --skip-plugin-refresh  install missing plugins but skip refresh-only updates")
   echo("  --yes             auto-accept toolchain prompts (containers/CI)")
   echo("  --verbose         also print no-op confirmations (already in sync, up to date, left as-is)")
@@ -147,8 +147,8 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
       case "--dry-run":
         ctx.dryRun = true
         continue
-      case "--skip-rtk":
-        ctx.skipRtk = true
+      case "--skip-bubblewrap":
+        ctx.skipBubblewrap = true
         continue
       case "--skip-plugin-refresh":
         ctx.skipPluginRefresh = true
@@ -217,8 +217,8 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
       case "--n8n":
         err("--n8n was renamed to --claude-plugin=n8n")
         throw new ExitError(2)
-      case "--no-rtk":
-        err("--no-rtk was renamed to --skip-rtk")
+      case "--skip-rtk":
+        err("--skip-rtk was renamed to --skip-bubblewrap")
         throw new ExitError(2)
       case "-h":
       case "--help":

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

@@ -26,10 +26,10 @@ export type { Logger } from "./logger"
 export interface DependencyManager {
   readonly spec: (id: ToolId) => DependencySpec
   readonly probe: (id: ToolId) => ProbeResult
-  readonly version: (id: ToolId) => string
-  readonly path: (id: ToolId) => string
-  readonly location: (id: ToolId) => DependencyLocation
-  readonly latest: (id: ToolId) => string
+  readonly version: (id: ToolId) => Promise<string>
+  readonly path: (id: ToolId) => Promise<string>
+  readonly location: (id: ToolId) => Promise<DependencyLocation>
+  readonly latest: (id: ToolId) => Promise<string>
   readonly warnMissing: (id: ToolId, logger: Logger, context?: string) => void
 }
 
@@ -73,7 +73,7 @@ export const makeDependencyManager = (
     version: (id) => resolveVersion(DEPENDENCIES[id], exec),
     path: (id) => resolvePath(DEPENDENCIES[id], exec, platform.raw()),
     location: (id) => resolveLocation(DEPENDENCIES[id], exec, platform.raw()),
-    latest: (id) => DEPENDENCIES[id].latest?.(exec) ?? "",
+    latest: (id) => DEPENDENCIES[id].latest?.(exec) ?? Promise.resolve(""),
     warnMissing: (id, logger, context) => {
       if (warned.has(id)) return
       warned.add(id)

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

@@ -1,12 +1,11 @@
 /**
  * EngineNative `sync agents` pipeline: universal-skill bootstrap
  * (`npx skills@<pin> add`), Claude symlink healing, --prune reconcile against
- * the kit-managed snapshot, agent-browser/effect-solutions toolchain callbacks,
- * and the snapshot write.
+ * the kit-managed snapshot, the effect-solutions toolchain callback, and the
+ * snapshot write.
  */
-import { spawnSync } from "node:child_process"
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync } from "node:fs"
-import { p, writeFileIfChanged } from "./exec"
+import { p, spawnProcess, writeFileIfChanged } from "./exec"
 import { bunBootstrap } from "./bun"
 import type { Ctx } from "./index"
 import { compareCodepoints } from "./jq"
@@ -18,7 +17,7 @@ export interface SkillsState {
   present: number
 }
 
-export function skillsSync(ctx: Ctx): SkillsState {
+export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
   const state: SkillsState = { present: 0 }
   const skillsDir = p(ctx.agentsDir, "skills")
   const manifest = payloadText("SoT/.agents/skills.txt")
@@ -26,10 +25,9 @@ export function skillsSync(ctx: Ctx): SkillsState {
 
   if (!ctx.dryRun) mkdirSync(skillsDir, { recursive: true })
 
-  syncUniversal(ctx, state, skillsDir, manifest)
-  if (ctx.prune) reconcileRemovals(ctx, manifest, snapshot)
-  syncAgentBrowserCli(ctx, manifest)
-  syncEffectSolutionsCli(ctx)
+  await syncUniversal(ctx, state, skillsDir, manifest)
+  if (ctx.prune) await reconcileRemovals(ctx, manifest, snapshot)
+  await syncEffectSolutionsCli(ctx)
   updateSnapshot(ctx, manifest, snapshot)
   return state
 }
@@ -56,8 +54,8 @@ function readSlugs(file: string): Array<string> {
   return existsSync(file) ? normalizeManifest(readFileSync(file, "utf8")) : []
 }
 
-function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest: string): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
+async function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest: string): Promise<void> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
   if (ctx.services.deps.probe("npx").state === "missing") {
     ctx.services.deps.warnMissing("npx", ctx.services.logger, "skipping universal skills bootstrap")
     return
@@ -87,10 +85,12 @@ function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest
       continue
     }
 
-    const res = spawnSync("npx", ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"], {
+    progress(`Installing universal skill ${slug}...`)
+    const res = await spawnProcess("npx", ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"], {
       stdio: "ignore"
     })
-    if (res.error === undefined && res.status === 0) {
+    clearProgress()
+    if (res.error === undefined && res.exitCode === 0) {
       added++
     } else {
       warn(`Failed to install universal skill: ${slug}`)
@@ -217,69 +217,29 @@ function linkOrCopyWithWarnings(target: string, link: string, services: EngineSe
 
 // ------------------------------------------------- toolchain callbacks ----
 
-/** skills::_agent_browser_install. */
-export function agentBrowserInstall(mode: "install" | "upgrade", version: string, services: EngineServices): number {
-  const { change, verbose, warn } = services.logger
-  const verb = mode === "upgrade" ? "Upgrading" : "Installing"
-  const pkg = version !== "" ? `agent-browser@${version}` : "agent-browser"
-  const installFlags = services.platform.isLinux() ? ["--with-deps"] : []
-
-  verbose(`${verb} agent-browser CLI via npm${version !== "" ? ` (pinned ${version})` : ""}...`)
-  if (spawnSync("npm", ["install", "-g", pkg], { stdio: "ignore" }).status !== 0) {
-    warn(`npm install -g ${pkg} failed. Try manually: npm install -g ${pkg}`)
-    return 1
-  }
-
-  if (mode === "install") {
-    warn("Downloading Chrome for Testing (~175 MB; sudo may be requested for system libs on Linux)...")
-    if (spawnSync("agent-browser", ["install", ...installFlags], { stdio: "inherit" }).status !== 0) {
-      warn(`agent-browser install failed. Re-run manually: agent-browser install ${installFlags.join(" ")}`)
-      return 1
-    }
-  }
-  const out = services.deps.version("agent-browser")
-  const fields = (out.split("\n")[0] ?? "").trim().split(/[ \t]+/)
-  const version2 = out !== "" ? fields[fields.length - 1] ?? "version unknown" : "version unknown"
-  change(`agent-browser CLI ready (${version2})`)
-  return 0
-}
-
-function syncAgentBrowserCli(ctx: Ctx, manifest: string): void {
-  const { warn } = ctx.services.logger
-  if (!manifest.split("\n").includes("vercel-labs/agent-browser")) return
-
-  if (ctx.services.deps.probe("npm").state === "missing") {
-    if (!ctx.dryRun) {
-      ctx.services.deps.warnMissing("npm", ctx.services.logger, "cannot auto-install agent-browser CLI; re-run sync after installing")
-    }
-    return
-  }
-
-  if (ensure(ctx, "agent-browser", agentBrowserInstall) !== 0) {
-    warn("agent-browser bootstrap failed — continuing sync")
-  }
-}
-
 /** skills::_effect_solutions_install. */
 export function effectSolutionsInstall(
   ctx: Ctx
-): (mode: "install" | "upgrade", version: string, services: EngineServices) => number {
-  return (mode, version, services) => {
-    const { change, verbose, warn } = services.logger
+): (mode: "install" | "upgrade", version: string, services: EngineServices) => Promise<number> {
+  return async (mode, version, services) => {
+    const { change, clearProgress, progress, verbose, warn } = services.logger
     const verb = mode === "upgrade" ? "Upgrading" : "Installing"
     const pkg = `effect-solutions@${version !== "" ? version : "latest"}`
 
-    const bunState = bunBootstrap(ctx, services)
+    const bunState = await bunBootstrap(ctx, services)
     if (bunState.kind === "deferred") return 1
     const bun = bunState.executable
 
     verbose(`${verb} effect-solutions CLI via bun${version !== "" ? ` (pinned ${version})` : ""}...`)
-    if (spawnSync(bun, ["add", "-g", pkg], { stdio: "ignore" }).status !== 0) {
+    progress(`${verb} effect-solutions CLI...`)
+    const installResult = await spawnProcess(bun, ["add", "-g", pkg], { stdio: "ignore" })
+    clearProgress()
+    if (installResult.exitCode !== 0) {
       warn(`bun add -g ${pkg} failed. Try manually: bun add -g ${pkg}`)
       return 1
     }
 
-    const location = services.deps.location("effect-solutions")
+    const location = await services.deps.location("effect-solutions")
     const gbin = location.binDir
     if (location.path !== "") {
       mkdirSync(p(ctx.home, ".local", "bin"), { recursive: true })
@@ -293,19 +253,22 @@ export function effectSolutionsInstall(
   }
 }
 
-function syncEffectSolutionsCli(ctx: Ctx): void {
-  const { warn } = ctx.services.logger
+async function syncEffectSolutionsCli(ctx: Ctx): Promise<void> {
+  const { clearProgress, progress, warn } = ctx.services.logger
   if (!/"effect-kit@docks"[ \t]*:[ \t]*true/.test(payloadText("SoT/.claude/settings.json"))) return
 
-  if (ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx)) !== 0) {
+  progress("Checking effect-solutions CLI...")
+  const result = await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
+  clearProgress()
+  if (result !== 0) {
     warn("effect-solutions bootstrap failed — continuing sync")
   }
 }
 
 // ----------------------------------------------------- prune + snapshot ----
 
-function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
-  const { change, echo, warn } = ctx.services.logger
+async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): Promise<void> {
+  const { change, clearProgress, echo, progress, warn } = ctx.services.logger
   if (!existsSync(snapshot)) {
     if (ctx.dryRun) {
       echo(
@@ -325,10 +288,12 @@ function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
       echo(`[dry-run] kit-managed skill no longer in SoT — would remove: ${base}`)
       continue
     }
-    const res = spawnSync("npx", ["--yes", skillsCli(ctx), "remove", "--global", base, "-y"], {
+    progress(`Removing universal skill ${base}...`)
+    const res = await spawnProcess("npx", ["--yes", skillsCli(ctx), "remove", "--global", base, "-y"], {
       stdio: "ignore"
     })
-    if (res.error === undefined && res.status === 0) {
+    clearProgress()
+    if (res.error === undefined && res.exitCode === 0) {
       removed++
     } else {
       warn(`Failed to remove kit-managed skill: ${base}`)

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

@@ -10,7 +10,11 @@ import { compareCodepoints, isObject, parseJson, type Json } from "./jq"
 import type { EngineServices } from "./services"
 import { payloadText } from "../payload"
 
-type InstallFn = (mode: "install" | "upgrade", version: string, services: EngineServices) => number
+type InstallFn = (
+  mode: "install" | "upgrade",
+  version: string,
+  services: EngineServices
+) => number | Promise<number>
 
 function manifest(): { [k: string]: Json } {
   const doc = parseJson(payloadText("SoT/toolchain.json"))
@@ -47,36 +51,40 @@ function firstLineField(out: string, index: number): string {
   return fields[index === -1 ? fields.length - 1 : index] ?? ""
 }
 
-export function installedVersion(ctx: Ctx, tool: ToolId): string {
-  const version = (): string => ctx.services.deps.version(tool)
+export async function installedVersion(ctx: Ctx, tool: ToolId): Promise<string> {
+  const version = () => ctx.services.deps.version(tool)
   switch (tool) {
-    case "rtk":
-      return firstLineField(version(), 1)
     case "claude":
-      return firstLineField(version(), 0)
+      return firstLineField(await version(), 0)
     case "codex":
-    case "agent-browser":
-      return firstLineField(version(), -1)
+      return firstLineField(await version(), -1)
     case "git":
-      return firstLineField(version(), 2)
+      return firstLineField(await version(), 2)
     case "node":
-      return version().replace(/^v/, "")
+      return (await version()).replace(/^v/, "")
     case "jq":
-      return version().replace(/^jq-/, "")
+      return (await version()).replace(/^jq-/, "")
     case "curl":
     case "tsc":
-      return firstLineField(version(), 1)
+      return firstLineField(await version(), 1)
     case "bun":
     case "effect-solutions":
     case "npm":
-      return version()
+      return await version()
+    case "bwrap":
+      return firstLineField(await version(), 1)
+    case "ffplay":
+      return firstLineField(await version(), 2).replace(/-.*$/, "")
+    case "intelephense":
+    case "typescript-language-server":
+      return (await version()).trim()
     default:
       return ""
   }
 }
 
-export function latestVersion(ctx: Ctx, tool: ToolId): string {
-  return ctx.services.deps.latest(tool)
+export async function latestVersion(ctx: Ctx, tool: ToolId): Promise<string> {
+  return await ctx.services.deps.latest(tool)
 }
 
 /** Blocking TTY prompt matching bash `read -r -p` (prompt on stderr). */
@@ -104,7 +112,12 @@ export function promptLine(
 }
 
 /** toolchain::_gate — { proceed, target } ("" target = latest). */
-function gate(ctx: Ctx, tool: string, mode: "install" | "upgrade", latest: string): { proceed: boolean; target: string } {
+async function gate(
+  ctx: Ctx,
+  tool: string,
+  mode: "install" | "upgrade",
+  latest: string
+): Promise<{ proceed: boolean; target: string }> {
   const { warn } = ctx.services.logger
   const verified = field(ctx, tool, "verified")
   const pinnable = field(ctx, tool, "pinnable")
@@ -118,7 +131,11 @@ function gate(ctx: Ctx, tool: string, mode: "install" | "upgrade", latest: strin
 
   if (process.stdin.isTTY === true) {
     ctx.services.logger.warn(`${tool} ${latest} is not kit-verified (verified: ${verified}).`)
-    const answer = promptLine(`Install ${tool} ${latest} anyway? [y/N] `)
+    const question = `Install ${tool} ${latest} anyway? [y/N] `
+    const answer =
+      ctx.terminalLease === undefined
+        ? promptLine(question)
+        : await ctx.terminalLease.withExclusive(() => promptLine(question))
     if (/^[yY]/.test(answer)) return { proceed: true, target: "" }
   }
 
@@ -132,12 +149,12 @@ function gate(ctx: Ctx, tool: string, mode: "install" | "upgrade", latest: strin
   return { proceed: false, target: "" }
 }
 
-export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
+export async function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): Promise<number> {
   const { echo, verbose, warn } = ctx.services.logger
   const policy = field(ctx, tool, "policy")
 
   if (!present(ctx, tool)) {
-    const latest = latestVersion(ctx, tool)
+    const latest = await latestVersion(ctx, tool)
     if (ctx.dryRun) {
       echo(`[dry-run] would install ${tool} (${latest !== "" ? latest : "latest"}, gated by toolchain.json verified pin)`)
       return 0
@@ -152,14 +169,14 @@ export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
         warn(`${tool} latest version unknown (offline?) and not pinnable — installing latest unverified`)
       }
     } else {
-      const g = gate(ctx, tool, "install", latest)
+      const g = await gate(ctx, tool, "install", latest)
       if (!g.proceed) return 0
       target = g.target
     }
-    return installFn("install", target !== "" ? target : latest, ctx.services)
+    return await installFn("install", target !== "" ? target : latest, ctx.services)
   }
 
-  const installed = installedVersion(ctx, tool)
+  const installed = await installedVersion(ctx, tool)
   const installedLabel = installed !== "" ? installed : "version unknown"
 
   if (policy !== "track") {
@@ -171,7 +188,7 @@ export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
     return 0
   }
 
-  const latest = latestVersion(ctx, tool)
+  const latest = await latestVersion(ctx, tool)
   if (latest === "") {
     if (ctx.dryRun) {
       echo(`[dry-run] ${tool} present (${installedLabel}); latest unknown (offline?) — no action`)
@@ -186,9 +203,9 @@ export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
       echo(`[dry-run] would upgrade ${tool} (${installed !== "" ? installed : "unknown"} -> ${latest}, gated by toolchain.json verified pin)`)
       return 0
     }
-    const g = gate(ctx, tool, "upgrade", latest)
+    const g = await gate(ctx, tool, "upgrade", latest)
     if (!g.proceed) return 0
-    return installFn("upgrade", g.target !== "" ? g.target : latest, ctx.services)
+    return await installFn("upgrade", g.target !== "" ? g.target : latest, ctx.services)
   }
 
   if (ctx.dryRun) {
@@ -204,7 +221,7 @@ function row(cells: [string, string, string, string, string, string]): string {
   return cells.map((c, i) => (i < widths.length ? c.padEnd(widths[i]!) : c)).join(" ")
 }
 
-export function report(ctx: Ctx): void {
+export async function report(ctx: Ctx): Promise<void> {
   const { echo } = ctx.services.logger
   echo(row(["TOOL", "KIND", "INSTALLED", "FLOOR", "VERIFIED", "STATUS"]))
   const pn = ctx.services.platform.name()
@@ -224,7 +241,7 @@ export function report(ctx: Ctx): void {
     let status: string
     const toolId = tool as ToolId
     if (present(ctx, toolId)) {
-      installed = installedVersion(ctx, toolId)
+      installed = await installedVersion(ctx, toolId)
       status = "ok"
       if (floor !== "" && installed !== "" && isNewer(floor, installed)) {
         status = "below-floor"

package/cli/src/engine.ts

@@ -37,7 +37,7 @@ export const engine = (args: ReadonlyArray<string>) =>
     const logger = yield* LoggerService
     const deps = yield* DependencyManagerService
     const platform = yield* PlatformService
-    const code = yield* Effect.sync(() => runEngineNative(args, { logger, deps, platform }))
+    const code = yield* Effect.promise(() => runEngineNative(args, { logger, deps, platform }))
     if (code !== 0) {
       yield* Effect.sync(() => process.exit(code))
     }