docks-kit 0.16.16 → 0.17.0

package/AGENTS.md

@@ -31,6 +31,8 @@ launcher can fall back to Bun source.
 | `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json`. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
 | `cli/src/engine-native/ompSync.ts` | omp file deployment, marketplace registration, and plugin synchronization |
+| `cli/src/commands/omp.ts` | `docks-kit omp` session launcher: renders the free-model run overlay and forwards args to omp |
+| `cli/src/engine-native/ompOverlay.ts` | Free-model overlay render plus catalog parse and thinking-ceiling helpers |
 | `cli/` | Effect 4 RC CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
@@ -72,6 +74,8 @@ omp SoT notes:
 - Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope.
 - Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
 - The omp CLI is upstream-owned and self-updating through `omp update`. Sync never installs or upgrades the CLI.
+- `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session on a single free model. It renders a run overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600) and passes it through omp's repeatable `--config` flag. `ompOverlay.ts overlayFileName` gives each model its own file, because omp can re-read the overlay during a live session and a second launcher on another model must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again. Remaining arguments forward verbatim to omp.
+- The session model persists per machine in `~/.docks-kit/state.json` under `ompSession`, next to `harnesses`. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both the session level and the advisor level from the ladder of the chosen model, never from a fixed list: free ladders are not uniform, three free models publish no `medium`, and two publish no ladder, which the overlay renders as bare selectors. The picker lists only zero-cost catalog models.
 
 For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
 
@@ -83,7 +87,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 - **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.115` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.0` (inside the `@effect/vitest` peer range `>=5.0.0 <6.0.0`; 5.0.0 is past the 5.x patch point for GHSA-82fw-gwwq-j7x9, fixed in 5.0.0-rc.2). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
 - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
 - **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
-- **Per-machine harness selection.** `~/.docks-kit/state.json` drives a flag-less sync. A missing file selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection file. `docks-kit harnesses` is the only command that writes the selection.
+- **Per-machine harness selection.** `~/.docks-kit/state.json` drives a flag-less sync. A missing file selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection file. `docks-kit harnesses` is the only command that writes the `harnesses` selection. The same state file also carries the independent `ompSession` key, which only `docks-kit omp` writes; every writer merges over the stored record, so neither key can drop the other.
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claudeSync.ts REMOVED_MANIFEST, baseline removal inventory`), a curated list of unambiguous kit-owned artifacts that `claudeSync.ts syncRemovals, baseline artifact prune` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.
 - **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing and validation. `toolchain.ts` owns verified-version floor reporting over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own their tool-specific sync logic. `ompSync.ts` owns omp file and plugin sync. `ompYaml.ts` owns the omp YAML merge. `harnesses.ts` owns per-machine harness selection. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.

package/cli/docs/flags.md

@@ -52,6 +52,27 @@ Bare model, effort, or advisor modifiers print the relevant valid-value catalog
 and exit 2. A modifier for a target not selected by the positional arguments is
 ignored with a warning; Claude modifiers never touch Codex config and vice versa.
 
+## `omp` session flags
+
+| Flag | Effect |
+|------|--------|
+| `--model <selector>` | Session model for this run and later runs; rejected unless the live catalog reports zero input and output cost; recorded in `~/.docks-kit/state.json` under `ompSession` |
+| `--pick` | Interactive picker over free catalog models; records the choice the same way |
+
+Remaining arguments forward verbatim to omp after the launcher flags.
+`docks-kit omp -p "..."` runs one prompt. `docks-kit omp --continue` resumes
+the previous session. A bare `docks-kit omp` opens an interactive session.
+The launcher changes no deployed file and never invokes `sync`.
+The boundary opens at the first token that is neither a declared launcher
+flag nor a declared global flag. Declared flags stay with docks-kit and
+never reach omp:
+
+- `--model`, `--pick`
+- `--help`, `--version`, `--log-level`, `--wizard`, `--completions`
+
+The same names on omp stay reachable behind an explicit delimiter. Use
+`docks-kit omp -- --help` to ask omp for help.
+
 ## Renamed legacy flags (pre-CLI sync.sh)
 
 Old flags exit with a rename hint — there is no compat behavior.

