docks-kit 0.14.2 → 0.14.3

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

@@ -1,7 +1,8 @@
 /**
- * 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 {
@@ -15,7 +16,6 @@ import {
   rmSync,
   writeFileSync
 } from "node:fs"
-import { tmpdir } from "node:os"
 import { bunBootstrap } from "./bun"
 import {
   syncClaudeAdvisor,
@@ -26,10 +26,9 @@ import { claudeRuntimePaths, materializeClaudeSettings, type ClaudeRuntimePaths
 import { p, 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 =
@@ -48,7 +47,6 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
     )
   }
 
-  syncRtk(ctx, claudeDir)
   const bun = bunBootstrap(ctx, ctx.services)
   const runtime: ClaudeRuntimeState = bun.kind === "ready"
     ? { kind: "ready", paths: claudeRuntimePaths(claudeDir, bun.executable) }
@@ -86,86 +84,6 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
   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 +366,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>,
@@ -646,7 +565,7 @@ function nonUserScopeMarketplaces(installedDoc: Json | undefined): Set<string> {
 }
 
 function syncPlugins(ctx: Ctx, claudeDir: string): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
+  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 +606,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 = cli(["plugin", "marketplace", "add", repo])
+    clearProgress()
+    if (marketplaceResult.ok) {
       addedMp++
     } else {
       warn(`Failed to add marketplace: ${mpName} (${repo})`)
@@ -695,17 +617,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}...`)
+      cli(["plugin", "marketplace", "update", mpName])
+      clearProgress()
+      refreshedMarketplaces.add(mpName)
     }
-    if (cli(["plugin", "install", pluginId]).ok) {
+    progress(`Installing plugin ${pluginId}...`)
+    const installResult = cli(["plugin", "install", pluginId])
+    clearProgress()
+    if (installResult.ok) {
       addedPl++
     } else {
       warn(`Failed to install plugin: ${pluginId}`)
@@ -717,12 +647,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}...`)
+      cli(["plugin", "marketplace", "update", mpName])
+      clearProgress()
+    }
+    for (const pluginId of [...kitPluginIds].sort(compareCodepoints)) {
+      if (!pluginUserScopeInstalled(installedPlugins, pluginId)) continue
+      progress(`Updating plugin ${pluginId}...`)
+      const updateResult = cli(["plugin", "update", pluginId, "--scope", "user"])
+      clearProgress()
+      if (updateResult.out.includes("Successfully updated")) updatedPl++
     }
   }
 
@@ -735,7 +685,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 = cli(["plugin", "uninstall", "-y", "--scope", "user", pluginId])
+      clearProgress()
+      if (uninstallResult.ok) {
         removedPl++
       } else {
         warn(`Failed to uninstall plugin: ${pluginId}`)
@@ -748,7 +701,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 = cli(["plugin", "marketplace", "remove", mpName])
+      clearProgress()
+      if (removeResult.ok) {
         removedMp++
       } else {
         warn(`Failed to remove marketplace: ${mpName}`)
@@ -810,7 +766,7 @@ 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
+  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)
@@ -830,7 +786,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 = 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
@@ -889,7 +848,7 @@ function lspPkg(ctx: Ctx, tool: string, pkg: string): string {
 }
 
 function syncLspServers(ctx: Ctx): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
+  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 +888,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 = spawnSync("npm", ["install", "-g", ...missing], { stdio: "ignore" })
+  clearProgress()
+  if (installResult.status === 0) {
     change(`LSP servers installed (${specs})`)
     ctx.nextStepTriggers.claudeRestart = true
   } else {
@@ -949,12 +911,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

@@ -42,9 +42,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
   }
@@ -491,7 +491,7 @@ function installedPluginIdsFromCli(): Set<string> | undefined {
 }
 
 function syncPlugins(ctx: Ctx, sotConfigText: string): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
+  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) {
+    progress("Checking installed Codex plugins...")
     const installedPluginIds = installedPluginIdsFromCli()
+    clearProgress()
     if (installedPluginIds === undefined) {
       warn("Codex plugin inventory unavailable — falling back to the full refresh path")
     } else {
@@ -530,7 +532,9 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   let refreshed = 0
   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"] })
+    clearProgress()
     const addOut = `${res.stdout ?? ""}${res.stderr ?? ""}`
     if (res.error === undefined && res.status === 0) {
       refreshed++

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

@@ -9,7 +9,6 @@
  */
 import { homedir } from "node:os"
 import { isAbsolute } from "node:path"
