docks-kit 0.14.3 → 0.15.0

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

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

@@ -23,7 +23,7 @@ export class ExitError extends Error {
   }
 }
 
-const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
+export const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
 const MODIFIER_FLAGS = new Set<ModifierFlag>([
   "--claude-model",
   "--claude-effort",

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

@@ -4,9 +4,8 @@
  * 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,9 +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)
-  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
 }
@@ -55,7 +54,7 @@ function readSlugs(file: string): Array<string> {
   return existsSync(file) ? normalizeManifest(readFileSync(file, "utf8")) : []
 }
 
-function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest: string): void {
+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")
@@ -87,11 +86,11 @@ function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest
     }
 
     progress(`Installing universal skill ${slug}...`)
-    const res = spawnSync("npx", ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"], {
+    const res = await spawnProcess("npx", ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"], {
       stdio: "ignore"
     })
     clearProgress()
-    if (res.error === undefined && res.status === 0) {
+    if (res.error === undefined && res.exitCode === 0) {
       added++
     } else {
       warn(`Failed to install universal skill: ${slug}`)
@@ -221,26 +220,26 @@ function linkOrCopyWithWarnings(target: string, link: string, services: EngineSe
 /** skills::_effect_solutions_install. */
 export function effectSolutionsInstall(
   ctx: Ctx
-): (mode: "install" | "upgrade", version: string, services: EngineServices) => number {
-  return (mode, version, services) => {
+): (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})` : ""}...`)
     progress(`${verb} effect-solutions CLI...`)
-    const installResult = spawnSync(bun, ["add", "-g", pkg], { stdio: "ignore" })
+    const installResult = await spawnProcess(bun, ["add", "-g", pkg], { stdio: "ignore" })
     clearProgress()
-    if (installResult.status !== 0) {
+    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 })
@@ -254,12 +253,12 @@ export function effectSolutionsInstall(
   }
 }
 
