docks-kit 0.16.17 → 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/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/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/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)`,

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

@@ -3,10 +3,62 @@
  * the intended binary with deterministic argv, and capture() mirrors command
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
-import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
+import {
+  spawn,
+  spawnSync,
+  type ChildProcess,
+  type SpawnOptions,
+  type SpawnSyncOptions,
+  type SpawnSyncOptionsWithStringEncoding,
+  type SpawnSyncReturns
+} from "node:child_process"
 import { accessSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { delimiter, extname, isAbsolute, join } from "node:path"
-import { hostOs, type HostOs } from "./os"
+import { hostOs, type HostOs, type Invocation } from "./os"
+
+/** 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 synchronous child 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 spawnHost = (
+  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 a caller 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)
+}
 
 /** Keep engine paths slash-separated so rendered output is host-stable. */
 export function p(...parts: Array<string>): string {

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

@@ -14,6 +14,21 @@ export type Harness = "claude" | "codex" | "agents" | "omp"
 export const HARNESSES: ReadonlyArray<Harness> = ["claude", "codex", "agents", "omp"]
 export const LEGACY_SELECTION: ReadonlyArray<Harness> = ["claude", "codex", "agents"]
 
+export interface OmpSessionModel {
+  readonly selector: string
+  // Session ceiling; absent when the model publishes no ladder, so no
+  // invented level ever reaches a selector that omp must resolve.
+  readonly thinking?: string
+  // Advisor level; absent when the model publishes no ladder.
+  readonly advisorThinking?: string
+}
+
+export const DEFAULT_OMP_SESSION_MODEL: OmpSessionModel = {
+  selector: "opencode-zen/muse-spark-1.3-contributor-free",
+  thinking: "xhigh",
+  advisorThinking: "medium",
+}
+
 function isHarness(value: unknown): value is Harness {
   return value === "claude" || value === "codex" || value === "agents" || value === "omp"
 }
@@ -36,8 +51,9 @@ export function harnessStateFile(home: string): string {
   return p(home, ".docks-kit", "state.json")
 }
 
-/** Read valid local state without allowing corruption to make sync unusable. */
-export function readHarnessSelection(home: string): ReadonlyArray<Harness> | undefined {
+// Read the whole state record so one key writer keeps sibling keys intact.
+// A corrupt file degrades to undefined so callers fall back to defaults.
+function readWholeState(home: string): Record<string, unknown> | undefined {
   let parsed: unknown
   try {
     parsed = JSON.parse(readFileSync(harnessStateFile(home), "utf8")) as unknown
@@ -47,7 +63,30 @@ export function readHarnessSelection(home: string): ReadonlyArray<Harness> | und
 
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
   const state = parsed as Record<string, unknown>
-  if (state["version"] !== 1 || !Array.isArray(state["harnesses"])) return undefined
+  if (state["version"] !== 1) return undefined
+  return state
+}
+
+// Merge the patch over the stored record so independent keys never erase
+// each other when only one writer runs.
+function writeWholeState(home: string, patch: Record<string, unknown>): void {
+  const existing = readWholeState(home) ?? {}
+  const next = { ...existing, ...patch, version: 1 }
+  const directory = p(home, ".docks-kit")
+  const file = harnessStateFile(home)
+  const text = `${JSON.stringify(next, null, 2)}\n`
+  // `mode` applies only when mkdir creates the path, so an existing permissive
+  // ~/.docks-kit would keep its mode.
+  mkdirSync(directory, { recursive: true, mode: 0o700 })
+  chmodSync(directory, 0o700)
+  writeFileSync(file, text, { mode: 0o600 })
+  chmodSync(file, 0o600)
+}
+
+/** Read valid local state without allowing corruption to make sync unusable. */
+export function readHarnessSelection(home: string): ReadonlyArray<Harness> | undefined {
+  const state = readWholeState(home)
+  if (state === undefined || !Array.isArray(state["harnesses"])) return undefined
 
   const selection = normalizeHarnesses(state["harnesses"])
   return selection.length > 0 ? selection : undefined
@@ -63,13 +102,55 @@ export function writeHarnessSelection(home: string, selection: ReadonlyArray<Har
     throw new Error("Harness selection must contain at least one known harness name")
   }
 
-  const directory = p(home, ".docks-kit")
-  const file = harnessStateFile(home)
-  const text = `${JSON.stringify({ version: 1, harnesses }, null, 2)}\n`
-  // `mode` applies only when mkdir creates the path, so an existing permissive
-  // ~/.docks-kit would keep its mode.
-  mkdirSync(directory, { recursive: true, mode: 0o700 })
-  chmodSync(directory, 0o700)
-  writeFileSync(file, text, { mode: 0o600 })
-  chmodSync(file, 0o600)
+  writeWholeState(home, { harnesses })
+}
+
+function isNonBlankString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== ""
+}
+
+// Read the stored session model without throwing so a corrupt entry falls
+// back to the default instead of breaking sync.
+export function readOmpSessionModel(home: string): OmpSessionModel | undefined {
+  const state = readWholeState(home)
+  if (state === undefined) return undefined
+  const entry = state["ompSession"]
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return undefined
+  const record = entry as Record<string, unknown>
+  if (!isNonBlankString(record["selector"])) {
+    return undefined
+  }
+  // Each level stands alone, so a level-free model reads back with no
+  // levels while a half-corrupt entry keeps the valid level.
+  const model: { selector: string; thinking?: string; advisorThinking?: string } = {
+    selector: record["selector"],
+  }
+  if (isNonBlankString(record["thinking"])) {
+    model.thinking = record["thinking"]
+  }
+  if (isNonBlankString(record["advisorThinking"])) {
+    model.advisorThinking = record["advisorThinking"]
+  }
+  return model
+}
+
+export function writeOmpSessionModel(home: string, model: OmpSessionModel): void {
+  // A blank selector would make omp resolve an arbitrary model, so reject it
+  // before anything reaches disk.
+  if (!isNonBlankString(model.selector)) {
+    throw new Error("Omp session model selector must be a non-empty string")
+  }
+  // Persist only non-blank levels so a switch to a level-free model leaves
+  // no stale level behind in the stored record.
+  const entry: { selector: string; thinking?: string; advisorThinking?: string } = {
+    selector: model.selector,
+  }
+  if (isNonBlankString(model.thinking)) {
+    entry.thinking = model.thinking
+  }
+  if (isNonBlankString(model.advisorThinking)) {
+    entry.advisorThinking = model.advisorThinking
+  }
+
+  writeWholeState(home, { ompSession: entry })
 }

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

@@ -0,0 +1,174 @@
+/**
+ * Run overlay for `docks-kit omp`. The overlay merges over the deployed omp
+ * config for one run only, so every key that can cause paid spend is set here
+ * and every other key falls through to the deployed paid config.
+ */
+import { createHash } from "node:crypto"
+import type { OmpSessionModel } from "./harnesses"
+
+export interface CatalogModel {
+  readonly selector: string
+  readonly name: string
+  readonly thinking: ReadonlyArray<string>
+  readonly contextWindow: number
+}
+
+/** Thinking levels from lowest to highest effort. */
+export const THINKING_LADDER: ReadonlyArray<string> = [
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]
+
+/**
+ * One overlay file per model, so a second launcher on another model cannot
+ * rewrite the file a running session still reads. A selector carries a slash
+ * and may carry other characters a host rejects in a file name, so unsafe
+ * characters become hyphens. That mapping alone is not injective, because
+ * `a/b` and `a-b` both fold to `a-b`, so a digest of the exact selector keeps
+ * two distinct models on two distinct files.
+ */
+export function overlayFileName(selector: string): string {
+  const safe = selector.replace(/[^A-Za-z0-9._-]/g, "-")
+  const digest = createHash("sha256").update(selector).digest("hex").slice(0, 8)
+  return `omp-free-${safe}-${digest}.yml`
+}
+
+/** Role keys in the order used by SoT/.omp/config.yml for readable diffs. */
+const ROLE_ORDER: ReadonlyArray<string> = [
+  "smol",
+  "advisor",
+  "designer",
+  "plan",
+  "commit",
+  "task",
+  "vision",
+  "tiny",
+  "default",
+  "slow",
+  "fable",
+  "switch_fable",
+]
+
+/** Retry chain keys in the order used by SoT/.omp/config.yml. */
+const FALLBACK_ORDER: ReadonlyArray<string> = [
+  "default",
+  "advisor",
+  "task",
+  "vision",
+  "smol",
+  "tiny",
+  "commit",
+  "switch_fable",
+  "fable",
+]
+
+/**
+ * Collect free models from parsed `omp models --json` output. The function is
+ * total because catalog output varies across omp versions, and one malformed
+ * row must not discard the remaining picker list.
+ */
+export function parseFreeModels(catalogJson: unknown): ReadonlyArray<CatalogModel> {
+  if (typeof catalogJson !== "object" || catalogJson === null || Array.isArray(catalogJson)) {
+    return []
+  }
+  const models = (catalogJson as Record<string, unknown>)["models"]
+  if (!Array.isArray(models)) return []
+  const found: Array<CatalogModel> = []
+  for (const row of models) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) continue
+    const record = row as Record<string, unknown>
+    const selector = record["selector"]
+    if (typeof selector !== "string" || selector.length === 0) continue
+    const cost = record["cost"]
+    if (typeof cost !== "object" || cost === null || Array.isArray(cost)) continue
+    const charges = cost as Record<string, unknown>
+    if (charges["input"] !== 0 || charges["output"] !== 0) continue
+    const rawName = record["name"]
+    const name = typeof rawName === "string" && rawName.length > 0 ? rawName : selector
+    const rawLevels = record["thinking"]
+    // Keep only known ladder levels in ladder order so an unknown future
+    // level never reaches a role value that omp would reject.
+    const thinking = THINKING_LADDER.filter(
+      (level) => Array.isArray(rawLevels) && (rawLevels as Array<unknown>).includes(level),
+    )
+    const rawWindow = record["contextWindow"]
+    const contextWindow =
+      typeof rawWindow === "number" && Number.isFinite(rawWindow) ? rawWindow : 0
+    found.push({ selector, name, thinking, contextWindow })
+  }
+  // Sort by selector so the picker list is stable across catalog orderings.
+  found.sort((a, b) => (a.selector < b.selector ? -1 : a.selector > b.selector ? 1 : 0))
+  return found
+}
+
+/**
+ * Resolve the highest ladder level a model supports. A model without a
+ * recognized ladder yields undefined so callers never invent a level the
+ * model would reject at session start.
+ */
+export function ladderCeiling(levels: ReadonlyArray<string>): string | undefined {
+  for (let index = THINKING_LADDER.length - 1; index >= 0; index -= 1) {
+    if (levels.includes(THINKING_LADDER[index] as string)) return THINKING_LADDER[index] as string
+  }
+  return undefined
+}
+
+/**
+ * Resolve the advisor level from the model own ladder. The advisor runs
+ * quick review passes, so it takes the highest level at or below medium,
+ * and the lowest level when the ladder starts above medium. The result
+ * never exceeds the ladder ceiling by construction.
+ */
+export function advisorLevelFor(levels: ReadonlyArray<string>): string | undefined {
+  const known = THINKING_LADDER.filter((level) => levels.includes(level))
+  if (known.length === 0) return undefined
+  const mediumIndex = THINKING_LADDER.indexOf("medium")
+  let advisor: string | undefined
+  for (const level of known) {
+    if ((THINKING_LADDER.indexOf(level) as number) <= (mediumIndex as number)) advisor = level
+  }
+  return advisor ?? (known[0] as string)
+}
+
+/**
+ * Render the run overlay as YAML text. Empty fallback chains keep a retry
+ * from falling back onto a paid model. A model without a level renders bare
+ * selectors with no thinking keys so the deployed values apply.
+ */
+export function renderFreeOverlay(model: OmpSessionModel): string {
+  const thinking = typeof model.thinking === "string" && model.thinking.trim() !== "" ? model.thinking : undefined
+  const lines: Array<string> = ["# Generated per run by docks-kit omp. Edits are overwritten."]
+  if (thinking !== undefined) {
+    lines.push(`defaultThinkingLevel: ${thinking}`, "modelRoles:")
+    const advisor =
+      typeof model.advisorThinking === "string" && model.advisorThinking.trim() !== ""
+        ? model.advisorThinking
+        : thinking
+    for (const role of ROLE_ORDER) {
+      lines.push(`  ${role}: ${model.selector}:${role === "advisor" ? advisor : thinking}`)
+    }
+    lines.push("task:", `  maxEffort: ${thinking}`)
+  } else {
+    lines.push("modelRoles:")
+    for (const role of ROLE_ORDER) {
+      lines.push(`  ${role}: ${model.selector}`)
+    }
+  }
+  lines.push("retry:", "  fallbackChains:")
+  for (const chain of FALLBACK_ORDER) {
+    lines.push(`    ${chain}: []`)
+  }
+  return `${lines.join("\n")}\n`
+}
+
+/** Build the omp argv with the overlay flag ahead of the forwarded args. */
+export function buildOmpArgs(
+  overlayPath: string,
+  passthrough: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+  return ["--config", overlayPath, ...passthrough]
+}

package/cli/src/generated/sotPayload.ts

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

package/cli/src/main.ts

@@ -7,6 +7,7 @@ import { docsCommand } from "./commands/docs"
 import { harnessesCommand } from "./commands/harnesses"
 import { modelCommand } from "./commands/model"
 import { modelsCommand } from "./commands/models"
+import { ompCommand } from "./commands/omp"
 import { pluginsCommand } from "./commands/plugins"
 import { skillsCommand } from "./commands/skills"
 import { statusCommand } from "./commands/status"
@@ -32,6 +33,7 @@ const root = Command.make("docks-kit", {}, () =>
     yield* Console.log("  docks-kit plugins list                     plugin tri-state")
     yield* Console.log("  docks-kit skills list                      universal skills")
     yield* Console.log("  docks-kit docs [topic]                     self-documentation")
+    yield* Console.log("  docks-kit omp [--model|--pick] [...]       free-model omp session")
     yield* Console.log("")
     yield* Console.log("Run 'docks-kit --help' for full option listings (also: --wizard, --completions).")
     yield* Console.log("No-Bun recovery path: use a platform release binary.")
@@ -50,7 +52,8 @@ const root = Command.make("docks-kit", {}, () =>
     statusCommand,
     pluginsCommand,
     skillsCommand,
-    docsCommand
+    docsCommand,
+    ompCommand
   ])
 )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.16.17",
+  "version": "0.17.0",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",