-import { existsSync, readdirSync } from "node:fs"
 
 import { capture, commandExists, p, which } from "./exec"
 import { isObject, parseJson } from "./jq"
@@ -24,12 +23,9 @@ export type ToolId =
   | "npx"
   | "claude"
   | "codex"
-  | "rtk"
   | "bun"
   | "bwrap"
-  | "agent-browser"
   | "effect-solutions"
-  | "chrome-for-testing"
   | "ffplay"
   | "intelephense"
   | "typescript-language-server"
@@ -166,35 +162,26 @@ const locateEffectSolutions = (exec: ProbeExecutor): DependencyLocation => {
   return { path: resolved, binDir: globalBin }
 }
 
-const resolveChrome = (exec: ProbeExecutor, platform: NodeJS.Platform): ProbeResult => {
-  const root = p(home(), ".agent-browser", "browsers")
-  const relative =
-    platform === "darwin"
-      ? "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
-      : "chrome"
-  if (existsSync(root)) {
-    for (const directory of readdirSync(root).filter((name) => name.startsWith("chrome-")).sort().reverse()) {
-      const path = exec.which(p(root, directory, relative))
-      if (path !== "") return { state: "present", path }
+const npmGlobalCache = new WeakMap<ProbeExecutor, { [k: string]: string }>()
+
+const npmGlobalVersions = (exec: ProbeExecutor): { [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"]
     }
   }
-  for (const command of ["chrome-for-testing", "google-chrome-for-testing", "google-chrome", "chromium", "chromium-browser", "brave-browser", "brave"]) {
-    const path = exec.which(command)
-    if (path !== "") return { state: "present", path }
-  }
-  return { state: "missing" }
+  npmGlobalCache.set(exec, out)
+  return out
 }
 
-const latestRtk = (exec: ProbeExecutor): string => {
-  if (!exec.commandExists("curl")) return ""
-  const doc = parseJson(
-    exec.capture("curl", ["-fsSL", "--max-time", "5", "https://api.github.com/repos/rtk-ai/rtk/releases/latest"])
-  )
-  const tag = doc !== undefined && isObject(doc) && typeof doc["tag_name"] === "string" ? doc["tag_name"] : ""
-  return tag.replace(/^v/, "")
-}
+const versionNpmGlobal = (pkg: string) => (exec: ProbeExecutor): string => npmGlobalVersions(exec)[pkg] ?? ""
 
-const latestNpm = (id: "agent-browser" | "effect-solutions") => (exec: ProbeExecutor): string =>
+const latestNpm = (id: "effect-solutions") => (exec: ProbeExecutor): string =>
   exec.commandExists("npm") ? exec.capture("npm", ["view", id, "version"]) : ""
 
 export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which }
@@ -236,10 +223,6 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     () => 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"',
     { version: versionProbe("codex") }
   ),
-  rtk: spec("rtk", "optional", () => "see https://github.com/rtk-ai/rtk (kit auto-install is Linux/macOS-only)", {
-    version: versionProbe("rtk"),
-    latest: latestRtk
-  }),
   bun: spec(
     "bun",
     "optional",
@@ -250,10 +233,8 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
       locate: (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
     }
   ),
-  bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)"),
-  "agent-browser": spec("agent-browser", "optional", () => "npm install -g agent-browser", {
-    version: versionProbe("agent-browser"),
-    latest: latestNpm("agent-browser")
+  bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)", {
+    version: versionProbe("bwrap")
   }),
   "effect-solutions": spec("effect-solutions", "optional", () => "bun add -g effect-solutions", {
     resolve: resolveEffectSolutions,
@@ -261,27 +242,22 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     locate: locateEffectSolutions,
     latest: latestNpm("effect-solutions")
   }),
