docks-kit 0.2.0 → 0.4.0

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

@@ -4,25 +4,26 @@
  * change. Guard order, message strings, and backup behavior are golden-tested.
  */
 import { spawnSync } from "node:child_process"
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 
 import { syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
 import { p } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
+import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
 
 export function codexSync(ctx: Ctx): void {
   const codexDir = p(ctx.home, ".codex")
-  const sotConfig = p(ctx.repoDir, "SoT", ".codex", "config.toml")
+  const sotConfig = payloadText("SoT/.codex/config.toml")
   const userConfig = p(codexDir, "config.toml")
 
   ensureBubblewrap(ctx)
   if (!ctx.dryRun) mkdirSync(codexDir, { recursive: true })
   syncConfig(ctx, sotConfig, userConfig)
   syncCodexModel(ctx, ctx.codexModel)
-  syncRules(ctx, p(ctx.repoDir, "SoT", ".codex", "rules"), p(codexDir, "rules"))
-  syncAgentsMd(ctx, p(ctx.repoDir, "SoT", ".codex", "AGENTS.md"), p(codexDir, "AGENTS.md"))
-  syncMarketplace(ctx, p(ctx.repoDir, "SoT", ".codex", "plugins", "marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
+  syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"))
+  syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"))
+  syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
   removeLegacyDocksMarketplace(ctx, userConfig)
   syncPlugins(ctx, sotConfig)
 }
@@ -95,9 +96,9 @@ function bwrapDetectPmInstallCmd(ctx: Ctx): string {
 
 // --------------------------------------------------------------- config ----
 
-function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
+function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  if (!existsSync(sotConfig)) return
+  const sotConfig = payloadDisplayPath("SoT/.codex/config.toml", ctx.repoDir)
 
   if (ctx.dryRun) {
     echo(`[dry-run] merge ${sotConfig} -> ${userConfig}`)
@@ -105,7 +106,7 @@ function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
   }
 
   if (!existsSync(userConfig)) {
-    copyFileSync(sotConfig, userConfig)
+    writeFileSync(userConfig, sotConfigText)
     change("Codex config installed")
     ctx.nextStepTriggers.codexRestart = true
     return
@@ -119,8 +120,8 @@ function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
   writeFileSync(staging, before)
 
   scrubDeprecatedFeatures(ctx, staging)
-  mergeTopLevelSettings(sotConfig, staging)
-  mergeTableSettings(sotConfig, staging)
+  mergeTopLevelSettings(sotConfigText, staging)
+  mergeTableSettings(sotConfigText, staging)
 
   if (readFileSync(staging, "utf8") === before) {
     rmSync(staging, { force: true })
@@ -179,8 +180,8 @@ function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
   change("Codex: scrubbed deprecated [features].use_legacy_landlock")
 }
 
-function mergeTopLevelSettings(sotConfig: string, userConfig: string): void {
-  for (const line of readFileSync(sotConfig, "utf8").split("\n")) {
+function mergeTopLevelSettings(sotConfigText: string, userConfig: string): void {
+  for (const line of sotConfigText.split("\n")) {
     if (line.startsWith("[")) break
     if (/^[ \t]*($|#)/.test(line)) continue
     if (!/^[A-Za-z0-9_.-]+[ \t]*=/.test(line)) continue
@@ -189,8 +190,8 @@ function mergeTopLevelSettings(sotConfig: string, userConfig: string): void {
   }
 }
 
-function mergeTableSettings(sotConfig: string, userConfig: string): void {
-  const sotLines = readFileSync(sotConfig, "utf8").split("\n")
+function mergeTableSettings(sotConfigText: string, userConfig: string): void {
+  const sotLines = sotConfigText.split("\n")
   for (const tableHeader of sotLines.filter((l) => /^\[[^\]]+\]/.test(l))) {
     // Extract the SoT block: from the exact header line to (excluding) the
     // next table header; `$(...)` strips trailing newlines.
@@ -225,9 +226,12 @@ function mergeTableSettings(sotConfig: string, userConfig: string): void {
 
 // ------------------------------------------------------- rules + agents ----
 
-function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
+function syncRules(ctx: Ctx, sotRules: ReadonlyArray<PayloadPath>, userRulesDir: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  if (!existsSync(sotRulesDir)) return
+  const firstRule = sotRules[0]
+  if (firstRule === undefined) return
+  const firstDisplay = payloadDisplayPath(firstRule, ctx.repoDir)
+  const sotRulesDir = firstDisplay.slice(0, firstDisplay.lastIndexOf("/"))
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotRulesDir}/*.rules -> ${userRulesDir}/`)
@@ -237,17 +241,15 @@ function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
   mkdirSync(userRulesDir, { recursive: true })
   let sawRules = false
   let rulesChanged = false
-  const ruleFiles = readdirSync(sotRulesDir, { withFileTypes: true })
-    .filter((e) => e.isFile() && e.name.endsWith(".rules"))
-    .map((e) => p(sotRulesDir, e.name))
-    .sort(compareCodepoints)
+  const ruleFiles = sotRules.filter((path) => path.endsWith(".rules")).sort(compareCodepoints)
   for (const ruleFile of ruleFiles) {
     sawRules = true
     const userRuleFile = p(userRulesDir, ruleFile.slice(ruleFile.lastIndexOf("/") + 1))
-    const identical = existsSync(userRuleFile) && readFileSync(userRuleFile).equals(readFileSync(ruleFile))
+    const content = payloadBytes(ruleFile)
+    const identical = existsSync(userRuleFile) && readFileSync(userRuleFile).equals(content)
     if (identical) continue
     if (existsSync(userRuleFile)) copyFileSync(userRuleFile, `${userRuleFile}.bak`)
-    copyFileSync(ruleFile, userRuleFile)
+    writeFileSync(userRuleFile, content)
     rulesChanged = true
   }
   if (rulesChanged) {
@@ -256,30 +258,30 @@ function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
   } else if (sawRules) verbose("Codex rules already in sync")
 }
 
-function syncAgentsMd(ctx: Ctx, sotAgentsMd: string, userAgentsMd: string): void {
+function syncAgentsMd(ctx: Ctx, sotAgentsMdText: string, userAgentsMd: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  if (!existsSync(sotAgentsMd)) return
+  const sotAgentsMd = payloadDisplayPath("SoT/.codex/AGENTS.md", ctx.repoDir)
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotAgentsMd} -> ${userAgentsMd}`)
     return
   }
 
-  if (existsSync(userAgentsMd) && readFileSync(userAgentsMd).equals(readFileSync(sotAgentsMd))) {
+  if (existsSync(userAgentsMd) && readFileSync(userAgentsMd, "utf8") === sotAgentsMdText) {
     verbose("Codex AGENTS.md already in sync")
     return
   }
   if (existsSync(userAgentsMd)) copyFileSync(userAgentsMd, `${userAgentsMd}.bak`)
-  copyFileSync(sotAgentsMd, userAgentsMd)
+  writeFileSync(userAgentsMd, sotAgentsMdText)
   change("Codex AGENTS.md synced")
   ctx.nextStepTriggers.codexRestart = true
 }
 
 // ---------------------------------------------------------- marketplace ----
 
-function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: string): void {
+function syncMarketplace(ctx: Ctx, sotMarketplaceText: string, userMarketplace: string): void {
   const { change, echo, err, verbose } = ctx.services.logger
-  if (!existsSync(sotMarketplace)) return
+  const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json", ctx.repoDir)
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotMarketplace} -> ${userMarketplace}`)
@@ -287,7 +289,7 @@ function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: stri
   }
 
   mkdirSync(p(ctx.agentsDir, "plugins"), { recursive: true })
-  const repo = parseJson(readFileSync(sotMarketplace, "utf8"))
+  const repo = parseJson(sotMarketplaceText)
   if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`)
 
   if (existsSync(userMarketplace)) {
@@ -307,7 +309,7 @@ function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: stri
     change("Codex marketplace merged (backup at marketplace.json.bak)")
     ctx.nextStepTriggers.codexRestart = true
   } else {
-    copyFileSync(sotMarketplace, userMarketplace)
+    writeFileSync(userMarketplace, sotMarketplaceText)
     change("Codex marketplace installed")
     ctx.nextStepTriggers.codexRestart = true
   }
@@ -390,13 +392,17 @@ const standaloneInstallCommand = (ctx: Ctx): string => ctx.services.deps.spec("c
 /** codex::_enabled_plugin_ids — [plugins."<id>"] tables with enabled = true. */
 export function enabledPluginIds(configFile: string): Array<string> {
   if (!existsSync(configFile)) return []
+  return enabledPluginIdsFromText(readFileSync(configFile, "utf8"))
+}
+
+export function enabledPluginIdsFromText(configText: string): Array<string> {
   const ids: Array<string> = []
   let plugin = ""
   let enabled = false
   const flush = (): void => {
     if (plugin !== "" && enabled) ids.push(plugin)
   }
-  for (const line of readFileSync(configFile, "utf8").split("\n")) {
+  for (const line of configText.split("\n")) {
     const m = /^\[plugins\."([^"]+)"\][ \t]*$/.exec(line)
     if (m !== null) {
       flush()
@@ -418,12 +424,12 @@ export function enabledPluginIds(configFile: string): Array<string> {
   return ids
 }
 
-function manualPluginRefreshCommand(sotConfig: string): string {
-  const first = enabledPluginIds(sotConfig)[0]
+function manualPluginRefreshCommand(sotConfigText: string): string {
+  const first = enabledPluginIdsFromText(sotConfigText)[0]
   return first !== undefined ? `codex plugin add ${first}` : "codex plugin add <plugin@marketplace>"
 }
 
-function syncPlugins(ctx: Ctx, sotConfig: string): void {
+function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   const { change, echo, warn } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] add enabled Codex plugins from SoT")
@@ -432,7 +438,7 @@ function syncPlugins(ctx: Ctx, sotConfig: string): void {
 
   if (ctx.services.deps.probe("codex").state === "missing") {
     warn(
-      `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli; then run: ${manualPluginRefreshCommand(sotConfig)}`
+      `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli; then run: ${manualPluginRefreshCommand(sotConfigText)}`
     )
     return
   }
@@ -447,7 +453,7 @@ function syncPlugins(ctx: Ctx, sotConfig: string): void {
 
   let refreshed = 0
   let failed = 0
-  for (const pluginId of enabledPluginIds(sotConfig)) {
+  for (const pluginId of enabledPluginIdsFromText(sotConfigText)) {
     const res = spawnSync("codex", ["plugin", "add", pluginId], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
     const addOut = `${res.stdout ?? ""}${res.stderr ?? ""}`
     if (res.error === undefined && res.status === 0) {

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

@@ -8,6 +8,7 @@
  * command that installs a missing one.
  */
 import { homedir } from "node:os"
+import { isAbsolute } from "node:path"
 import { existsSync, readdirSync } from "node:fs"
 
 import { capture, commandExists, p, which } from "./exec"
@@ -110,21 +111,34 @@ const home = (): string => {
   return envHome !== undefined && envHome !== "" ? envHome : homedir()
 }
 
-const findBun = (exec: ProbeExecutor): { command: string; path: string } | undefined => {
+const absoluteWindowsExe = (path: string): boolean =>
+  /\.exe$/i.test(path) && (/^[A-Za-z]:[\\/]/.test(path) || /^\\\\/.test(path))
+
+// The resolved path gets persisted into global direct-exec hooks, so a
+// relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
+// break outside the sync working directory.
+const absoluteExecutable = (path: string, platform: NodeJS.Platform): boolean =>
+  platform === "win32" ? absoluteWindowsExe(path) : isAbsolute(path)
+
+const findBun = (exec: ProbeExecutor, platform: NodeJS.Platform = rawPlatform()): { command: string; path: string } | undefined => {
   const onPath = exec.which("bun")
-  if (onPath !== "") return { command: "bun", path: onPath }
+  if (onPath !== "" && absoluteExecutable(onPath, platform)) {
+    return { command: platform === "win32" ? onPath : "bun", path: onPath }
+  }
   const root =
     process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
       ? process.env["BUN_INSTALL"]!
       : p(home(), ".bun")
-  for (const candidate of [p(root, "bin", "bun"), p(home(), ".bun", "bin", "bun")]) {
-    if (exec.which(candidate) !== "") return { command: candidate, path: candidate }
+  const name = platform === "win32" ? "bun.exe" : "bun"
+  for (const candidate of [p(root, "bin", name), p(home(), ".bun", "bin", name)]) {
+    const found = exec.which(candidate)
+    if (found !== "" && absoluteExecutable(found, platform)) return { command: found, path: found }
   }
   return undefined
 }
 
-const resolveBun = (exec: ProbeExecutor): ProbeResult => {
-  const bun = findBun(exec)
+const resolveBun = (exec: ProbeExecutor, platform: NodeJS.Platform): ProbeResult => {
+  const bun = findBun(exec, platform)
   return bun === undefined
     ? { state: "missing" }
     : { state: "present", path: bun.path }
@@ -147,7 +161,9 @@ const versionEffectSolutions = (exec: ProbeExecutor): string => {
 }
 
 const locateEffectSolutions = (exec: ProbeExecutor, platform: NodeJS.Platform): DependencyLocation => {
-  const bun = findBun(exec)
+  const strictBun = findBun(exec, platform)
+  const pathBun = exec.which("bun")
+  const bun = strictBun ?? (pathBun !== "" ? { command: "bun", path: pathBun } : undefined)
   if (bun === undefined) return { path: "", binDir: "" }
   const globalBin = exec.capture(bun.command, ["pm", "-g", "bin"])
   const names =
@@ -180,6 +196,7 @@ const resolveChrome = (exec: ProbeExecutor, platform: NodeJS.Platform): ProbeRes
 }
 
 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"])
   )
@@ -204,7 +221,7 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
           : "sudo apt install -y git (or your distro's package manager)",
     { version: versionProbe("git") }
   ),
-  jq: spec("jq", "required", (pf = rawPlatform()) =>
+  jq: spec("jq", "optional", (pf = rawPlatform()) =>
     pf === "win32"
       ? "winget install jqlang.jq (then open a new terminal)"
       : pf === "darwin"
@@ -212,7 +229,7 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
         : "sudo apt install -y jq",
     { version: versionProbe("jq") }
   ),
-  curl: spec("curl", "required", (pf = rawPlatform()) =>
+  curl: spec("curl", "optional", (pf = rawPlatform()) =>
     pf === "win32" ? "winget install cURL.cURL" : pf === "darwin" ? "brew install curl" : "sudo apt install -y curl",
     { version: versionProbe("curl") }
   ),
@@ -251,7 +268,7 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     {
       resolve: resolveBun,
       version: (exec) => exec.capture(versionBunCommand(exec), ["--version"]),
-      locate: (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
+      locate: (exec, platform) => ({ path: findBun(exec, platform)?.path ?? "", binDir: "" })
     }
   ),
   bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)"),

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

@@ -4,7 +4,7 @@
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
 import { spawnSync } from "node:child_process"
-import { accessSync, chmodSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { accessSync, chmodSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { delimiter, isAbsolute, join } from "node:path"
 
 /**
@@ -69,34 +69,19 @@ export function ensureExecutable(path: string): boolean {
   return true
 }
 
-export function writeFileIfChanged(path: string, content: string): boolean {
+export function writeTextIfChanged(path: string, content: string): boolean {
   if (existsSync(path) && readFileSync(path, "utf8") === content) return false
   writeFileSync(path, content)
   return true
 }
 
-/** Copy only when dest differs from src; returns whether a copy happened. */
-export function copyFileIfChanged(src: string, dest: string): boolean {
-  if (existsSync(dest) && readFileSync(dest).equals(readFileSync(src))) return false
-  copyFileSync(src, dest)
+export function writeBytesIfChanged(path: string, content: Uint8Array): boolean {
+  const bytes = Buffer.from(content)
+  if (existsSync(path) && readFileSync(path).equals(bytes)) return false
+  writeFileSync(path, bytes)
   return true
 }
 
-/** Recursive copy via copyFileIfChanged; returns whether anything changed. */
-export function copyTreeIfChanged(srcDir: string, destDir: string): boolean {
-  let changed = false
-  for (const e of readdirSync(srcDir, { withFileTypes: true })) {
-    const src = p(srcDir, e.name)
-    const dest = p(destDir, e.name)
-    if (e.isDirectory()) {
-      if (!existsSync(dest)) {
-        mkdirSync(dest, { recursive: true })
-        changed = true
-      }
-      if (copyTreeIfChanged(src, dest)) changed = true
-    } else if (copyFileIfChanged(src, dest)) {
-      changed = true
-    }
-  }
-  return changed
+export function writeFileIfChanged(path: string, content: string): boolean {
+  return writeTextIfChanged(path, content)
 }

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

@@ -6,16 +6,16 @@
  * vocabulary directly.
  */
 import { p } from "./exec"
-import { existsSync } from "node:fs"
 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 { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, preflight, validateModelFlags } from "./parseArgs"
+import { ExitError, parseArgs, validateModelFlags } from "./parseArgs"
 
 export interface Ctx {
   readonly repoDir: string
@@ -34,6 +34,7 @@ export interface Ctx {
   codexModel: string
   /** Injected capability seam (logger/deps/platform) — see services.ts. */
   readonly services: EngineServices
+  bunRuntime?: BunRuntimeState
   targetFilterSet: boolean
   syncClaude: boolean
   syncCodex: boolean
@@ -78,21 +79,20 @@ function makeCtx(services: EngineServices): Ctx {
 function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   const { echo } = ctx.services.logger
   parseArgs(ctx, args)
-  preflight(ctx)
   validateModelFlags(ctx)
 
-  const claudeRan = ctx.syncClaude && existsSync(p(ctx.repoDir, "SoT", ".claude"))
-  if (claudeRan) claudeSync(ctx)
+  const claudeRan = ctx.syncClaude
+  const claudeRuntime = claudeRan ? claudeSync(ctx) : undefined
 
-  const codexRan = ctx.syncCodex && existsSync(p(ctx.repoDir, "SoT", ".codex"))
+  const codexRan = ctx.syncCodex
   if (codexRan) codexSync(ctx)
 
-  const skillsState = ctx.syncAgents && existsSync(p(ctx.repoDir, "SoT", ".agents")) ? skillsSync(ctx) : undefined
+  const skillsState = ctx.syncAgents ? skillsSync(ctx) : undefined
 
   echo("")
   echo("--- Sync complete ---")
   echo(`Repo:     ${ctx.repoDir}`)
-  if (claudeRan) claudeSummary(ctx)
+  if (claudeRuntime !== undefined) claudeSummary(ctx, claudeRuntime)
   if (codexRan) codexSummary(ctx)
   if (skillsState !== undefined) skillsSummary(ctx, skillsState)
 

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

@@ -2,49 +2,47 @@
  * Model-catalog helpers: manifest listing plus Claude/Codex model validation.
  * Message strings are covered by the golden suites.
  */
-import { p } from "./exec"
-import { readFileSync } from "node:fs"
-
 import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
+import { payloadDisplayPath, payloadText } from "../payload"
 
-function catalog(repoDir: string): Json | undefined {
+function catalog(): Json | undefined {
   try {
-    return parseJson(readFileSync(p(repoDir, "SoT", "models.json"), "utf8"))
+    return parseJson(payloadText("SoT/models.json"))
   } catch {
     return undefined
   }
 }
 
-function toolEntry(repoDir: string, tool: string): { [k: string]: Json } | undefined {
-  const doc = catalog(repoDir)
+function toolEntry(tool: string): { [k: string]: Json } | undefined {
+  const doc = catalog()
   if (doc === undefined || !isObject(doc)) return undefined
   const entry = doc[tool]
   return entry !== undefined && isObject(entry) ? entry : undefined
 }
 
-function modelEntries(repoDir: string, tool: string): Array<{ [k: string]: Json }> {
-  const entry = toolEntry(repoDir, tool)
+function modelEntries(tool: string): Array<{ [k: string]: Json }> {
+  const entry = toolEntry(tool)
   const models = entry?.["models"]
   return Array.isArray(models) ? models.filter(isObject) : []
 }
 
-export function modelsFromManifest(repoDir: string, tool: string): Array<string> {
-  return modelEntries(repoDir, tool)
+export function modelsFromManifest(tool: string): Array<string> {
+  return modelEntries(tool)
     .map((m) => m["id"])
     .filter((id): id is string => typeof id === "string")
 }
 
 export function printModels(ctx: Ctx, tool: string): void {
   const { echo, warn } = ctx.services.logger
-  const entry = toolEntry(ctx.repoDir, tool)
+  const entry = toolEntry(tool)
   if (entry === undefined) {
-    warn(`Model catalog unavailable (${p(ctx.repoDir, "SoT", "models.json")})`)
+    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json", ctx.repoDir)})`)
     return
   }
   const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?"
   const lines = [`Available ${tool} models (kit-verified ${verified} — SoT/models.json):`]
-  for (const m of modelEntries(ctx.repoDir, tool)) {
+  for (const m of modelEntries(tool)) {
     const note = typeof m["note"] === "string" ? `  — ${m["note"]}` : ""
     lines.push(`  ${String(m["id"] ?? "")}${note}`)
   }
@@ -55,7 +53,7 @@ export function printModels(ctx: Ctx, tool: string): void {
 
 export function validateClaudeModel(ctx: Ctx, m: string): boolean {
   if (m === "") return false
-  if (modelsFromManifest(ctx.repoDir, "claude").includes(m)) return true
+  if (modelsFromManifest("claude").includes(m)) return true
   if (m.startsWith("claude-")) {
     ctx.services.logger.warn(`Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`)
     return true
@@ -65,7 +63,7 @@ export function validateClaudeModel(ctx: Ctx, m: string): boolean {
 
 export function validateCodexModel(ctx: Ctx, m: string): boolean {
   if (!/^[A-Za-z0-9._-]+$/.test(m)) return false
-  if (!modelsFromManifest(ctx.repoDir, "codex").includes(m)) {
+  if (!modelsFromManifest("codex").includes(m)) {
     ctx.services.logger.warn(
       `Codex model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway (check ~/.codex/config.toml if Codex rejects it)`
     )

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

@@ -4,14 +4,16 @@
  */
 import { p } from "./exec"
 import { readFileSync } from "node:fs"
+import { payloadText } from "../payload"
 
 import { syncClaudeModel } from "./claudeModel"
 import { syncCodexModel } from "./codexToml"
 import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
-import { rtkInstall } from "./claudeSync"
-import { agentBrowserInstall, bunBootstrap, effectSolutionsInstall } from "./skillsSync"
+import { ensureRtk } from "./claudeSync"
+import { bunBootstrap } from "./bun"
+import { agentBrowserInstall, effectSolutionsInstall } from "./skillsSync"
 import { ensure, report } from "./toolchain"
 
 export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
@@ -41,7 +43,7 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
         return 0
       }
       echo(`deployed: ${jsonModelField(deployed)}`)
-      echo(`SoT:      ${jsonModelField(p(ctx.repoDir, "SoT", ".claude", "settings.json"))}`)
+      echo(`SoT:      ${jsonModelText(payloadText("SoT/.claude/settings.json"))}`)
     } else {
       const deployed = p(ctx.home, ".codex", "config.toml")
       if (!fileReadable(deployed)) {
@@ -49,7 +51,7 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
         return 0
       }
       echo(`deployed: ${tomlModelField(deployed)}`)
-      echo(`SoT:      ${tomlModelField(p(ctx.repoDir, "SoT", ".codex", "config.toml"))}`)
+      echo(`SoT:      ${tomlModelText(payloadText("SoT/.codex/config.toml"))}`)
     }
     printModels(ctx, tool)
     return 0
@@ -84,7 +86,11 @@ function fileReadable(p: string): boolean {
 
 /** `jq -r '.model // "default (unset)"'` — empty on unparseable input. */
 function jsonModelField(file: string): string {
-  const doc = parseJson(readFileSync(file, "utf8"))
+  return jsonModelText(readFileSync(file, "utf8"))
+}
+
+function jsonModelText(text: string): string {
+  const doc = parseJson(text)
   if (doc === undefined) return ""
   const v: Json | undefined = isObject(doc) ? doc["model"] : undefined
   if (v === undefined || v === null || v === false) return "default (unset)"
@@ -93,7 +99,11 @@ function jsonModelField(file: string): string {
 
 /** `awk -F'"' '/^model[[:space:]]*=/{print $2; exit}'`. */
 function tomlModelField(file: string): string {
-  for (const line of readFileSync(file, "utf8").split("\n")) {
+  return tomlModelText(readFileSync(file, "utf8"))
+}
+
+function tomlModelText(text: string): string {
+  for (const line of text.split("\n")) {
     if (/^model[ \t]*=/.test(line)) return line.split('"')[1] ?? ""
   }
   return ""
@@ -125,10 +135,9 @@ export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
   }
   switch (tool) {
     case "rtk":
-      return ensure(ctx, "rtk", rtkInstall(ctx))
+      return ensureRtk(ctx, "cannot download RTK installer; toolchain ensure rtk aborted", 1)
     case "bun":
-      // skills::_bun_bootstrap >/dev/null — the found-bun stdout is discarded.
-      return bunBootstrap(ctx, ctx.services) !== "" ? 0 : 1
+      return bunBootstrap(ctx, ctx.services).kind === "ready" ? 0 : 1
     case "effect-solutions":
       return ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
     case "agent-browser":

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

@@ -1,6 +1,6 @@
 /**
  * EngineNative flag layer: usage / target selection / compact-window parsing /
- * optional-plugin parsing / model validation / preflight. ExitError mirrors an
+ * optional-plugin parsing / model validation. ExitError mirrors an
  * early parser exit and is caught once in runEngineNative.
  */
 
@@ -184,22 +184,6 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   }
 }
 
-export function preflight(ctx: Ctx): void {
-  const { err } = ctx.services.logger
-  if (ctx.syncClaude || ctx.syncCodex) {
-    if (ctx.services.deps.probe("jq").state === "missing") {
-      err(`jq is required (deployed statusline/hooks call it). Install: ${ctx.services.deps.spec("jq").installHint()}`)
-      throw new ExitError(1)
-    }
-  }
-  if (ctx.syncClaude) {
-    if (ctx.services.deps.probe("curl").state === "missing") {
-      err(`curl is required. Install: ${ctx.services.deps.spec("curl").installHint()}`)
-      throw new ExitError(1)
-    }
-  }
-}
-
 export function validateModelFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger
   if (ctx.claudeModel !== "") {

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

@@ -0,0 +1,11 @@
+export function powerShellLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`
+}
+
+export function encodePowerShellCommand(script: string): string {
+  return Buffer.from(script, "utf16le").toString("base64")
+}
+
+export function decodePowerShellCommand(encoded: string): string {
+  return Buffer.from(encoded, "base64").toString("utf16le")
+}