docks-kit 0.1.5 → 0.3.0

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

@@ -0,0 +1,325 @@
+/**
+ * DependencyManager — one home for external-tool identity, presence probing,
+ * and platform-correct install hints (Output Policy in DESIGN.md).
+ *
+ * Ownership split: SoT/toolchain.json + toolchain.ts keep version floors,
+ * pin policy, and managed install/upgrade orchestration; this registry owns
+ * WHICH external tools exist, whether they are required, and the one-line
+ * command that installs a missing one.
+ */
+import { homedir } from "node:os"
+import { existsSync, readdirSync } from "node:fs"
+
+import { capture, commandExists, p, which } from "./exec"
+import { isObject, parseJson } from "./jq"
+import { rawPlatform } from "./os"
+
+export type ToolId =
+  | "git"
+  | "jq"
+  | "curl"
+  | "node"
+  | "npm"
+  | "npx"
+  | "claude"
+  | "codex"
+  | "rtk"
+  | "bun"
+  | "bwrap"
+  | "agent-browser"
+  | "effect-solutions"
+  | "chrome-for-testing"
+  | "ffplay"
+  | "intelephense"
+  | "typescript-language-server"
+  | "tsc"
+  | "apt-get"
+  | "dnf"
+  | "pacman"
+  | "zypper"
+
+/** required = the engine aborts when missing; optional = warn + degrade. */
+export type Requirement = "required" | "optional"
+
+export type ProbeResult =
+  | { readonly state: "present"; readonly path?: string }
+  | { readonly state: "missing" }
+
+export interface DependencyLocation {
+  readonly path: string
+  readonly binDir: string
+}
+
+export interface ProbeExecutor {
+  readonly commandExists: (name: string) => boolean
+  readonly capture: (cmd: string, args: ReadonlyArray<string>) => string
+  readonly which: (name: string) => string
+}
+
+export interface DependencySpec {
+  readonly id: ToolId
+  readonly requirement: Requirement
+  readonly versionArgs: ReadonlyArray<string>
+  /** Platform-correct one-line install command (param injectable for tests). */
+  readonly installHint: (platform?: NodeJS.Platform) => string
+  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
+  readonly version?: (exec: ProbeExecutor) => string
+  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => DependencyLocation
+  readonly latest?: (exec: ProbeExecutor) => string
+}
+
+interface SpecOptions {
+  readonly versionArgs?: ReadonlyArray<string>
+  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
+  readonly version?: (exec: ProbeExecutor) => string
+  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => DependencyLocation
+  readonly latest?: (exec: ProbeExecutor) => string
+}
+
+const spec = (
+  id: ToolId,
+  requirement: Requirement,
+  installHint: (platform?: NodeJS.Platform) => string,
+  options: SpecOptions = {}
+): DependencySpec => ({
+  id,
+  requirement,
+  versionArgs: options.versionArgs ?? ["--version"],
+  installHint,
+  resolve: options.resolve,
+  version: options.version,
+  locate: options.locate,
+  latest: options.latest
+})
+
+const pathProbe = (id: string): ((exec: ProbeExecutor) => ProbeResult) =>
+  (exec) =>
+    exec.commandExists(id)
+      ? { state: "present", path: exec.which(id) }
+      : { state: "missing" }
+
+const versionProbe = (
+  id: string,
+  versionArgs: ReadonlyArray<string> = ["--version"],
+  parse: (out: string) => string = (out) => out
+): ((exec: ProbeExecutor) => string) =>
+  (exec) => parse(exec.capture(id, versionArgs))
+
+const home = (): string => {
+  const envHome = process.env["HOME"]
+  return envHome !== undefined && envHome !== "" ? envHome : homedir()
+}
+
+const findBun = (exec: ProbeExecutor): { command: string; path: string } | undefined => {
+  const onPath = exec.which("bun")
+  if (onPath !== "") return { command: "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 }
+  }
+  return undefined
+}
+
+const resolveBun = (exec: ProbeExecutor): ProbeResult => {
+  const bun = findBun(exec)
+  return bun === undefined
+    ? { state: "missing" }
+    : { state: "present", path: bun.path }
+}
+
+const resolveEffectSolutions = (exec: ProbeExecutor): ProbeResult => {
+  return exec.commandExists("effect-solutions")
+    ? { state: "present", path: exec.which("effect-solutions") }
+    : { state: "missing" }
+}
+
+const versionBunCommand = (exec: ProbeExecutor): string =>
+  exec.commandExists("bun") ? "bun" : p(home(), ".bun", "bin", "bun")
+
+const versionEffectSolutions = (exec: ProbeExecutor): string => {
+  const bun = versionBunCommand(exec)
+  if (bun !== "bun" && exec.which(bun) === "") return ""
+  const match = /effect-solutions@([0-9][0-9.]*)/.exec(exec.capture(bun, ["pm", "-g", "ls"]))
+  return match?.[1] ?? ""
+}
+
+const locateEffectSolutions = (exec: ProbeExecutor, platform: NodeJS.Platform): DependencyLocation => {
+  const bun = findBun(exec)
+  if (bun === undefined) return { path: "", binDir: "" }
+  const globalBin = exec.capture(bun.command, ["pm", "-g", "bin"])
+  const names =
+    platform === "win32"
+      ? ["effect-solutions.exe", "effect-solutions.cmd", "effect-solutions.bunx"]
+      : ["effect-solutions"]
+  const path = names.map((name) => p(globalBin, name)).find((candidate) => globalBin !== "" && exec.which(candidate) !== "")
+  return { path: path ?? "", binDir: globalBin }
+}
+
+const resolveChrome = (exec: ProbeExecutor, platform: NodeJS.Platform): ProbeResult => {
+  const root = p(home(), ".agent-browser", "browsers")
+  const relative =
+    platform === "win32"
+      ? "chrome.exe"
+      : platform === "darwin"
+        ? "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
+        : "chrome"
+  if (existsSync(root)) {
+    for (const directory of readdirSync(root).filter((name) => name.startsWith("chrome-")).sort().reverse()) {
+      const path = exec.which(p(root, directory, relative))
+      if (path !== "") return { state: "present", path }
+    }
+  }
+  for (const command of ["chrome-for-testing", "google-chrome-for-testing", "google-chrome", "chromium", "chromium-browser", "brave-browser", "brave"]) {
+    const path = exec.which(command)
+    if (path !== "") return { state: "present", path }
+  }
+  return { state: "missing" }
+}
+
+const latestRtk = (exec: ProbeExecutor): string => {
+  const doc = parseJson(
+    exec.capture("curl", ["-fsSL", "--max-time", "5", "https://api.github.com/repos/rtk-ai/rtk/releases/latest"])
+  )
+  const tag = doc !== undefined && isObject(doc) && typeof doc["tag_name"] === "string" ? doc["tag_name"] : ""
+  return tag.replace(/^v/, "")
+}
+
+const latestNpm = (id: "agent-browser" | "effect-solutions") => (exec: ProbeExecutor): string =>
+  exec.commandExists("npm") ? exec.capture("npm", ["view", id, "version"]) : ""
+
+export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which }
+
+export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
+  git: spec(
+    "git",
+    "optional",
+    (pf = rawPlatform()) =>
+      pf === "win32"
+        ? "winget install Git.Git (then open a new terminal)"
+        : pf === "darwin"
+          ? "brew install git"
+          : "sudo apt install -y git (or your distro's package manager)",
+    { version: versionProbe("git") }
+  ),
+  jq: spec("jq", "required", (pf = rawPlatform()) =>
+    pf === "win32"
+      ? "winget install jqlang.jq (then open a new terminal)"
+      : pf === "darwin"
+        ? "brew install jq"
+        : "sudo apt install -y jq",
+    { version: versionProbe("jq") }
+  ),
+  curl: spec("curl", "required", (pf = rawPlatform()) =>
+    pf === "win32" ? "winget install cURL.cURL" : pf === "darwin" ? "brew install curl" : "sudo apt install -y curl",
+    { version: versionProbe("curl") }
+  ),
+  node: spec("node", "optional", () => "install Node.js via https://nodejs.org (or your package manager)", {
+    version: versionProbe("node")
+  }),
+  npm: spec("npm", "optional", () => "ships with Node.js — install via https://nodejs.org (or your package manager)"),
+  npx: spec("npx", "optional", () => "ships with Node.js — install via https://nodejs.org (or your package manager)"),
+  claude: spec(
+    "claude",
+    "optional",
+    (pf = rawPlatform()) =>
+      pf === "win32"
+        ? "winget install Anthropic.ClaudeCode"
+        : "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh",
+    { version: versionProbe("claude") }
+  ),
+  codex: spec(
+    "codex",
+    "optional",
+    (pf = rawPlatform()) =>
+      pf === "win32"
+        ? `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"`
+        : 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"',
+    { version: versionProbe("codex") }
+  ),
+  rtk: spec("rtk", "optional", () => "see https://github.com/rtk-ai/rtk (kit auto-install is Unix-only)", {
+    version: versionProbe("rtk"),
+    latest: latestRtk
+  }),
+  bun: spec(
+    "bun",
+    "optional",
+    (pf = rawPlatform()) =>
+      pf === "win32" ? `powershell -c "irm bun.sh/install.ps1 | iex"` : "curl -fsSL https://bun.sh/install | bash",
+    {
+      resolve: resolveBun,
+      version: (exec) => exec.capture(versionBunCommand(exec), ["--version"]),
+      locate: (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
+    }
+  ),
+  bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)"),
+  "agent-browser": spec("agent-browser", "optional", () => "npm install -g agent-browser", {
+    version: versionProbe("agent-browser"),
+    latest: latestNpm("agent-browser")
+  }),
+  "effect-solutions": spec("effect-solutions", "optional", () => "bun add -g effect-solutions", {
+    resolve: resolveEffectSolutions,
+    version: versionEffectSolutions,
+    locate: locateEffectSolutions,
+    latest: latestNpm("effect-solutions")
+  }),
+  "chrome-for-testing": spec(
+    "chrome-for-testing",
+    "optional",
+    (pf = rawPlatform()) => (pf === "linux" ? "agent-browser install --with-deps" : "agent-browser install"),
+    { resolve: resolveChrome }
+  ),
+  ffplay: spec(
+    "ffplay",
+    "optional",
+    (pf = rawPlatform()) =>
+      pf === "win32" ? "winget install Gyan.FFmpeg" : pf === "darwin" ? "brew install ffmpeg" : "sudo apt install -y ffmpeg",
+    { versionArgs: ["-version"], resolve: pathProbe("ffplay") }
+  ),
+  intelephense: spec("intelephense", "optional", () => "npm install -g intelephense", {
+    resolve: pathProbe("intelephense")
+  }),
+  "typescript-language-server": spec(
+    "typescript-language-server",
+    "optional",
+    () => "npm install -g typescript-language-server typescript",
+    { resolve: pathProbe("typescript-language-server") }
+  ),
+  tsc: spec("tsc", "optional", () => "npm install -g typescript", {
+    resolve: pathProbe("tsc"),
+    version: versionProbe("tsc")
+  }),
+  "apt-get": spec("apt-get", "optional", () => "install apt via your Linux distribution"),
+  dnf: spec("dnf", "optional", () => "install dnf via your Linux distribution"),
+  pacman: spec("pacman", "optional", () => "install pacman via your Linux distribution"),
+  zypper: spec("zypper", "optional", () => "install zypper via your Linux distribution")
+}
+
+export function resolveDependency(
+  specification: DependencySpec,
+  exec: ProbeExecutor,
+  platform: NodeJS.Platform = rawPlatform()
+): ProbeResult {
+  return (specification.resolve ?? pathProbe(specification.id))(exec, platform)
+}
+
+export function resolveVersion(specification: DependencySpec, exec: ProbeExecutor): string {
+  if (resolveDependency(specification, exec).state !== "present") return ""
+  return (specification.version ?? versionProbe(specification.id, specification.versionArgs))(exec)
+}
+
+export function resolveLocation(
+  specification: DependencySpec,
+  exec: ProbeExecutor,
+  platform: NodeJS.Platform = rawPlatform()
+): DependencyLocation {
+  if (specification.locate !== undefined) return specification.locate(exec, platform)
+  const result = resolveDependency(specification, exec, platform)
+  return { path: result.state === "present" ? (result.path ?? exec.which(specification.id)) : "", binDir: "" }
+}
+
+export function resolvePath(specification: DependencySpec, exec: ProbeExecutor, platform?: NodeJS.Platform): string {
+  return resolveLocation(specification, exec, platform).path
+}

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

