docks-kit 0.15.1 → 0.15.3

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

@@ -4,8 +4,9 @@
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
-import { accessSync, chmodSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
-import { delimiter, isAbsolute, join } from "node:path"
+import { accessSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { delimiter, extname, isAbsolute, join } from "node:path"
+import { hostOs, type HostOs } from "./os"
 
 /** Keep engine paths slash-separated so rendered output is host-stable. */
 export function p(...parts: Array<string>): string {
@@ -21,6 +22,8 @@ export interface AsyncProcessResult {
 
 export interface AsyncProcessOptions {
   readonly stdio?: SpawnOptions["stdio"]
+  /** Host whose executable resolution and argv shaping apply; tests inject it. */
+  readonly host?: HostOs
 }
 
 export function spawnProcess(
@@ -29,9 +32,25 @@ export function spawnProcess(
   options: AsyncProcessOptions = {}
 ): Promise<AsyncProcessResult> {
   const { promise, resolve } = Promise.withResolvers<AsyncProcessResult>()
+  const host = options.host ?? hostOs()
+  const resolvesSuffixes = host.executableSuffixes.some((suffix) => suffix !== "")
+  const executablePath = resolvesSuffixes ? which(cmd, host.executableSuffixes) : cmd
+  if (executablePath === "") {
+    // Never hand a pathless name to a host that resolves suffixes: CreateProcess
+    // searches the parent's current directory before the system one, so an
+    // untrusted checkout could answer for a missing tool.
+    resolve({ exitCode: null, stdout: "", stderr: "", error: new Error(`command not found on PATH: ${cmd}`) })
+    return promise
+  }
   let child: ChildProcess
   try {
-    child = spawn(cmd, [...args], { stdio: options.stdio ?? ["ignore", "pipe", "ignore"] })
+    // Inside the try: a host whose invocation encoding rejects a value it
+    // cannot represent reports it like any other spawn failure.
+    const invocation = host.invoke(executablePath, args)
+    child = spawn(invocation.command, [...invocation.args], {
+      stdio: options.stdio ?? ["ignore", "pipe", "ignore"],
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments
+    })
   } catch (cause) {
     const error = cause instanceof Error ? cause : new Error(String(cause))
     resolve({ exitCode: null, stdout: "", stderr: "", error })
@@ -75,14 +94,20 @@ export async function capture(cmd: string, args: ReadonlyArray<string>): Promise
 }
 
 /** `command -v` — resolve an executable name on PATH. */
-export function which(name: string): string {
-  if (isAbsolute(name) || name.includes("/")) {
-    return isExecutable(name) ? name : ""
+export function which(name: string, suffixes: ReadonlyArray<string> = hostOs().executableSuffixes): string {
+  const runnableCandidate = (base: string): string => {
+    for (const suffix of suffixes) {
+      const candidate = `${base}${suffix}`
+      if (isExecutable(candidate, suffixes)) return candidate
+    }
+    return ""
   }
+
+  if (isAbsolute(name) || name.includes("/")) return runnableCandidate(name)
   for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
     if (dir === "") continue
-    const candidate = join(dir, name)
-    if (isExecutable(candidate)) return candidate
+    const candidate = runnableCandidate(join(dir, name))
+    if (candidate !== "") return candidate
   }
   return ""
 }
@@ -91,33 +116,26 @@ export function commandExists(name: string): boolean {
   return which(name) !== ""
 }
 
-export function isExecutable(p: string): boolean {
+export function isExecutable(path: string, suffixes: ReadonlyArray<string> = hostOs().executableSuffixes): boolean {
   try {
-    if (!statSync(p).isFile()) return false
-    accessSync(p, constants.X_OK)
+    if (!statSync(path).isFile()) return false
+    if (suffixes.some((suffix) => suffix !== "")) {
+      const lowerPath = path.toLowerCase()
+      return suffixes.some((suffix) =>
+        suffix === "" ? extname(path) === "" : lowerPath.endsWith(suffix.toLowerCase())
+      )
+    }
+    accessSync(path, constants.X_OK)
     return true
   } catch {
     return false
   }
 }
 
-export function fileExists(p: string): boolean {
-  return existsSync(p)
-}
-
 // Change-detection primitives (Output Policy in DESIGN.md): operations report
 // changed:boolean so unchanged repeat runs log at verbose instead of [ok].
 
 /** Write only when the content differs; returns whether a write happened. */
-/** Add missing +x bits; returns whether a repair actually happened. */
-export function ensureExecutable(path: string): boolean {
-  const mode = statSync(path).mode
-  const want = mode | 0o111
-  if (mode === want) return false
-  chmodSync(path, want)
-  return true
-}
-
 export function writeTextIfChanged(path: string, content: string): boolean {
   if (existsSync(path) && readFileSync(path, "utf8") === content) return false
   writeFileSync(path, content)

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

@@ -17,12 +17,15 @@ import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } f
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { normalizeManifest, skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+import { ExitError, parseArgs, parseClaudePlugin, parseCompactWindow, validateModifierFlags } from "./parseArgs"
 
 export type ModifierFlag =
   | "--claude-model"
   | "--claude-effort"
   | "--claude-advisor"
+  | "--claude-compact-window"
+  | "--claude-permissive"
+  | "--claude-plugin"
   | "--codex-model"
   | "--codex-effort"
 
@@ -84,7 +87,6 @@ export interface Ctx {
   skipPluginRefresh?: boolean
   reconcile: boolean
   prune: boolean
-  assumeYes: boolean
   claudeCompactWindow: string
   claudePermissive: boolean
   claudePlugins: Array<string>
@@ -117,6 +119,16 @@ export interface Ctx {
 function makeCtx(services: EngineServices): Ctx {
   const env = process.env
   const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir()
+  const compactWindowSource = env["CLAUDE_COMPACT_WINDOW"] ?? ""
+  const claudeCompactWindow = compactWindowSource === "" ? "" : parseCompactWindow(compactWindowSource)
+  if (claudeCompactWindow === undefined) {
+    services.logger.err("CLAUDE_COMPACT_WINDOW expects a token count (e.g. 680000 or 680k)")
+    throw new ExitError(2)
+  }
+  const claudePlugins = (env["CLAUDE_PLUGINS"] ?? "")
+    .split(" ")
+    .filter((plugin) => plugin !== "")
+    .map((plugin) => parseClaudePlugin(plugin, services.logger.err))
   return {
     repoDir: kitHome(),
     home,
@@ -127,10 +139,9 @@ function makeCtx(services: EngineServices): Ctx {
     skipPluginRefresh: false,
     reconcile: env["RECONCILE"] === "1",
     prune: env["PRUNE"] === "1",
-    assumeYes: env["ASSUME_YES"] === "1",
-    claudeCompactWindow: env["CLAUDE_COMPACT_WINDOW"] ?? "",
+    claudeCompactWindow,
     claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
-    claudePlugins: (env["CLAUDE_PLUGINS"] ?? "").split(" ").filter((s) => s !== ""),
+    claudePlugins,
     claudeModel: env["CLAUDE_MODEL"] ?? "",
     claudeEffort: "",
     claudeAdvisor: "",
@@ -278,8 +289,8 @@ export async function runEngineNative(argv: ReadonlyArray<string>, services?: En
     deps: baseServices.deps,
     platform: baseServices.platform
   }
-  ctx = makeCtx(runServices)
   try {
+    ctx = makeCtx(runServices)
     switch (argv[0]) {
       case "model":
         return modeModel(ctx, argv.slice(1))

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

@@ -6,16 +6,9 @@ import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { payloadDisplayPath, payloadText } from "../payload"
 
-function catalog(): Json | undefined {
-  try {
-    return parseJson(payloadText("SoT/models.json"))
-  } catch {
-    return undefined
-  }
-}
 
 function toolEntry(tool: string): { [k: string]: Json } | undefined {
-  const doc = catalog()
+  const doc = parseJson(payloadText("SoT/models.json"))
   if (doc === undefined || !isObject(doc)) return undefined
   const entry = doc[tool]
   return entry !== undefined && isObject(entry) ? entry : undefined
@@ -37,7 +30,7 @@ export function printModels(ctx: Ctx, tool: string): void {
   const { echo, warn } = ctx.services.logger
   const entry = toolEntry(tool)
   if (entry === undefined) {
-    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json", ctx.repoDir)})`)
+    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json")})`)
     return
   }
   const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?"

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

@@ -12,8 +12,7 @@ import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
 import { bunBootstrap } from "./bun"
-import { effectSolutionsInstall } from "./skillsSync"
-import { ensure, report } from "./toolchain"
+import { installedVersion, present, report } from "./toolchain"
 
 export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   const { echo, err, warn } = ctx.services.logger
@@ -37,19 +36,29 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   if (value === "") {
     if (tool === "claude") {
       const deployed = p(ctx.home, ".claude", "settings.json")
-      if (!fileReadable(deployed)) {
+      const result = readConfig(deployed)
+      if (result.kind === "missing") {
         warn("~/.claude/settings.json missing")
         return 0
       }
-      echo(`deployed: ${jsonModelField(deployed)}`)
+      if (result.kind === "read-error") {
+        err(`Failed to read ~/.claude/settings.json: ${String(result.error)}`)
+        return 1
+      }
+      echo(`deployed: ${jsonModelText(result.data)}`)
       echo(`SoT:      ${jsonModelText(payloadText("SoT/.claude/settings.json"))}`)
     } else {
       const deployed = p(ctx.home, ".codex", "config.toml")
-      if (!fileReadable(deployed)) {
+      const result = readConfig(deployed)
+      if (result.kind === "missing") {
         warn("~/.codex/config.toml missing")
         return 0
       }
-      echo(`deployed: ${tomlModelField(deployed)}`)
+      if (result.kind === "read-error") {
+        err(`Failed to read ~/.codex/config.toml: ${String(result.error)}`)
+        return 1
+      }
+      echo(`deployed: ${tomlModelText(result.data)}`)
       echo(`SoT:      ${tomlModelText(payloadText("SoT/.codex/config.toml"))}`)
     }
     printModels(ctx, tool)
@@ -74,20 +83,23 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   return 0
 }
 
-function fileReadable(p: string): boolean {
+type ConfigReadResult =
+  | { readonly kind: "missing" }
+  | { readonly kind: "read-error"; readonly error: unknown }
+  | { readonly kind: "data"; readonly data: string }
+
+function readConfig(file: string): ConfigReadResult {
   try {
-    readFileSync(p)
-    return true
-  } catch {
-    return false
+    return { kind: "data", data: readFileSync(file, "utf8") }
+  } catch (error) {
+    const code =
+      typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        ? error.code
+        : undefined
+    return code === "ENOENT" ? { kind: "missing" } : { kind: "read-error", error }
   }
 }
 
-/** `jq -r '.model // "default (unset)"'` — empty on unparseable input. */
-function jsonModelField(file: string): string {
-  return jsonModelText(readFileSync(file, "utf8"))
-}
-
 function jsonModelText(text: string): string {
   const doc = parseJson(text)
   if (doc === undefined) return ""
@@ -97,9 +109,6 @@ function jsonModelText(text: string): string {
 }
 
 /** `awk -F'"' '/^model[[:space:]]*=/{print $2; exit}'`. */
-function tomlModelField(file: string): string {
-  return tomlModelText(readFileSync(file, "utf8"))
-}
 
 function tomlModelText(text: string): string {
   for (const line of text.split("\n")) {
@@ -109,15 +118,12 @@ function tomlModelText(text: string): string {
 }
 
 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"
-  const tool = words[1] ?? args[1] ?? ""
+  const { echo, err, verbose } = ctx.services.logger
+  const words = args.filter((arg) => !arg.startsWith("--"))
+  const op = words[0] ?? "check"
+  const tool = words[1] ?? ""
   for (const arg of args) {
-    if (arg === "--yes") ctx.assumeYes = true
-    else if (arg === "--verbose") {
-      ctx.verbose = true
-    }
+    if (arg === "--verbose") ctx.verbose = true
   }
 
   if (op === "check") {
@@ -125,20 +131,33 @@ export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Prom
     return 0
   }
   if (op !== "ensure") {
-    err("Usage: toolchain [check|ensure <tool>] [--yes]")
+    err("Usage: toolchain [check|ensure <tool>]")
     return 2
   }
-  if (tool === "" || tool === "--yes") {
-    err("Usage: toolchain ensure <tool> [--yes]")
+  if (tool === "") {
+    err("Usage: toolchain ensure <tool>")
     return 2
   }
   switch (tool) {
-    case "bun":
-      return (await bunBootstrap(ctx, ctx.services)).kind === "ready" ? 0 : 1
-    case "effect-solutions":
-      return await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
+    case "bun": {
+      // `bun` is the one managed tool, and its bootstrap is silent when Bun is
+      // already installed. Probe first so the no-op confirmation the `--verbose`
+      // contract promises is not mistaken for a fresh install.
+      const alreadyInstalled = present(ctx, "bun")
+      if ((await bunBootstrap(ctx, ctx.services)).kind !== "ready") return 1
+      if (alreadyInstalled) {
+        // A present tool whose --version cannot be read reports `unknown` in the
+        // doctor table; keep the same vocabulary rather than an empty pair of
+        // parentheses.
+        const probed = await installedVersion(ctx, "bun")
+        const installed = probed === "" ? "version unknown" : probed
+        if (ctx.dryRun) echo(`[dry-run] bun up to date (${installed})`)
+        else verbose(`bun up to date (${installed})`)
+      }
+      return 0
+    }
     default:
-      err("toolchain ensure supports managed tools only (bun, effect-solutions)")
+      err("toolchain ensure supports managed tools only (bun)")
       return 2
   }
 }

package/cli/src/engine-native/os/darwin.ts

@@ -0,0 +1,62 @@
+import { p } from "../exec"
+import type { HostOs } from "./types"
+
+function posixLiteral(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
+export const darwin: HostOs = {
+  id: "darwin",
+  toolchainOs: "darwin",
+  supportsBubblewrap: false,
+  directoryLinkKinds: ["symlink"],
+  executableSuffixes: [""],
+  invoke: (executablePath, args) => ({ command: executablePath, args }),
+  bunExecutableName: "bun",
+  bunInstaller: (pin, directory) => {
+    const scriptPath = p(directory, "install.sh")
+    return {
+      scriptPath,
+      download: {
+        command: "curl",
+        args: ["-fsSL", "https://bun.sh/install", "-o", scriptPath]
+      },
+      run: {
+        command: "bash",
+        args: [scriptPath, `bun-v${pin}`]
+      }
+    }
+  },
+  environmentSetting: (name, value) => ({
+    kind: "profile",
+    candidates: [".zshrc", ".bashrc", ".bash_profile", ".profile", ".zshenv"],
+    target: (shell) => {
+      const shellPath = shell ?? "bash"
+      const shellName = shellPath.slice(shellPath.lastIndexOf("/") + 1)
+      return shellName === "zsh" ? ".zshrc" : shellName === "bash" ? ".bashrc" : ".profile"
+    },
+    line: `export ${name}=${value}`
+  }),
+  statusLineCommand: (bun, script) => {
+    const bunLiteral = posixLiteral(bun)
+    const scriptLiteral = posixLiteral(script)
+    return `test -x ${bunLiteral} && test -f ${scriptLiteral} && exec ${bunLiteral} ${scriptLiteral} || true`
+  },
+  failureHookCommand: (command) => command,
+  installHint: (tool) => {
+    switch (tool) {
+      case "git":
+        return "brew install git"
+      case "jq":
+        return "brew install jq"
+      case "curl":
+        return "brew install curl"
+      case "ffplay":
+        return "brew install ffmpeg"
+      case "claude":
+        return "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh"
+      case "codex":
+        return 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"'
+    }
+  }
+}

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

@@ -0,0 +1,42 @@
+import { darwin } from "./darwin"
+import { linux } from "./linux"
+import type { HostOs, PlatformName } from "./types"
+import { windows } from "./windows"
+
+export * from "./types"
+
+export function rawPlatform(): NodeJS.Platform {
+  return process.platform
+}
+
+export function platformName(pf: NodeJS.Platform = rawPlatform()): PlatformName {
+  switch (pf) {
+    case "linux":
+      return "linux"
+    case "darwin":
+      return "darwin"
+    case "win32":
+      return "windows"
+    default:
+      return "unknown"
+  }
+}
+
+// An unrecognized host keeps Linux hint text, filters no toolchain row, and never claims bubblewrap — exactly today's behavior.
+const unknown: HostOs = {
+  ...linux,
+  id: "unknown",
+  toolchainOs: "",
+  supportsBubblewrap: false
+}
+
+const HOSTS: Readonly<Record<PlatformName, HostOs>> = {
+  linux,
+  darwin,
+  windows,
+  unknown
+}
+
+export function hostOs(id: PlatformName = platformName()): HostOs {
+  return HOSTS[id]
+}

package/cli/src/engine-native/os/linux.ts

@@ -0,0 +1,62 @@
+import { p } from "../exec"
+import type { HostOs } from "./types"
+
+function posixLiteral(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
+export const linux: HostOs = {
+  id: "linux",
+  toolchainOs: "linux",
+  supportsBubblewrap: true,
+  directoryLinkKinds: ["symlink"],
+  executableSuffixes: [""],
+  invoke: (executablePath, args) => ({ command: executablePath, args }),
+  bunExecutableName: "bun",
+  bunInstaller: (pin, directory) => {
+    const scriptPath = p(directory, "install.sh")
+    return {
+      scriptPath,
+      download: {
+        command: "curl",
+        args: ["-fsSL", "https://bun.sh/install", "-o", scriptPath]
+      },
+      run: {
+        command: "bash",
+        args: [scriptPath, `bun-v${pin}`]
+      }
+    }
+  },
+  environmentSetting: (name, value) => ({
+    kind: "profile",
+    candidates: [".zshrc", ".bashrc", ".bash_profile", ".profile", ".zshenv"],
+    target: (shell) => {
+      const shellPath = shell ?? "bash"
+      const shellName = shellPath.slice(shellPath.lastIndexOf("/") + 1)
+      return shellName === "zsh" ? ".zshrc" : shellName === "bash" ? ".bashrc" : ".profile"
+    },
+    line: `export ${name}=${value}`
+  }),
+  statusLineCommand: (bun, script) => {
+    const bunLiteral = posixLiteral(bun)
+    const scriptLiteral = posixLiteral(script)
+    return `test -x ${bunLiteral} && test -f ${scriptLiteral} && exec ${bunLiteral} ${scriptLiteral} || true`
+  },
+  failureHookCommand: (command) => command,
+  installHint: (tool) => {
+    switch (tool) {
+      case "git":
+        return "sudo apt install -y git (or your distro's package manager)"
+      case "jq":
+        return "sudo apt install -y jq"
+      case "curl":
+        return "sudo apt install -y curl"
+      case "ffplay":
+        return "sudo apt install -y ffmpeg"
+      case "claude":
+        return "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh"
+      case "codex":
+        return 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"'
+    }
+  }
+}

package/cli/src/engine-native/os/targets.ts

@@ -0,0 +1,73 @@
+/**
+ * Host-to-artifact map (Platform seam in DESIGN.md). Every launcher, installer,
+ * build script, and release workflow selects a compiled binary from this one
+ * table; cli/test/unit/hostTargets.test.ts parses those scripts and fails when
+ * any of them drifts from it.
+ *
+ * Membership here is the support matrix: adding a row is how a host becomes
+ * supported, and `requireSupportedHost` in cli/src/engine.ts admits exactly the
+ * platform/arch pairs this table names.
+ */
+import { platformName, type PlatformName } from "./index"
+
+export type TargetId =
+  | "linux-x64"
+  | "linux-arm64"
+  | "darwin-x64"
+  | "darwin-arm64"
+  | "windows-x64"
+  | "windows-arm64"
+
+export type TargetArch = "x64" | "arm64"
+
+export interface HostTarget {
+  readonly id: TargetId
+  readonly platform: PlatformName
+  readonly arch: TargetArch
+  /** `bun build --compile --target=` value. */
+  readonly bunTarget: string
+  /** Compiled binary file name, including the Windows `.exe` suffix. */
+  readonly artifact: string
+  /** `uname -s`-`uname -m` keys the Bash launcher matches; empty on Windows. */
+  readonly unameKeys: ReadonlyArray<string>
+  /**
+   * `$env:PROCESSOR_ARCHITECTURE` values the PowerShell launcher matches; empty
+   * off Windows. Windows PowerShell 5.1 runs emulated on ARM64 and reports
+   * `AMD64` there, so a launcher must read `PROCESSOR_ARCHITEW6432` first.
+   */
+  readonly processorArchitectures: ReadonlyArray<string>
+}
+
+const target = (
+  id: TargetId,
+  platform: PlatformName,
+  arch: TargetArch,
+  unameKeys: ReadonlyArray<string>,
+  processorArchitectures: ReadonlyArray<string>
+): HostTarget => ({
+  id,
+  platform,
+  arch,
+  bunTarget: `bun-${id}`,
+  artifact: platform === "windows" ? `docks-kit-${id}.exe` : `docks-kit-${id}`,
+  unameKeys,
+  processorArchitectures
+})
+
+export const HOST_TARGETS: ReadonlyArray<HostTarget> = [
+  target("linux-x64", "linux", "x64", ["Linux-x86_64"], []),
+  target("linux-arm64", "linux", "arm64", ["Linux-aarch64"], []),
+  target("darwin-x64", "darwin", "x64", ["Darwin-x86_64"], []),
+  target("darwin-arm64", "darwin", "arm64", ["Darwin-arm64"], []),
+  target("windows-x64", "windows", "x64", [], ["AMD64"]),
+  target("windows-arm64", "windows", "arm64", [], ["ARM64"])
+]
+
+export function targetFor(platform: PlatformName, arch: string): HostTarget | undefined {
+  return HOST_TARGETS.find((t) => t.platform === platform && t.arch === arch)
+}
+
+/** Resolve the artifact for a raw Node platform/arch pair. */
+export function targetForHost(platform: NodeJS.Platform, arch: string): HostTarget | undefined {
+  return targetFor(platformName(platform), arch)
+}

package/cli/src/engine-native/os/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Host modules own only facts that cannot be probed. Anything that can fail at
+ * runtime stays try-then-fallback at the call site; a host module contributes
+ * only the order of that fallback chain.
+ */
+
+export type PlatformName = "linux" | "darwin" | "windows" | "unknown"
+/** Directory-link mechanisms, tried in order before the copy fallback. */
+export type DirectoryLinkKind = "symlink" | "junction"
+/** Tools whose install command differs per host OS. */
+export type HintedTool = "git" | "jq" | "curl" | "ffplay" | "claude" | "codex"
+
+/** A command plus argv, already shaped for how this host must invoke it. */
+export interface Invocation {
+  readonly command: string
+  readonly args: ReadonlyArray<string>
+  /** Preserve a fully quoted Windows command line instead of applying libuv quoting. */
+  readonly windowsVerbatimArguments?: boolean
+}
+
+/** How this host persists a user-level environment variable. */
+export type EnvironmentSetting =
+  | {
+      readonly kind: "profile"
+      /** Home-relative files scanned for an existing setting. */
+      readonly candidates: ReadonlyArray<string>
+      /** Home-relative file that receives the write for this shell. */
+      readonly target: (shell: string | undefined) => string
+      /** Line appended to the target file. */
+      readonly line: string
+    }
+  | {
+      readonly kind: "command"
+      /** Exits zero when the variable is already persisted. */
+      readonly probe: Invocation
+      /** Persists the variable. */
+      readonly apply: Invocation
+      /** Where the value lands, named for the log line. */
+      readonly location: string
+      /** Manual recovery when `apply` fails. */
+      readonly manualHint: string
+    }
+
+/** The two steps that fetch and run a pinned Bun installer. */
+export interface BunInstaller {
+  readonly scriptPath: string
+  readonly download: Invocation
+  readonly run: Invocation
+}
+
+export interface HostOs {
+  readonly id: PlatformName
+  /** `SoT/toolchain.json` `os` field this host matches; "" matches every row. */
+  readonly toolchainOs: string
+  /** Bubblewrap is the Linux-only Codex sandbox runtime. */
+  readonly supportsBubblewrap: boolean
+  /** Directory-link mechanisms tried in order before `skillsSync.ts linkOrCopy` copies. */
+  readonly directoryLinkKinds: ReadonlyArray<DirectoryLinkKind>
+  /** One-line install command for a tool whose package differs per OS. */
+  readonly installHint: (tool: HintedTool) => string
+  /** Filename suffixes tried in order when resolving a bare tool name on PATH. */
+  readonly executableSuffixes: ReadonlyArray<string>
+  /** Shape the argv that actually runs a resolved executable on this host. */
+  readonly invoke: (executablePath: string, args: ReadonlyArray<string>) => Invocation
+  /** Bun executable filename inside `<bunRoot>/bin`. */
+  readonly bunExecutableName: string
+  /** Download-then-run installer for a pinned Bun version placed in `directory`. */
+  readonly bunInstaller: (pin: string, directory: string) => BunInstaller
+  /** How this host persists a user-level environment variable. */
+  readonly environmentSetting: (name: string, value: string) => EnvironmentSetting
+  /** Claude `statusLine.command` for a resolved bun executable and script. */
+  readonly statusLineCommand: (bun: string, script: string) => string
+  /** Reshape the SoT `PostToolUseFailure` command for this host's shell. */
+  readonly failureHookCommand: (command: string) => string
+}