package/cli/docs/install.md

@@ -153,6 +153,7 @@ sync/config reads.
 
 - Bun for source/global installs; release binaries embed the runtime
 - Node/npm for npm-global LSP servers
+- rustup is optional and needed only for the Rust language server
 - jq is optional doctor/test tooling; sync has no jq runtime dependency
 - curl is required only when a source launcher must download Bun. The POSIX
   launchers run `install.sh`; Windows runs `install.ps1` through PowerShell.

package/cli/docs/omp-models.md

@@ -211,6 +211,65 @@ omp's 272k context window is the `/extended-context off` window for Astra.
 `/extended-context on` uses the 922k input window, 1.05M total, which matches
 AA's 1M.
 
+## Free session launcher (`docks-kit omp`)
+
+`docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive
+omp session on a single free model. All 12 model roles resolve to that model.
+All 9 retry fallback chains are empty, so a retry cannot reach a paid model.
+The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
+a model that publishes no thinking ladder, where both keys are omitted and the
+deployed values apply.
+
+The launcher renders a run overlay to
+`~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
+through omp's repeatable `--config` flag. Each model gets its own file,
+because omp can re-read the overlay during a live session, and a second
+launcher on another model must not rewrite that file. The name sanitizes the
+selector for the file system and appends a digest of the exact selector, so
+two selectors that differ only in separator characters stay apart. The
+launcher never reads or writes `~/.omp/agent/config.yml` or `models.yml`. It
+never touches the SoT. The next plain `omp` run uses the paid configuration
+again.
+
+Every argument after the launcher flags forwards verbatim to omp. `docks-kit
+omp -p "..."` runs one prompt. `docks-kit omp --continue` resumes the
+previous session. A bare `docks-kit omp` opens an interactive session.
+
+The default model is `opencode-zen/muse-spark-1.3-contributor-free` ("Muse
+Spark 1.3 Free", 1,048,576-token context) at `xhigh`. `xhigh` is the ceiling
+of that model ladder: `minimal, low, medium, high, xhigh`. The paid
+`muse-spark-1.3` sibling also offers `max`. The free variant does not.
+
+Both levels come from the ladder of the chosen model, never from a fixed
+list. The session level is the ceiling of that ladder. The advisor level is
+the highest level at or below `medium`, because the advisor performs quick
+review passes. When every level of a ladder is above `medium`, the advisor
+takes the lowest level, so it never becomes the most expensive role.
+
+Free ladders are not uniform. On 2026-09-11 the 26 free models published six
+distinct ladders: 21 include `medium`, 3 stop at `low, high, max` or
+`high, max`, and 2 publish no ladder at all. A model without a ladder gets
+bare selectors with no `:level` suffix, because an invented level makes omp
+fail when the session starts.
+
+The choice persists per machine in `~/.docks-kit/state.json` under
+`ompSession`, next to `harnesses`. It survives across sessions. It is never
+committed. `--model <selector>` records one selector. `--pick` opens an
+interactive picker.
+
+The picker lists only models the live `omp models --json` catalog reports at
+zero input and output cost (26 entries on 2026-09-11). This path cannot start
+a paid session. The catalog can advertise a free model that the account
+cannot call; omp reports that provider error unchanged.
+
+An omp login is required. The kit owns no login flow. It surfaces omp's own
+authentication error unchanged.
+
+When the catalog renames the free variant, change only the default selector
+constant. A ladder change needs no code change, because both levels come from
+the catalog row of the chosen model. Refresh the recorded default and the
+ladder counts in these docs in the same commit.
+
 ## Maintenance
 
 - Refresh the snapshot from the AA release page of each family

package/cli/docs/overview.md

@@ -16,7 +16,7 @@ AI-assisted dev environment on every machine.
 | `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
 | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
-| `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain |
+| `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain and the `docks-kit omp` session overlay |
 | `cli/` | This CLI (Effect 4 RC on Bun) plus bundled docs |
 | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers: version-matching compiled binary → Bun-from-source, with Bun auto-install |
 

package/cli/docs/sync-layers.md

@@ -30,7 +30,7 @@ Order matters — runtime readiness and settings form one transaction:
 7. **Plugins** — seven idempotent passes via the `claude plugin` CLI
    (marketplaces → install → update → [--prune: uninstall/remove] → re-assert
    SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
-8. LSP server binaries (npm globals).
+8. LSP server binaries (npm globals plus the rust-analyzer rustup component).
 
 The statusline reads Claude's native `rate_limits`. There is no OAuth request,
 usage cache, jq/curl runtime dependency, or Stop fetch hook.

package/cli/docs/toolchain.md

@@ -39,12 +39,25 @@ floor: it skips the `typescript-language-server` install on such a host, warns
 with the host Node version, and installs the other language servers. Nothing
 else consults the floor, so a host below it still runs every kit operation.
 
+## rust-analyzer: no floor, no pin
+
+`rust-analyzer` is a `check` row with no floor and no `verified` pin. The kit
+installs the component with `rustup component add rust-analyzer` for the
+`rust-analyzer-lsp` plugin, so the version follows the host Rust toolchain. A
+pin would claim control the kit does not have, the stance `bubblewrap` already
+takes for a tool the kit does not publish. `docks-kit toolchain check` reports
+the installed version and judges nothing.
+
 ## Language-server upgrades
 
 `claudeSync syncLspServers` installs `intelephense`, `typescript-language-server`,
-and `typescript` only when the binary is missing. It never upgrades a server
-that is already present. A `verified` bump therefore reaches a fresh host
-immediately and leaves an existing install alone.
+`typescript`, and `rust-analyzer` only when the binary is missing. It never
+upgrades a server that is already present. A `verified` bump therefore reaches
+a fresh host immediately and leaves an existing install alone.
+
+The rustup channel follows the same rule. Sync adds the component only when the
+`rust-analyzer` binary is missing, and `rustup update` is the user's remedy for
+an old component.
 
 A lagging server shows as `below-floor` in `docks-kit toolchain check`. To move
 it, upgrade Node to 22.22.2 or newer, then install the pinned version by hand:

package/cli/src/argv.ts

@@ -8,6 +8,7 @@ import { statusCommand } from "./commands/status"
 import { syncCommand } from "./commands/sync"
 import { toolchainCommand } from "./commands/toolchain"
 import { updateCommand } from "./commands/update"
+import { ompCommand } from "./commands/omp"
 import {
   advisorCatalog,
   advisorFlagGrammar,
@@ -161,7 +162,8 @@ const COMMANDS: ReadonlyArray<CommandValue> = [
   statusCommand,
   pluginsCommand,
   skillsCommand,
-  docsCommand
+  docsCommand,
+  ompCommand
 ]
 
 // A Map, not a plain object: an object literal answers `toString` and friends from
@@ -373,11 +375,68 @@ const missingModifierValue = (flag: string): string | undefined => {
   }
 }
 
+// Without the injected `--`, Effect 4 rejects a forwarded flag such as `-p` or
+// `--mode` as unrecognized. The omp launcher therefore owns a passthrough
+// boundary: the first token after the `omp` word that is neither a flag
+// declared on the omp or global surface nor a value consumed by such a flag
+// starts the verbatim tail forwarded to omp. An undeclared long flag joins the
+// tail too, because most omp flags are long (`--mode`, `--continue`,
+// `--models`), and omp itself reports an unrecognized one accurately. Use
+// `docks-kit omp -- --model x` to reach omp's own same-named flag.
+const spliceOmpBoundary = (args: ReadonlyArray<string>): ReadonlyArray<string> => {
+  const surface = COMMAND_SURFACES.get("omp")
+  let ompIndex = -1
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index] as string
+    if (token === "--") return args
+    const name = flagNameOf(token)
+    if (token === name && takesValueInAnySurface(name)) {
+      const next = args[index + 1]
+      if (next === "--") return args
+      if (next !== undefined && !(next.startsWith("-") && declaredInAnySurface(flagNameOf(next)))) {
+        index++
+        continue
+      }
+    }
+    if (!token.startsWith("-")) {
+      ompIndex = index
+      break
+    }
+  }
+  if (ompIndex === -1 || args[ompIndex] !== "omp") return args
+  for (let index = ompIndex + 1; index < args.length; index++) {
+    const token = args[index] as string
+    // An explicit delimiter already marks the tail; a second one would be
+    // forwarded to omp as a literal argument.
+    if (token === "--") return args
+    if (!token.startsWith("-")) {
+      return [...args.slice(0, index), "--", ...args.slice(index)]
+    }
+    const name = flagNameOf(token)
+    const canonical = declaredFlagName(name, surface)
+    if (canonical === undefined) return [...args.slice(0, index), "--", ...args.slice(index)]
+    const takesValue =
+      surface?.valueFlags.includes(canonical) === true ||
+      GLOBAL_SURFACE.valueFlags.includes(canonical)
+    if (takesValue && !token.includes("=")) {
+      const next = args[index + 1]
+      if (
+        next !== undefined &&
+        !(next.startsWith("-") && declaredFlagName(flagNameOf(next), surface) !== undefined)
+      ) {
+        index++
+      }
+    }
+  }
+  return args
+}
+
 /** Validate the argument list, then hand back the arguments Effect 4 should parse. */
 export const prepareArgv = (args: ReadonlyArray<string>): ArgvOutcome => {
-  const subcommand = subcommandName(args)
+  const boundaryArgs = subcommandName(args) === "omp" ? spliceOmpBoundary(args) : args
+  const subcommand = subcommandName(boundaryArgs)
   const commandSurface = subcommand === undefined ? undefined : COMMAND_SURFACES.get(subcommand)
-  const { flags, normalizations } = scanArgv(args, commandSurface)
+  const { flags, normalizations } = scanArgv(boundaryArgs, commandSurface)
   const unknownCommandWouldMisdiagnoseFlag =
     subcommand !== undefined &&
     commandSurface === undefined &&
@@ -430,5 +489,5 @@ export const prepareArgv = (args: ReadonlyArray<string>): ArgvOutcome => {
     }
   }
 
-  return { kind: "accept", args: normalizeArgv(args, normalizations) }
+  return { kind: "accept", args: normalizeArgv(boundaryArgs, normalizations) }
 }

package/cli/src/commands/omp.ts

@@ -0,0 +1,189 @@
+import { Argument, Command, Flag, Prompt } from "effect/unstable/cli"
+import { Console, Effect, Option } from "effect"
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs"
+import { bail } from "../engine"
+import { capture, p, spawnHost, which } from "../engine-native/exec"
+import {
+  DEFAULT_OMP_SESSION_MODEL,
+  engineHome,
+  readOmpSessionModel,
+  writeOmpSessionModel,
+  type OmpSessionModel
+} from "../engine-native/harnesses"
+import {
+  advisorLevelFor,
+  buildOmpArgs,
+  ladderCeiling,
+  overlayFileName,
+  parseFreeModels,
+  renderFreeOverlay,
+  type CatalogModel
+} from "../engine-native/ompOverlay"
+
+const model = Flag.String("model").pipe(
+  Flag.withDescription("Free model selector to use and remember for omp sessions"),
+  Flag.optional
+)
+const pick = Flag.Boolean("pick").pipe(
+  Flag.withDescription("Choose the free model interactively"),
+  Flag.withDefault(false)
+)
+const args: Argument.Argument<ReadonlyArray<string>> = Argument.String("args").pipe(
+  Argument.withDescription("Arguments forwarded verbatim to omp"),
+  Argument.variadic()
+)
+
+export type FreeSelectorResolution =
+  | { readonly ok: true; readonly model: CatalogModel }
+  | { readonly ok: false; readonly message: string }
+
+// Pure selector matching so the picker rule stays testable without spawning omp.
+// An exact selector always wins; otherwise one case-insensitive substring hit
+// across the free selectors resolves, because a longer exact selector is easy
+// to mistype and the catalog is small enough to disambiguate safely.
+export function resolveFreeSelector(
+  input: string,
+  free: ReadonlyArray<CatalogModel>
+): FreeSelectorResolution {
+  const trimmed = input.trim()
+  if (trimmed === "") {
+    return { ok: false, message: "Model selector must not be empty or blank" }
+  }
+  const exact = free.find((candidate) => candidate.selector === trimmed)
+  if (exact !== undefined) return { ok: true, model: exact }
+  const lowered = trimmed.toLowerCase()
+  const matches = free.filter((candidate) => candidate.selector.toLowerCase().includes(lowered))
+  const list = free.map((candidate) => candidate.selector).join(", ")
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      message: `Model '${trimmed}' is not in the free catalog. Free models: ${list}`
+    }
+  }
+  const only = matches[0]
+  if (matches.length === 1 && only !== undefined) return { ok: true, model: only }
+  return {
+    ok: false,
+    message: `Model '${trimmed}' is ambiguous; matches: ${matches.map((candidate) => candidate.selector).join(", ")}. Pass the exact selector.`
+  }
+}
+
+const loadFreeCatalog = (omp: string): Effect.Effect<ReadonlyArray<CatalogModel>> =>
+  Effect.gen(function* () {
+    const raw = yield* Effect.promise(() => capture(omp, ["models", "--json"]))
+    if (raw === "") {
+      return yield* bail(
+        "'omp models --json' returned no output; verify omp runs on this host, then retry"
+      )
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw) as unknown
+    } catch {
+      return yield* bail(
+        "'omp models --json' returned output that is not JSON; verify the omp version, then retry"
+      )
+    }
+    const free = parseFreeModels(parsed)
+    if (free.length === 0) {
+      return yield* bail("'omp models --json' listed no free models; verify the omp login, then retry")
+    }
+    return free
+  })
+
+export const ompCommand = Command.make("omp", { model, pick, args }, (config) =>
+  Effect.gen(function* () {
+    if (Option.isSome(config.model) && config.pick) {
+      return yield* bail("Pass either --model <selector> or --pick, not both")
+    }
+
+    const omp = yield* Effect.sync(() => which("omp"))
+    if (omp === "") {
+      return yield* bail("omp not found on PATH; install omp, then retry", 1)
+    }
+
+    const home = engineHome(process.env)
+    if (Option.isSome(config.model)) {
+      const free = yield* loadFreeCatalog(omp)
+      const resolved = resolveFreeSelector(config.model.value, free)
+      if (!resolved.ok) return yield* bail(resolved.message)
+      // Compute both levels once from the catalog row so a plain launch
+      // never needs the catalog again.
+      const thinking = ladderCeiling(resolved.model.thinking)
+      const advisorThinking = advisorLevelFor(resolved.model.thinking)
+      yield* Effect.sync(() =>
+        writeOmpSessionModel(home, { selector: resolved.model.selector, thinking, advisorThinking })
+      )
+    }
+
+    if (config.pick) {
+      // Check the terminal before the catalog spawn, so a non-interactive run
+      // fails with the actionable message instead of an omp subprocess first.
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return yield* bail("Picking needs a terminal; pass --model <selector> instead")
+      }
+      const free = yield* loadFreeCatalog(omp)
+      const chosen = yield* Prompt.Select({
+        message: "Choose the free model for this omp session",
+        choices: free.map((candidate) => {
+          const ceiling = ladderCeiling(candidate.thinking)
+          return {
+            title: `${candidate.name} — ${candidate.selector}`,
+            value: candidate.selector,
+            description:
+              ceiling === undefined
+                ? `model default thinking; ${candidate.contextWindow} context`
+                : `thinking to ${ceiling}; ${candidate.contextWindow} context`
+          }
+        })
+      })
+      const match = free.find((candidate) => candidate.selector === chosen)
+      if (match === undefined) return yield* bail(`Model '${chosen}' is not in the free catalog`)
+      const thinking = ladderCeiling(match.thinking)
+      const advisorThinking = advisorLevelFor(match.thinking)
+      yield* Effect.sync(() => writeOmpSessionModel(home, { selector: match.selector, thinking, advisorThinking }))
+    }
+
+    const session: OmpSessionModel = (yield* Effect.sync(() => readOmpSessionModel(home))) ??
+      DEFAULT_OMP_SESSION_MODEL
+
+    // A stable cache path, not a temp file deleted at exit, because omp may
+    // re-read the overlay during a live session. The name carries the model,
+    // so a second launcher on another model cannot rewrite the file a running
+    // session still reads.
+    const directory = p(home, ".cache", "docks-kit")
+    const overlayPath = p(directory, overlayFileName(session.selector))
+    yield* Effect.sync(() => {
+      // `mode` applies only when mkdir creates the path, so an existing
+      // permissive cache directory keeps its mode until the chmod below.
+      mkdirSync(directory, { recursive: true, mode: 0o700 })
+      chmodSync(directory, 0o700)
+      writeFileSync(overlayPath, renderFreeOverlay(session), { mode: 0o600 })
+      chmodSync(overlayPath, 0o600)
+    })
+
+    // A level-free model states the model default so the line never shows
+    // an undefined level.
+    const hasLevel = typeof session.thinking === "string" && session.thinking.trim() !== ""
+    yield* Console.error(
+      hasLevel
+        ? `Starting omp with ${session.selector} at ${session.thinking} thinking (session only; deployed config unchanged)`
+        : `Starting omp with ${session.selector} at the model default thinking level (session only; deployed config unchanged)`
+    )
+
+    const child = yield* Effect.sync(() =>
+      spawnHost("omp", buildOmpArgs(overlayPath, config.args), { stdio: "inherit" })
+    )
+    if (child.error !== undefined) {
+      return yield* bail(
+        `Failed to start omp: ${child.error instanceof Error ? child.error.message : String(child.error)}`
+      )
+    }
+    // A signalled child reports a null status, which must not look successful.
+    yield* Effect.sync(() => process.exit(child.status ?? 1))
+  })
+).pipe(
+  Command.withDescription(
+    "Start omp with every model role overridden to the remembered free model for this run only (no deployed configuration is changed; --model or --pick remembers a new free default)."
+  )
+)

package/cli/src/commands/sync.ts

@@ -31,7 +31,7 @@ const updateNudge = (logger: Logger): void => {
 
 const VALID_TARGETS = ["claude", "codex", "agents", "omp"]
 
-const targets = Argument.String("target").pipe(
+const targets: Argument.Argument<ReadonlyArray<string>> = Argument.String("target").pipe(
   Argument.withDescription("Sync targets: claude, codex, agents, omp (default: selected harnesses)"),
   Argument.variadic()
 )

package/cli/src/commands/update.ts

@@ -1,63 +1,19 @@
 import { Command, Flag } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
-import { spawnSync, type SpawnSyncOptions, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process"
 import { existsSync, readFileSync } from "node:fs"
 import { bail, compiled } from "../engine"
 import { kitHome } from "../kitHome"
-import { p, which } from "../engine-native/exec"
-import { hostOs, type HostOs, type Invocation } from "../engine-native/os"
+import { p, spawnHost, which } from "../engine-native/exec"
+import { hostOs, type HostOs } from "../engine-native/os"
 
 const noSync = Flag.Boolean("no-sync").pipe(
   Flag.withDescription("Update the kit only; skip the chained flag-less sync"),
   Flag.withDefault(false)
 )
 
-/** A tool this host cannot resolve, shaped like the failed spawn it replaces. */
-const notFound = (command: string): SpawnSyncReturns<string> => ({
-  pid: 0,
-  output: [],
-  stdout: "",
-  stderr: "",
-  status: null,
-  signal: null,
-  error: new Error(`command not found on PATH: ${command}`)
-})
-
-/**
- * Every child in this command starts here, because two host facts must never be
- * separated from the argv they describe: a Windows shim invocation is only
- * correct with the verbatim-arguments flag, and a pathless name would let
- * CreateProcess search the parent's current directory before the system one.
- */
-export const spawnUpdate = (
-  command: string,
-  args: ReadonlyArray<string>,
-  overrides: SpawnSyncOptions = {},
-  host: HostOs = hostOs()
-): SpawnSyncReturns<string> => {
-  const resolvesSuffixes = host.executableSuffixes.some((suffix) => suffix !== "")
-  const executablePath = resolvesSuffixes ? which(command, host.executableSuffixes) : command
-  if (executablePath === "") return notFound(command)
-  let invocation: Invocation
-  try {
-    invocation = host.invoke(executablePath, args)
-  } catch (cause) {
-    // A value this host cannot put on a command line at all. Print the encoder's
-    // reason and exit, matching how this command reports a failed child.
-    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`)
-    return process.exit(2)
-  }
-  const options: SpawnSyncOptionsWithStringEncoding = {
-    stdio: ["ignore", "pipe", "pipe"],
-    ...overrides,
-    encoding: "utf8",
-    windowsVerbatimArguments: invocation.windowsVerbatimArguments
-  }
-  return spawnSync(invocation.command, [...invocation.args], options)
-}
 
 const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {
-  const res = spawnUpdate("git", ["-C", home, ...args])
+  const res = spawnHost("git", ["-C", home, ...args])
   return { ok: res.error === undefined && res.status === 0, out: `${res.stdout ?? ""}${res.stderr ?? ""}`.trim() }
 }
 
