docks-kit 0.15.1 → 0.15.3

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

@@ -1,22 +1,39 @@
 /**
  * EngineNative `sync agents` pipeline: universal-skill bootstrap
  * (`npx skills@<pin> add`), Claude symlink healing, --prune reconcile against
- * the kit-managed snapshot, the effect-solutions toolchain callback, and the
- * snapshot write.
+ * the kit-managed snapshot, and the snapshot write.
  */
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync } from "node:fs"
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync
+} from "node:fs"
+import { dirname, relative, resolve } from "node:path"
+import { payloadText } from "../payload"
 import { p, spawnProcess, writeFileIfChanged } from "./exec"
-import { bunBootstrap } from "./bun"
 import type { Ctx } from "./index"
 import { compareCodepoints } from "./jq"
+import { hostOs, type DirectoryLinkKind } from "./os"
+import { ExitError } from "./parseArgs"
 import type { EngineServices } from "./services"
-import { ensure, field } from "./toolchain"
-import { payloadText } from "../payload"
+import { field } from "./toolchain"
 
 export interface SkillsState {
   present: number
 }
 
+export type LinkOutcome = "symlink" | "junction" | "copy" | "failed"
+
+/** Lets heal and prune distinguish a kit-owned copy from a user's real directory. */
+export const COPY_MARKER = ".docks-kit-copied-skill"
+
 export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
   const state: SkillsState = { present: 0 }
   const skillsDir = p(ctx.agentsDir, "skills")
@@ -26,16 +43,17 @@ export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
   if (!ctx.dryRun) mkdirSync(skillsDir, { recursive: true })
 
   await syncUniversal(ctx, state, skillsDir, manifest)
-  if (ctx.prune) await reconcileRemovals(ctx, manifest, snapshot)
-  await syncEffectSolutionsCli(ctx)
-  updateSnapshot(ctx, manifest, snapshot)
+  const failedRemovals = ctx.prune ? await reconcileRemovals(ctx, manifest, snapshot) : []
+  updateSnapshot(ctx, manifest, snapshot, failedRemovals)
   return state
 }
 
 /** skills::_skills_cli — the pinned npx package spec. */
 function skillsCli(ctx: Ctx): string {
-  const v = field(ctx, "skills-cli", "verified")
-  return v !== "" ? `skills@${v}` : "skills"
+  const version = field(ctx, "skills-cli", "verified")
+  if (version !== "") return `skills@${version}`
+  ctx.services.logger.err("Universal skills sync aborted because SoT/toolchain.json has no verified skills-cli pin")
+  throw new ExitError(1)
 }
 
 /** skills::_normalize_manifest — cleaned slugs, one per line. */
@@ -131,7 +149,7 @@ function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): boolean {
   const canonical = p(skillsDir, base)
   const claudeSkillsDir = p(ctx.home, ".claude", "skills")
   const claudeLink = p(claudeSkillsDir, base)
-  const relTarget = `../../.agents/skills/${base}`
+  const relTarget = relative(dirname(claudeLink), canonical)
 
   if (!isDir(canonical)) return false
 
@@ -148,15 +166,25 @@ function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): boolean {
       return false
     }
   } else if (linkStat !== undefined) {
-    warn(`~/.claude/skills/${base} exists as a real path (not a symlink) — leaving alone; remove manually if it's stale`)
-    return false
+    if (!isKitOwnedCopy(claudeLink)) {
+      warn(`~/.claude/skills/${base} exists as a real path (not a symlink) — leaving alone; remove manually if it's stale`)
+      return false
+    }
+    if (ctx.dryRun) {
+      echo(`[dry-run] would replace kit-created Claude copy: ~/.claude/skills/${base} -> ${relTarget}`)
+      return true
+    }
+    if (!removeKitOwnedCopy(claudeLink)) {
+      warn(`could not remove kit-created copy ~/.claude/skills/${base} — remove it manually, then re-run sync`)
+      return false
+    }
   } else if (ctx.dryRun) {
     echo(`[dry-run] would create missing Claude symlink: ~/.claude/skills/${base} -> ${relTarget}`)
     return true
   }
 
   mkdirSync(claudeSkillsDir, { recursive: true })