-function syncEffectSolutionsCli(ctx: Ctx): void {
+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 = ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
+  const result = await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
   clearProgress()
   if (result !== 0) {
     warn("effect-solutions bootstrap failed — continuing sync")
@@ -268,7 +267,7 @@ function syncEffectSolutionsCli(ctx: Ctx): void {
 
 // ----------------------------------------------------- prune + snapshot ----
 
-function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
+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) {
@@ -290,11 +289,11 @@ function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
       continue
     }
     progress(`Removing universal skill ${base}...`)
-    const res = spawnSync("npx", ["--yes", skillsCli(ctx), "remove", "--global", base, "-y"], {
+    const res = await spawnProcess("npx", ["--yes", skillsCli(ctx), "remove", "--global", base, "-y"], {
       stdio: "ignore"
     })
     clearProgress()
-    if (res.error === undefined && res.status === 0) {
+    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,40 +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 "claude":
-      return firstLineField(version(), 0)
+      return firstLineField(await version(), 0)
     case "codex":
-      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(version(), 1)
+      return firstLineField(await version(), 1)
     case "ffplay":
-      return firstLineField(version(), 2).replace(/-.*$/, "")
+      return firstLineField(await version(), 2).replace(/-.*$/, "")
     case "intelephense":
     case "typescript-language-server":
-      return version().trim()
+      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). */
@@ -108,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")
@@ -122,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: "" }
   }
 
@@ -136,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
@@ -156,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") {
@@ -175,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`)
@@ -190,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) {
@@ -208,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()
@@ -228,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

@@ -7,7 +7,7 @@ import { DependencyManagerService, LoggerService, PlatformService } from "./serv
 
 /**
  * The single seam between the typed CLI and EngineNative. Engine execution
- * stays in-process after @effect/cli has parsed pickers and flag spellings.
+ * stays in-process after effect/unstable/cli has parsed pickers and flag spellings.
  */
 const bashRemovedMessage = "bash engine removed — recover at tag bash-engine-final"
 const bashEngineRequested = (): boolean => process.env["DOCKS_KIT_ENGINE"] === "bash"
@@ -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))
     }

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.14.3"
+export const GENERATED_PACKAGE_VERSION = "0.15.0"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",

package/cli/src/main.ts

@@ -1,8 +1,7 @@
 #!/usr/bin/env bun
-import { Command } from "@effect/cli"
-import { BunContext, BunRuntime } from "@effect/platform-bun"
+import { Command, CliOutput } from "effect/unstable/cli"
+import { BunRuntime, BunServices } from "@effect/platform-bun"
 import { Console, Effect, Layer } from "effect"
-import { engine } from "./engine"
 import { EngineServicesLive } from "./services"
 import { docsCommand } from "./commands/docs"
 import { modelCommand } from "./commands/model"
@@ -14,6 +13,7 @@ import { syncCommand } from "./commands/sync"
 import { toolchainCommand } from "./commands/toolchain"
 import { updateCommand } from "./commands/update"
 import { GENERATED_PACKAGE_VERSION } from "./generated/sotPayload"
+import { prepareArgv } from "./argv"
 
 
 const root = Command.make("docks-kit", {}, () =>
@@ -50,37 +50,36 @@ const root = Command.make("docks-kit", {}, () =>
   ])
 )
 
+// v4's default formatter renders `name vversion`, but the `docks-kit` launcher
+// compares `--version` against the bare `package.json` version. The trailing
+// newline reproduces the characterized byte-for-byte output of the v3 CLI.
+const bareVersionFormatter: CliOutput.Formatter = {
+  ...CliOutput.defaultFormatter(),
+  formatVersion: (_name, version) => `${version}\n`
+}
+
 // Harness-private raw channel:
-// `DOCKS_KIT_ENGINE=native-raw` bypasses @effect/cli and hands the raw engine
+// `DOCKS_KIT_ENGINE=native-raw` bypasses effect/unstable/cli and hands the raw engine
 // argv to EngineNative so golden tests drive the internal vocabulary directly.
 // PUBLIC engine execution lives at the engine.ts seam after the CLI has
 // parsed/normalized pickers, --flag value forms, and non-engine commands.
 if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
   const { runEngineNative } = await import("./engine-native")
-  process.exit(runEngineNative(process.argv.slice(2)))
+  process.exit(await runEngineNative(process.argv.slice(2)))
 }
 
-const cli = Command.run(root, {
-  name: "docks-kit",
-  version: GENERATED_PACKAGE_VERSION
-})
-
-// Normalize the repeatable plugin's documented equals form and exact empty
-// text-option assignments that @effect/cli otherwise routes into positional
-// targets. EngineNative owns the resulting shared empty-value validation.
-const emptyTextOptions = new Set([
-  "--claude-model=",
-  "--claude-effort=",
-  "--claude-advisor=",
-  "--codex-model=",
-  "--codex-effort=",
-])
-const argv = process.argv.flatMap((a, index, all) => {
-  if (a.startsWith("--claude-plugin=")) {
-    return ["--claude-plugin", a.slice("--claude-plugin=".length)]
-  }
-  if (emptyTextOptions.has(a)) return [a.slice(0, -1), ""]
-  return [a]
-})
+// Validate and normalize before parsing because the kit refuses to guess at unrecognized
+// or duplicated flags, and Effect 4 would otherwise negate `--no-<flag>` into a real
+// mutating run. This seam owns argument normalization.
+const prepared = prepareArgv(process.argv.slice(2))
+if (prepared.kind === "reject") {
+  process.stderr.write(`${prepared.message}\n`)
+  process.exit(prepared.exitCode)
+}
 
-cli(argv).pipe(Effect.provide(Layer.mergeAll(BunContext.layer, EngineServicesLive)), BunRuntime.runMain)
+Command.runWith(root, { version: GENERATED_PACKAGE_VERSION })(prepared.args).pipe(
+  Effect.provide(
+    Layer.mergeAll(BunServices.layer, EngineServicesLive, CliOutput.layer(bareVersionFormatter))
+  ),
+  BunRuntime.runMain
+)

package/cli/src/services.ts

@@ -8,14 +8,14 @@ import { Context, Layer } from "effect"
 import { makeLogger, type Logger, type LoggerSinks } from "./engine-native/logger"
 import { makeEngineServices, makePlatform, type DependencyManager, type Platform } from "./engine-native/services"
 
-export class LoggerService extends Context.Tag("docks-kit/Logger")<LoggerService, Logger>() {}
+export class LoggerService extends Context.Service<LoggerService, Logger>()("docks-kit/Logger") {}
 
-export class DependencyManagerService extends Context.Tag("docks-kit/DependencyManager")<
+export class DependencyManagerService extends Context.Service<
   DependencyManagerService,
   DependencyManager
->() {}
+>()("docks-kit/DependencyManager") {}
 
-export class PlatformService extends Context.Tag("docks-kit/Platform")<PlatformService, Platform>() {}
+export class PlatformService extends Context.Service<PlatformService, Platform>()("docks-kit/Platform") {}
 
 const live = makeEngineServices()
 

package/docks-kit

@@ -69,7 +69,7 @@ fi
 
 # Sentinel is a real dependency dir, not bare node_modules/ — a failed or
 # partial install leaves node_modules/ present and would suppress the repair.
-if [[ ! -d "$REPO_DIR/node_modules/@effect/cli" ]]; then
+if [[ ! -d "$REPO_DIR/node_modules/effect" ]]; then
   echo "[docks-kit] Installing CLI dependencies (bun install --frozen-lockfile)..." >&2
   (cd "$REPO_DIR" && "$BUN" install --frozen-lockfile >/dev/null)
 fi