@@ -4,8 +4,8 @@
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
 import { spawnSync } from "node:child_process"
-import { accessSync, constants, existsSync, statSync } from "node:fs"
-import { delimiter, join } from "node:path"
+import { accessSync, chmodSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { delimiter, isAbsolute, join } from "node:path"
 
 /**
  * Engine paths are built with "/" because they appear verbatim in output
@@ -24,6 +24,9 @@ export function capture(cmd: string, args: ReadonlyArray<string>): string {
 
 /** `command -v` — resolve a name on PATH (PATHEXT-aware on Windows). */
 export function which(name: string): string {
+  if (isAbsolute(name) || name.includes("/") || name.includes("\\")) {
+    return isExecutable(name) ? name : ""
+  }
   const exts = process.platform === "win32" ? (process.env["PATHEXT"] ?? ".EXE;.CMD;.BAT;.COM").split(";").concat("") : [""]
   for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
     if (dir === "") continue
@@ -52,3 +55,33 @@ export function isExecutable(p: string): boolean {
 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)
+  return true
+}
+
+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
+}
+
+export function writeFileIfChanged(path: string, content: string): boolean {
+  return writeTextIfChanged(path, content)
+}

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

@@ -6,15 +6,14 @@
  * 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 { claudeNextSteps, claudeSummary, claudeSync } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { echo } from "./output"
 import { ExitError, parseArgs, preflight, validateModelFlags } from "./parseArgs"
 
 export interface Ctx {
@@ -22,6 +21,7 @@ export interface Ctx {
   readonly home: string
   readonly agentsDir: string
   dryRun: boolean
+  verbose: boolean
   skipRtk: boolean
   reconcile: boolean
   prune: boolean
@@ -31,14 +31,23 @@ export interface Ctx {
   claudePlugins: Array<string>
   claudeModel: string
   codexModel: string
+  /** Injected capability seam (logger/deps/platform) — see services.ts. */
+  readonly services: EngineServices
   targetFilterSet: boolean
   syncClaude: boolean
   syncCodex: boolean
   syncAgents: boolean
+  /** Per-run next-step triggers (Output Policy): advice prints only when its trigger changed or --verbose. */
+  readonly nextStepTriggers: {
+    claudePlugins: boolean
+    claudeRestart: boolean
+    codexRestart: boolean
+    skillsRestart: boolean
+  }
 }
 
 /** Globals default from env using the historical ${VAR:-default} contract. */
-function makeCtx(): Ctx {
+function makeCtx(services: EngineServices): Ctx {
   const env = process.env
   const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir()
   return {
@@ -46,6 +55,7 @@ function makeCtx(): Ctx {
     home,
     agentsDir: env["AGENTS_DIR"] !== undefined && env["AGENTS_DIR"] !== "" ? env["AGENTS_DIR"] : p(home, ".agents"),
     dryRun: env["DRY_RUN"] === "1",
+    verbose: env["DOCKS_KIT_VERBOSE"] === "1",
     skipRtk: env["SKIP_RTK"] === "1",
     reconcile: env["RECONCILE"] === "1",
     prune: env["PRUNE"] === "1",
@@ -55,25 +65,28 @@ function makeCtx(): Ctx {
     claudePlugins: (env["CLAUDE_PLUGINS"] ?? "").split(" ").filter((s) => s !== ""),
     claudeModel: env["CLAUDE_MODEL"] ?? "",
     codexModel: env["CODEX_MODEL"] ?? "",
+    services,
     targetFilterSet: false,
     syncClaude: false,
     syncCodex: false,
-    syncAgents: false
+    syncAgents: false,
+    nextStepTriggers: { claudePlugins: false, claudeRestart: false, codexRestart: false, skillsRestart: false }
   }
 }
 
 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"))
+  const claudeRan = ctx.syncClaude
   if (claudeRan) claudeSync(ctx)
 
-  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 ---")
@@ -82,15 +95,37 @@ function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   if (codexRan) codexSummary(ctx)
   if (skillsState !== undefined) skillsSummary(ctx, skillsState)
 
-  echo("")
-  if (claudeRan) claudeNextSteps()
-  if (codexRan) codexNextSteps()
-  if (skillsState !== undefined) skillsNextSteps()
+  const advice = [
+    ...(claudeRan ? claudeNextSteps(ctx) : []),
+    ...(codexRan ? codexNextSteps(ctx) : []),
+    ...(skillsState !== undefined ? skillsNextSteps(ctx) : [])
+  ]
+  if (advice.length > 0) {
+    echo("")
+    for (const line of advice) echo(line)
+  }
   return 0
 }
 
-export function runEngineNative(argv: ReadonlyArray<string>): number {
-  const ctx = makeCtx()
+export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineServices): number {
+  let ctx!: Ctx
+  const baseServices = services ?? makeEngineServices()
+  const baseLogger = baseServices.logger
+  const logger: Logger = {
+    change: (msg) => baseLogger.change(msg),
+    verbose: (msg) => {
+      if (ctx.verbose) baseLogger.verbose(msg)
+    },
+    warn: (msg) => baseLogger.warn(msg),
+    err: (msg) => baseLogger.err(msg),
+    echo: (line) => baseLogger.echo(line)
+  }
+  const runServices: EngineServices = {
+    logger,
+    deps: baseServices.deps,
+    platform: baseServices.platform
+  }
+  ctx = makeCtx(runServices)
   try {
     switch (argv[0]) {
       case "model":

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

@@ -0,0 +1,35 @@
+/**
+ * Leveled stderr logger + stdout data writer — the Output Policy contract in
+ * DESIGN.md. Filtering is explicit and synchronous: engine code is imperative,
+ * so fiber-scoped Effect log levels cannot see these writes. The prefixes and
+ * ANSI codes are stable golden surface; the level controls visibility only.
+ */
+
+export interface Logger {
+  /** `[ok]` green — an operation actually mutated something. Always visible. */
+  readonly change: (msg: string) => void
+  /** `[ok]` green — status-quo confirmation; visible only with verbosity on. */
+  readonly verbose: (msg: string) => void
+  readonly warn: (msg: string) => void
+  readonly err: (msg: string) => void
+  /** stdout data line (dry-run report, summary, usage) — never filtered. */
+  readonly echo: (line: string) => void
+}
+
+export interface LoggerSinks {
+  readonly stderr?: (chunk: string) => void
+  readonly stdout?: (chunk: string) => void
+}
+
+export function makeLogger(sinks: LoggerSinks): Logger {
+  const errWrite = sinks.stderr ?? ((chunk: string) => void process.stderr.write(chunk))
+  const outWrite = sinks.stdout ?? ((chunk: string) => void process.stdout.write(chunk))
+  const ok = (msg: string): void => errWrite(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`)
+  return {
+    change: ok,
+    verbose: ok,
+    warn: (msg) => errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`),
+    err: (msg) => errWrite(`\x1b[1;31m[err]\x1b[0m ${msg}\n`),
+    echo: (line) => outWrite(`${line}\n`)
+  }
+}

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

@@ -2,70 +2,69 @@
  * 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 { warn } from "./output"
+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(repoDir: string, tool: string): void {
-  const entry = toolEntry(repoDir, tool)
+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 (${p(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(repoDir, tool)) {
+  for (const m of modelEntries(tool)) {
     const note = typeof m["note"] === "string" ? `  — ${m["note"]}` : ""
     lines.push(`  ${String(m["id"] ?? "")}${note}`)
   }
   if (tool === "claude") lines.push("  (full claude-* model IDs outside the catalog are accepted with a warning)")
   if (tool === "codex") lines.push("  (well-formed IDs outside the catalog are accepted with a warning)")
-  process.stderr.write(`${lines.join("\n")}\n`)
+  for (const line of lines) echo(line)
 }
 
-export function validateClaudeModel(repoDir: string, m: string): boolean {
+export function validateClaudeModel(ctx: Ctx, m: string): boolean {
   if (m === "") return false
-  if (modelsFromManifest(repoDir, "claude").includes(m)) return true
+  if (modelsFromManifest("claude").includes(m)) return true
   if (m.startsWith("claude-")) {
-    warn(`Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`)
+    ctx.services.logger.warn(`Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`)
     return true
   }
   return false
 }
 
-export function validateCodexModel(repoDir: string, m: string): boolean {
+export function validateCodexModel(ctx: Ctx, m: string): boolean {
   if (!/^[A-Za-z0-9._-]+$/.test(m)) return false
-  if (!modelsFromManifest(repoDir, "codex").includes(m)) {
-    warn(
+  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)`
     )
   }