-  return linkOrCopyWithWarnings(relTarget, claudeLink, ctx.services)
+  return linkOrCopyWithWarnings(relTarget, claudeLink, ctx.services) !== "failed"
 }
 
 function lstat(path: string): ReturnType<typeof lstatSync> | undefined {
@@ -167,107 +195,110 @@ function lstat(path: string): ReturnType<typeof lstatSync> | undefined {
   }
 }
 
-function safeReadlink(path: string): string {
+/**
+ * A link only counts when it RESOLVES to the skill directory. Windows picks a
+ * symlink's file-or-directory type by autodetecting the target against the
+ * process working directory, not the link's own directory, so a relative
+ * target can yield a symlink that exists but resolves to nothing. Checking
+ * resolution is what makes the next mechanism in the chain reachable.
+ */
+function linksToDirectory(path: string): boolean {
+  if (lstat(path)?.isSymbolicLink() !== true) return false
   try {
-    return readlinkSync(path)
+    return statSync(path).isDirectory()
   } catch {
-    return ""
+    return false
   }
 }
 
+function isKitOwnedCopy(path: string): boolean {
+  return lstat(path)?.isDirectory() === true && existsSync(p(path, COPY_MARKER))
+}
 
-/** Remove a symlink without touching a real directory. */
-function removeLink(path: string): boolean {
+function removeKitOwnedCopy(path: string): boolean {
+  if (!isKitOwnedCopy(path)) return false
   try {
-    rmSync(path, { force: true })
+    rmSync(path, { recursive: true, force: true })
     return true
   } catch {
     return lstat(path) === undefined
   }
 }
 
-/** skills::_link_or_copy — real symlink preferred, copy fallback. */
-export function linkOrCopy(target: string, link: string): boolean {
-  removeLink(link)
-  try {
-    symlinkSync(target, link)
-  } catch {
-    // fall through to the copy fallback below
-  }
-  if (lstat(link)?.isSymbolicLink() === true) return true
+function safeReadlink(path: string): string {
   try {
-    // Resolve a relative target against the link's parent, like ln does.
-    const resolved = target.startsWith("/") ? target : p(link.slice(0, link.lastIndexOf("/")), target)
-    cpSync(resolved, link, { recursive: true })
+    return readlinkSync(path)
   } catch {
-    // fall through to the existence check below
+    return ""
   }
-  return existsSync(link)
 }
 
-function linkOrCopyWithWarnings(target: string, link: string, services: EngineServices): boolean {
-  const linked = linkOrCopy(target, link)
-  if (!linked) {
-    services.logger.warn(`could not create ${link} (symlink and copy both failed)`)
-  } else if (lstat(link)?.isSymbolicLink() !== true) {
-    services.logger.warn(`symlinks unsupported here — ${link} is a copy refreshed on sync`)
+
+/** Remove a symlink without touching a real directory. */
+function removeLink(path: string): boolean {
+  try {
+    rmSync(path, { force: true })
+    return true
+  } catch {
+    return lstat(path) === undefined
   }
-  return linked
 }
 
-// ------------------------------------------------- toolchain callbacks ----
-
-/** skills::_effect_solutions_install. */
-export function effectSolutionsInstall(
-  ctx: Ctx
-): (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 = await bunBootstrap(ctx, services)
-    if (bunState.kind === "deferred") return 1
-    const bun = bunState.executable
+/** skills::_link_or_copy — try directory links in host order, then a marked copy. */
+export function linkOrCopy(
+  target: string,
+  link: string,
+  kinds: ReadonlyArray<DirectoryLinkKind> = hostOs().directoryLinkKinds
+): LinkOutcome {
+  const resolvedLink = resolve(link)
+  const absoluteTarget = resolve(dirname(resolvedLink), target)
+  if (absoluteTarget === resolvedLink) return "symlink"
+  removeLink(link)
 
-    verbose(`${verb} effect-solutions CLI via bun${version !== "" ? ` (pinned ${version})` : ""}...`)
-    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
+  for (const kind of kinds) {
+    try {
+      if (kind === "symlink") {
+        symlinkSync(target, link)
+      } else {
+        symlinkSync(absoluteTarget, link, "junction")
+      }
+      if (linksToDirectory(link)) return kind
+    } catch {
+      // The runtime decides whether each mechanism works; try the next one.
     }
+    removeLink(link)
+  }
 
-    const location = await services.deps.location("effect-solutions")
-    const gbin = location.binDir
-    if (location.path !== "") {
-      mkdirSync(p(ctx.home, ".local", "bin"), { recursive: true })
-      linkOrCopyWithWarnings(bun, p(ctx.home, ".local", "bin", "bun"), services)
-      linkOrCopyWithWarnings(location.path, p(ctx.home, ".local", "bin", "effect-solutions"), services)
-      change("effect-solutions CLI ready (linked bun + effect-solutions into ~/.local/bin)")
-    } else {
-      warn(`effect-solutions installed but binary not found under '${gbin !== "" ? gbin : "<unknown>"}' — link it onto PATH manually`)
+  const copyDestinationWasAbsent = lstat(link) === undefined
+  try {
+    cpSync(absoluteTarget, link, { recursive: true })
+    writeFileSync(p(link, COPY_MARKER), "")
+    return "copy"
+  } catch {
+    if (copyDestinationWasAbsent) {
+      try {
+        rmSync(link, { recursive: true, force: true })
+      } catch {
+        // The outcome remains failed; a later sync can retry the destination.
+      }
     }
-    return 0
+    return "failed"
   }
 }
 
-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
-
-  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")
+function linkOrCopyWithWarnings(target: string, link: string, services: EngineServices): LinkOutcome {
+  const outcome = linkOrCopy(target, link)
+  if (outcome === "copy") {
+    services.logger.warn(`created copy fallback ${link} because directory linking is unavailable — a later sync will restore a real link once linking works`)
+  } else if (outcome === "failed") {
+    services.logger.warn(`could not create symlink ${link}`)
   }
+  return outcome
 }
 
 // ----------------------------------------------------- prune + snapshot ----
 
-async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): Promise<void> {
+async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): Promise<Array<string>> {
   const { change, clearProgress, echo, progress, warn } = ctx.services.logger
   if (!existsSync(snapshot)) {
     if (ctx.dryRun) {
@@ -275,17 +306,25 @@ async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
         `[dry-run] (--prune) no kit-managed-skills snapshot yet; first real sync writes ${snapshot}, then future --prune runs reconcile against it`
       )
     }
-    return
+    return []
   }
 
   const current = normalizeManifest(manifest)
+  const currentBases = new Set(current.map((slug) => slug.slice(slug.lastIndexOf("/") + 1)))
   let removed = 0
   let failed = 0
+  const failedSlugs: Array<string> = []
   for (const slug of readSlugs(snapshot)) {
     if (current.includes(slug)) continue
     const base = slug.slice(slug.lastIndexOf("/") + 1)
+    if (currentBases.has(base)) continue
+    const claudeEntry = p(ctx.home, ".claude", "skills", base)
+    const managedClaudeEntry = lstat(claudeEntry)?.isSymbolicLink() === true || isKitOwnedCopy(claudeEntry)
     if (ctx.dryRun) {
       echo(`[dry-run] kit-managed skill no longer in SoT — would remove: ${base}`)
+      if (managedClaudeEntry) {
+        echo(`[dry-run] kit-managed Claude skill entry — would remove: ~/.claude/skills/${base}`)
+      }
       continue
     }
     progress(`Removing universal skill ${base}...`)
@@ -293,12 +332,24 @@ async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
       stdio: "ignore"
     })
     clearProgress()
-    if (res.error === undefined && res.exitCode === 0) {
-      removed++
-    } else {
+    if (res.error !== undefined || res.exitCode !== 0) {
       warn(`Failed to remove kit-managed skill: ${base}`)
       failed++
+      failedSlugs.push(slug)
+      continue
+    }
+    if (managedClaudeEntry) {
+      const entryStat = lstat(claudeEntry)
+      const removedClaudeEntry = entryStat === undefined
+        || (entryStat.isSymbolicLink() ? removeLink(claudeEntry) : removeKitOwnedCopy(claudeEntry))
+      if (!removedClaudeEntry) {
+        warn(`Failed to remove kit-managed Claude skill entry: ${base}`)
+        failed++
+        failedSlugs.push(slug)
+        continue
+      }
     }
+    removed++
   }
 
   if (removed > 0) {
@@ -306,13 +357,14 @@ async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
     ctx.nextStepTriggers.skillsRestart = true
   }
   if (failed > 0) warn(`${failed} skill remove(s) failed — re-run with --prune or run: npx skills remove --global <name> -y`)
+  return failedSlugs
 }
 
-function updateSnapshot(ctx: Ctx, manifest: string, snapshot: string): void {
+function updateSnapshot(ctx: Ctx, manifest: string, snapshot: string, failedRemovals: ReadonlyArray<string>): void {
   if (ctx.dryRun) return
 
   mkdirSync(ctx.agentsDir, { recursive: true })
-  const sorted = [...new Set(normalizeManifest(manifest))].sort(compareCodepoints)
+  const sorted = [...new Set([...normalizeManifest(manifest), ...failedRemovals])].sort(compareCodepoints)
   writeFileIfChanged(snapshot, sorted.length > 0 ? `${sorted.join("\n")}\n` : "")
 }
 

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

@@ -1,20 +1,12 @@
 /**
- * Verified-version-floor layer over SoT/toolchain.json. Probe/install commands
- * spawn deterministic argv arrays and are covered by golden regression cases.
+ * Verified-version-floor layer over SoT/toolchain.json. Probe commands spawn
+ * deterministic argv arrays and are covered by golden regression cases.
  */
-import { readSync } from "node:fs"
-
 import type { ToolId } from "./deps"
 import type { Ctx } from "./index"
 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 | Promise<number>
+import { hostOs } from "./os"
 
 function manifest(): { [k: string]: Json } {
   const doc = parseJson(payloadText("SoT/toolchain.json"))
@@ -68,7 +60,6 @@ export async function installedVersion(ctx: Ctx, tool: ToolId): Promise<string>
     case "tsc":
       return firstLineField(await version(), 1)
     case "bun":
-    case "effect-solutions":
     case "npm":
       return await version()
     case "bwrap":
@@ -83,139 +74,6 @@ export async function installedVersion(ctx: Ctx, tool: ToolId): Promise<string>
   }
 }
 
-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). */
-export function promptLine(
-  prompt: string,
-  write: (chunk: string) => void = (chunk) => void process.stderr.write(chunk),
-  readByte: (buffer: Buffer) => number = (buffer) => readSync(0, buffer, 0, 1, null)
-): string {
-  write(prompt)
-  const buf = Buffer.alloc(1)
-  let line = ""
-  for (;;) {
-    let n: number
-    try {
-      n = readByte(buf)
-    } catch {
-      break
-    }
-    if (n === 0) break
-    const ch = buf.toString("utf8")
-    if (ch === "\n") break
-    line += ch
-  }
-  return line.replace(/\r$/, "")
-}
-
-/** toolchain::_gate — { proceed, target } ("" target = latest). */
-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")
-
-  if (verified === "" || !isNewer(latest, verified)) return { proceed: true, target: "" }
-
-  if (ctx.assumeYes) {
-    warn(`${tool} ${latest} is newer than kit-verified ${verified} — proceeding (--yes)`)
-    return { proceed: true, target: "" }
-  }
-
-  if (process.stdin.isTTY === true) {
-    ctx.services.logger.warn(`${tool} ${latest} is not kit-verified (verified: ${verified}).`)
-    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: "" }
-  }
-
-  if (mode === "install" && pinnable === "true") {
-    warn(`installing kit-verified ${tool} ${verified} instead of ${latest}`)
-    return { proceed: true, target: verified }
-  }
-  warn(
-    `skipping ${tool} ${mode} (latest ${latest} is above kit-verified ${verified}; pass --yes to accept, or update SoT/toolchain.json after testing)`
-  )
-  return { proceed: false, target: "" }
-}
-
-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 = await latestVersion(ctx, tool)
-    if (ctx.dryRun) {
-      echo(`[dry-run] would install ${tool} (${latest !== "" ? latest : "latest"}, gated by toolchain.json verified pin)`)
-      return 0
-    }
-    let target: string
-    if (latest === "") {
-      target = field(ctx, tool, "verified")
-      if (target !== "" && field(ctx, tool, "pinnable") === "true") {
-        warn(`${tool} latest version unknown (offline?) — installing kit-verified ${target} instead`)
-      } else {
-        target = ""
-        warn(`${tool} latest version unknown (offline?) and not pinnable — installing latest unverified`)
-      }
-    } else {
-      const g = await gate(ctx, tool, "install", latest)
-      if (!g.proceed) return 0
-      target = g.target
-    }
-    return await installFn("install", target !== "" ? target : latest, ctx.services)
-  }
-
-  const installed = await installedVersion(ctx, tool)
-  const installedLabel = installed !== "" ? installed : "version unknown"
-
-  if (policy !== "track") {
-    if (ctx.dryRun) {
-      echo(`[dry-run] ${tool} present (${installedLabel})`)
-      return 0
-    }
-    verbose(`${tool} present (${installedLabel})`)
-    return 0
-  }
-
-  const latest = await latestVersion(ctx, tool)
-  if (latest === "") {
-    if (ctx.dryRun) {
-      echo(`[dry-run] ${tool} present (${installedLabel}); latest unknown (offline?) — no action`)
-      return 0
-    }
-    verbose(`${tool} present (${installedLabel}; latest unknown — no action)`)
-    return 0
-  }
-
-  if (installed === "" || isNewer(latest, installed)) {
-    if (ctx.dryRun) {
-      echo(`[dry-run] would upgrade ${tool} (${installed !== "" ? installed : "unknown"} -> ${latest}, gated by toolchain.json verified pin)`)
-      return 0
-    }
-    const g = await gate(ctx, tool, "upgrade", latest)
-    if (!g.proceed) return 0
-    return await installFn("upgrade", g.target !== "" ? g.target : latest, ctx.services)
-  }
-
-  if (ctx.dryRun) {
-    echo(`[dry-run] ${tool} up to date (${installed})`)
-    return 0
-  }
-  verbose(`${tool} up to date (${installed})`)
-  return 0
-}
-
 function row(cells: [string, string, string, string, string, string]): string {
   const widths = [28, 9, 14, 9, 9]
   return cells.map((c, i) => (i < widths.length ? c.padEnd(widths[i]!) : c)).join(" ")
@@ -225,7 +83,7 @@ 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()
-  const platformOs = pn === "unknown" ? "" : pn
+  const platformOs = hostOs(pn).toolchainOs
   for (const tool of Object.keys(manifest()).sort(compareCodepoints)) {
     const os = field(ctx, tool, "os")
     if (os !== "" && platformOs !== "" && os !== platformOs) continue
@@ -242,7 +100,7 @@ export async function report(ctx: Ctx): Promise<void> {
     const toolId = tool as ToolId
     if (present(ctx, toolId)) {
       installed = await installedVersion(ctx, toolId)
-      status = "ok"
+      status = installed === "" ? "unknown" : "ok"
       if (floor !== "" && installed !== "" && isNewer(floor, installed)) {
         status = "below-floor"
       } else if (verified !== "" && installed !== "" && isNewer(installed, verified)) {

package/cli/src/engine.ts

@@ -1,7 +1,10 @@
+import { CliError } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
 import { spawnSync } from "node:child_process"
 import { runEngineNative } from "./engine-native"
+import { ExitError } from "./engine-native/parseArgs"
 import { makeEngineServices } from "./engine-native/services"
+import { targetForHost } from "./engine-native/os/targets"
 import { kitHome } from "./kitHome"
 import { DependencyManagerService, LoggerService, PlatformService } from "./services"
 
@@ -14,10 +17,10 @@ const bashEngineRequested = (): boolean => process.env["DOCKS_KIT_ENGINE"] === "
 const requireSupportedHost = () => {
   const platform = process.platform
   const arch = process.arch
-  return (platform === "linux" || platform === "darwin") && (arch === "x64" || arch === "arm64")
+  return targetForHost(platform, arch) !== undefined
     ? Effect.void
     : bail(
-      `unsupported host ${platform}/${arch}; docks-kit supports only Linux and macOS on x64 or arm64`,
+      `unsupported host ${platform}/${arch}; docks-kit supports only Linux, macOS, and Windows on x64 or arm64`,
       2
     )
 }
@@ -28,6 +31,19 @@ const requireSupportedHost = () => {
 export const compiled =
   process.argv[1] !== undefined && process.argv[1].startsWith("/$bunfs/")
 
+export class EngineCaptureError extends ExitError {
+  constructor(readonly diagnostic: string, code: number) {
+    super(code)
+    this.name = "EngineCaptureError"
+    this.message = diagnostic
+  }
+}
+
+const failureMessage = (error: unknown): string => {
+  if (error instanceof Error && error.message !== "") return error.message
+  return typeof error === "string" && error !== "" ? error : "unknown error"
+}
+
 export const engine = (args: ReadonlyArray<string>) =>
   Effect.gen(function* () {
     yield* requireSupportedHost()
@@ -37,7 +53,13 @@ export const engine = (args: ReadonlyArray<string>) =>
     const logger = yield* LoggerService
     const deps = yield* DependencyManagerService
     const platform = yield* PlatformService
-    const code = yield* Effect.promise(() => runEngineNative(args, { logger, deps, platform }))
+    const code = yield* Effect.tryPromise({
+      try: () => runEngineNative(args, { logger, deps, platform }),
+      catch: (error) => new CliError.UserError({
+        cause: error,
+        userMessage: `engine operation '${args.join(" ") || "default"}' failed: ${failureMessage(error)}`
+      })
+    })
     if (code !== 0) {
       yield* Effect.sync(() => process.exit(code))
     }
@@ -50,19 +72,27 @@ export const engineCapture = (args: ReadonlyArray<string>) =>
     if (bashEngineRequested()) {
       return yield* bail(bashRemovedMessage, 2)
     }
-    return yield* Effect.sync(() => {
+    const res = yield* Effect.sync(() =>
       // Child process (raw channel): runEngineNative writes straight to
-      // process.stdout, so in-process capture isn't possible.
-      const res = spawnSync(process.execPath, compiled ? [...args] : [`${kitHome()}/cli/src/main.ts`, ...args], {
+      // process.stdout, so in-process capture is not possible.
+      spawnSync(process.execPath, compiled ? [...args] : [`${kitHome()}/cli/src/main.ts`, ...args], {
         env: { ...process.env, DOCKS_KIT_ENGINE: "native-raw" },
         encoding: "utf8",
         stdio: ["ignore", "pipe", "inherit"]
       })
-      if (res.error !== undefined || res.status !== 0) {
-        makeEngineServices().logger.warn(`engine capture failed (${args.join(" ")} exited ${res.status ?? "spawn-error"})`)
-      }
-      return res.stdout ?? ""
-    })
+    )
+    if (res.error !== undefined || res.status !== 0) {
+      const reasons = new Array<string>()
+      if (typeof res.status === "number") reasons.push(`exit ${res.status}`)
+      if (res.signal !== null) reasons.push(`signal ${res.signal}`)
+      if (res.error !== undefined) reasons.push(`spawn error: ${res.error.message}`)
+      if (reasons.length === 0) reasons.push("no child status")
+      const diagnostic = `engine capture failed for '${args.join(" ") || "default"}': ${reasons.join("; ")}`
+      makeEngineServices().logger.err(diagnostic)
+      const code = typeof res.status === "number" && res.status !== 0 ? res.status : 1
+      return yield* Effect.fail(new EngineCaptureError(diagnostic, code))
+    }
+    return res.stdout ?? ""
   })
 
 /** Print a message to stderr and exit — for CLI-side validation failures. */