@@ -65,7 +21,7 @@ const git = (home: string, args: Array<string>): { ok: boolean; out: string } =>
  * version loaded, so the chained sync must be a new process. */
 const chainSync = (argv0: string, args: Array<string>): Effect.Effect<void> =>
   Effect.sync(() => {
-    const res = spawnUpdate(argv0, args, { stdio: "inherit" })
+    const res = spawnHost(argv0, args, { stdio: "inherit" })
     if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1)
   })
 
@@ -95,7 +51,7 @@ type CapturePackageRoot = (
 ) => PackageRootCapture
 
 const capturePackageRoot: CapturePackageRoot = (command, args) => {
-  const res = spawnUpdate(command, args)
+  const res = spawnHost(command, args)
   return {
     status: res.status,
     stdout: res.stdout ?? "",
@@ -191,7 +147,7 @@ export const packageUpdateResult = (
 
 const updateCheckout = (home: string, skipSync: boolean) =>
   Effect.gen(function* () {
-    if (spawnUpdate("git", ["--version"], { stdio: "ignore" }).status !== 0) {
+    if (spawnHost("git", ["--version"], { stdio: "ignore" }).status !== 0) {
       return yield* bail("git not found - cannot update the kit checkout")
     }
     const dirty = git(home, ["status", "--porcelain"])
@@ -217,7 +173,7 @@ const updateCheckout = (home: string, skipSync: boolean) =>
 
       const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n")
       if (touched.includes("bun.lock") || touched.includes("package.json")) {
-        const res = spawnUpdate("bun", ["install", "--frozen-lockfile"], { cwd: home, stdio: "inherit" })
+        const res = spawnHost("bun", ["install", "--frozen-lockfile"], { cwd: home, stdio: "inherit" })
         if (res.error !== undefined || res.status !== 0) {
           return yield* bail("dependencies changed but 'bun install --frozen-lockfile' failed - fix that, then run docks-kit sync", 1)
         }
@@ -245,7 +201,7 @@ const updatePackage = (home: string, skipSync: boolean) =>
     const updateArgs = manager === "bun"
       ? ["add", "-g", "docks-kit@latest"]
       : ["install", "-g", "docks-kit@latest"]
-    const res = spawnUpdate(manager, updateArgs, { stdio: "inherit" })
+    const res = spawnHost(manager, updateArgs, { stdio: "inherit" })
     if (res.error !== undefined || res.status !== 0) {
       return yield* bail(
         `global package update failed (${manager === "bun" ? "bun add -g" : "npm install -g"} docks-kit@latest)`,