-  "chrome-for-testing": spec(
-    "chrome-for-testing",
-    "optional",
-    (pf = rawPlatform()) => (pf === "linux" ? "agent-browser install --with-deps" : "agent-browser install"),
-    { resolve: resolveChrome }
-  ),
   ffplay: spec(
     "ffplay",
     "optional",
     (pf = rawPlatform()) =>
       pf === "darwin" ? "brew install ffmpeg" : "sudo apt install -y ffmpeg",
-    { versionArgs: ["-version"], resolve: pathProbe("ffplay") }
+    { versionArgs: ["-version"], version: versionProbe("ffplay", ["-version"]), resolve: pathProbe("ffplay") }
   ),
   intelephense: spec("intelephense", "optional", () => "npm install -g intelephense", {
-    resolve: pathProbe("intelephense")
+    resolve: pathProbe("intelephense"),
+    version: versionNpmGlobal("intelephense")
   }),
   "typescript-language-server": spec(
     "typescript-language-server",
     "optional",
     () => "npm install -g typescript-language-server typescript",
-    { resolve: pathProbe("typescript-language-server") }
+    { resolve: pathProbe("typescript-language-server"), version: versionProbe("typescript-language-server") }
   ),
   tsc: spec("tsc", "optional", () => "npm install -g typescript", {
     resolve: pathProbe("tsc"),

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

@@ -11,9 +11,9 @@ import { homedir } from "node:os"
 import { kitHome } from "../kitHome"
 import { makeEngineServices, type EngineServices, type Logger } from "./services"
 import type { BunRuntimeState } from "./bun"
-import { claudeNextSteps, claudeSummary, claudeSync } from "./claudeSync"
+import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
-import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
+import { skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
 import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
 
@@ -30,7 +30,7 @@ export interface Ctx {
   readonly agentsDir: string
   dryRun: boolean
   verbose: boolean
-  skipRtk: boolean
+  skipBubblewrap: boolean
   skipPluginRefresh?: boolean
   reconcile: boolean
   prune: boolean
@@ -71,7 +71,7 @@ function makeCtx(services: EngineServices): Ctx {
     agentsDir: env["AGENTS_DIR"] !== undefined && env["AGENTS_DIR"] !== "" ? env["AGENTS_DIR"] : p(home, ".agents"),
     dryRun: env["DRY_RUN"] === "1",
     verbose: env["DOCKS_KIT_VERBOSE"] === "1",
-    skipRtk: env["SKIP_RTK"] === "1",
+    skipBubblewrap: env["SKIP_BUBBLEWRAP"] === "1",
     skipPluginRefresh: false,
     reconcile: env["RECONCILE"] === "1",
     prune: env["PRUNE"] === "1",
@@ -95,17 +95,40 @@ function makeCtx(services: EngineServices): Ctx {
 }
 
 function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
-  const { echo } = ctx.services.logger
+  const { clearProgress, echo, progress } = ctx.services.logger
   parseArgs(ctx, args)
   validateModifierFlags(ctx)
 
   const claudeRan = ctx.syncClaude
-  const claudeRuntime = claudeRan ? claudeSync(ctx) : undefined
+  let claudeRuntime: ClaudeRuntimeState | undefined
+  if (claudeRan) {
+    progress("Syncing Claude...")
+    try {
+      claudeRuntime = claudeSync(ctx)
+    } finally {
+      clearProgress()
+    }
+  }
 
   const codexRan = ctx.syncCodex
-  if (codexRan) codexSync(ctx)
+  if (codexRan) {
+    progress("Syncing Codex...")
+    try {
+      codexSync(ctx)
+    } finally {
+      clearProgress()
+    }
+  }
 
-  const skillsState = ctx.syncAgents ? skillsSync(ctx) : undefined
+  let skillsState: SkillsState | undefined
+  if (ctx.syncAgents) {
+    progress("Syncing skills...")
+    try {
+      skillsState = skillsSync(ctx)
+    } finally {
+      clearProgress()
+    }
+  }
 
   echo("")
   echo("--- Sync complete ---")
@@ -133,6 +156,8 @@ export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineSe
   const baseLogger = baseServices.logger
   const logger: Logger = {
     change: (msg) => baseLogger.change(msg),
+    progress: (msg) => baseLogger.progress(msg),
+    clearProgress: () => baseLogger.clearProgress(),
     verbose: (msg) => {
       if (ctx.verbose) baseLogger.verbose(msg)
     },

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

@@ -1,13 +1,19 @@
 /**
- * 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, transient progress writer, 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 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
@@ -18,18 +24,75 @@ export interface Logger {
 
 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
+
+  const clearProgress = (): void => {
+    if (!progressPending || progressWrite === undefined) return
+    progressWrite("\r\x1b[2K")
+    progressPending = false
+  }
+  const ok = (msg: string): void => {
+    clearProgress()
+    errWrite(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`)
+  }
   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 (progressWrite === undefined) return
+      progressWrite(`\r\x1b[2K\x1b[2m${msg}\x1b[0m`)
+      progressPending = true
+    },
+    clearProgress,
+    warn: (msg) => {
+      clearProgress()
+      errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`)
+    },
+    err: (msg) => {
+      clearProgress()
+      errWrite(`\x1b[1;31m[err]\x1b[0m ${msg}\n`)
+    },
+    echo: (line) => {
+      clearProgress()
+      outWrite(`${line}\n`)
+    }
   }
 }