docks-kit 0.18.0 → 0.19.0

package/AGENTS.md

@@ -35,12 +35,14 @@ launcher can fall back to Bun source.
 | `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/src/engine-native/<axis>.ts` | One change axis per file: `codexConfig`/`codexHooks`/`codexPlugins`/`codexStatus`, `claudeSettings`/`claudeRemovals`/`claudePluginPasses`/`claudeOptionalPlugins`/`claudeLsp`, `parseModifiers`/`parseHelp`, `ompFileDeploy`/`ompMarketplace`/`ompPlugins`, `skillsManifest`/`skillsLinks`/`skillsInstall`/`skillsPrune`, `engineCtx`/`syncConcurrency`/`syncDispatch`; orchestrators keep prior exports |
-| `cli/src/engine-native/sharedTypes.d.ts` | Single definition per shared shape (manifest records, settings edits, omp session model, scalar modifier flags) |
+| `cli/src/engine-native/sharedTypes.d.ts` | Single definition per shared shape (manifest records, settings edits, omp session model, scalar modifier flags, resolved model catalog) |
+| `cli/src/engine-native/kitDb.ts` | Only opener of the SQLite store `~/.docks-kit/kit.db`: append-only migrations, one-time `state.json` import, TTL cache |
+| `cli/src/engine-native/liveModels.ts` | Live model list per enabled harness (Anthropic API via Claude Code login, Codex model cache, `omp models --json`) merged over `SoT/models.json` |
 | `.oxlintrc.json` / `.oxfmtrc.json` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and code format scope |
 | `cli/test/fixtures/` | Golden fixtures: `home-fresh`, `home-drift`, `home-invalid-json`, `codex-toml`, `statusline` |
 | `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) |
+| `SoT/models.json` | Curated Claude and Codex model overlay: aliases and notes always apply; id rows are the fallback when a harness live list is unavailable |
+| `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
 | `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, and `intercom.json` |
 | `install.sh` / `install.ps1` | POSIX and Windows global installers |
@@ -73,7 +75,7 @@ omp SoT notes:
 - `ompSync.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards.
 - `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync, without `--reconcile`. The pass is required because `mergeOmpConfig` is additive, so removing a key from the SoT alone never removes it from a deployed file. A key retired with a recorded value is pruned only while the deployed value still matches that value, so a user edit survives; a key retired outright, such as `providers.webSearchOrder`, is pruned at any value.
 - `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6-astra:xhigh`, and `modelTags.astra` is visible. Astra and Fable fall back to each other through concrete selectors. `modelRoles.fable` remains `anthropic/claude-fable-5-1:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
-- `modelRoles.task` is `openai-codex/gpt-6-sol:high`, and `advisor` is `openai-codex/gpt-6-sol:medium`. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The four reviewer entries in `task.agentModelOverrides` inherit `task` through `@task`. Only bundled `reviewer` and `security-reviewer` are discoverable OMP agents; `code-reviewer` and `plan-reviewer` stay dormant. omp 18.2.9 does not list `gpt-6-sol` or `gpt-6-luna` in its `openai-codex` catalog, so it fuzzy-matches both selectors to the GPT-5.6 models without a warning until the catalog lists them. The owner deployed them anyway. `cli/docs/omp-models.md` records the checks.
+- `modelRoles.task` is `openai-codex/gpt-6-sol:high`. `advisor` is `anthropic/claude-opus-5-5:medium` with an empty fallback chain, because a GPT-6 Sol advisor looped on repeated reads under an Opus 5.5 session; never put GPT-6 Sol in the advisor role or chain. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The four reviewer entries in `task.agentModelOverrides` inherit `task` through `@task`. Only bundled `reviewer` and `security-reviewer` are discoverable OMP agents; `code-reviewer` and `plan-reviewer` stay dormant. omp 18.2.9 does not list `gpt-6-sol` or `gpt-6-luna` in its `openai-codex` catalog, so it fuzzy-matches both selectors to the GPT-5.6 models without a warning until the catalog lists them. The owner deployed them anyway. `cli/docs/omp-models.md` records the checks.
 - The five Anthropic roles (`default`, `slow`, `plan`, `designer`, `vision`) and the five Anthropic retry chains use `anthropic/claude-opus-5-5` at the levels the role map records. `cli/docs/omp-models.md` carries the Artificial Analysis capture behind the role map, read 2026-09-22 at Intelligence Index v4.3.2 and Coding Agent Index v1.5 from the AA comparison-page metric tables. Opus 5.5 max has the highest index in that topic. AA has not measured speed or latency for Opus 5.5 max, GPT-6 Sol, or GPT-6 Luna.
 - `modelRoles.web` is `web/firecrawl` and `retry.fallbackChains.web` carries the explicit 20-entry provider order. The kit declares both keys because the legacy `providers.webSearchOrder` key is retired: omp expands it in memory into these two keys and then drops it, and never writes that expansion back to disk. An explicit chain replaces omp's built-in web order wholesale, so every entry left out is a provider omp never tries. The owner removed the seven entries that named older models (Gemini 2.5 Flash, Claude Haiku 4.5, GPT-5.6, GPT-5.5, and Grok 4.5); keep every other provider.
 - `SoT/.omp/models.yml` declares Astra's full `low, medium, high, xhigh, max` ladder with `defaultLevel: xhigh` as the worked provider ladder-override example. It also carries a temporary `anthropic.modelOverrides.claude-opus-5-5` block with that model's limits, ladder, and prices, because the shared catalog still serves the id as a stub with null limits and zero cost; remove the block once the catalog publishes the row. `ompYaml.ts mergeOmpModels` preserves deployed-only keys in `~/.omp/agent/models.yml`, because a user file may carry provider credentials. Whole-file replacement is wrong.
@@ -84,7 +86,7 @@ omp SoT notes:
 - 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 with every model role set to one free model and every retry chain empty. Higher-precedence model selection can replace those overlay values. It renders the 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 levels from the ladder of the chosen model for the `--model` path, and `ompOverlay.ts planEffortChoice` drives the `--pick` wizard, which asks whether every role shares one level and otherwise takes one level for the main roles and one for the advisor from that model's own ladder. Levels never come 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.
+- The session model persists per machine in `~/.docks-kit/kit.db` (table `omp_session`), next to the harness selection. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both levels from the ladder of the chosen model for the `--model` path, and `ompOverlay.ts planEffortChoice` drives the `--pick` wizard, which asks whether every role shares one level and otherwise takes one level for the main roles and one for the advisor from that model's own ladder. Levels never come 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.
 
@@ -96,7 +98,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 `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.
+- **Per-machine harness selection.** The SQLite store `~/.docks-kit/kit.db` drives a flag-less sync. A missing selection selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection. `docks-kit harnesses` is the only command that writes the `harness_selection` table. The same store holds the independent `omp_session` table, which only `docks-kit omp` writes, and a TTL cache (`cache_entry`) for the live Anthropic model list and `toolchain outdated` lookups. `kitDb.ts withKitDb` is the only opener: it runs the append-only `MIGRATIONS`, imports a legacy `state.json` once and renames it to `state.json.migrated`, and refuses a store from a newer schema. Cache rows carry the kit version as fingerprint, so a new release refetches them.
 - **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.** Axis modules own one concern each (see layout); orchestrators (`claudeSync.ts`, `codexSync.ts`, `skillsSync.ts`, `ompSync.ts`, `index.ts`, `argv.ts`, `parseArgs.ts`) keep prior exports. New shared shapes go in `sharedTypes.d.ts`, never a second local copy. The public CLI seam is `cli/src/engine.ts`.

package/README.md

@@ -47,9 +47,9 @@ docks-kit sync [claude] [codex] [agents] [omp]  deploy explicit targets or the m
 docks-kit harnesses                             view or change this machine's selection
 docks-kit update [--no-sync]                    self-update the kit (autodetects checkout vs global install), then sync
 docks-kit model <claude|codex> [value]          get/set the DEPLOYED model (TTY picker)
-docks-kit models [claude|codex]                 model catalogs (`--json`)
+docks-kit models [claude|codex|omp] [--refresh]  live catalogs for enabled harnesses (`--json`)
 docks-kit omp [--model <m>|--pick] [args...]    one omp session on a free model, nothing deployed changes
-docks-kit toolchain [check|ensure <tool>]       verified-version floors for external tools
+docks-kit toolchain [check|ensure <tool>|outdated]  verified-version floors for external tools
 docks-kit status [--json]                       deployed-vs-SoT drift + toolchain + counts
 docks-kit plugins list [--json]                 enabledPlugins tri-state vs installed
 docks-kit skills list [--json]                  universal skills vs manifest
@@ -91,16 +91,16 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 - **Additive by default** — user-only settings keys, plugins, and skills
   survive a plain sync. Reconciliation toward the SoT is explicit
   (`--reconcile` / `--prune`).
-- **Per-machine selection** — `~/.docks-kit/state.json` drives a flag-less sync.
-  A missing file selects Claude Code, Codex, and universal skills. It does not
+- **Per-machine selection** — `~/.docks-kit/kit.db` drives a flag-less sync.
+  A missing selection selects Claude Code, Codex, and universal skills. It does not
   select omp. Use `docks-kit harnesses` to view or change the selection.
 - **Idempotent** — every step is safe to re-run; no-change syncs are no-ops.
 - **Toolchain floors** — `SoT/toolchain.json` records the kit-verified version
   floors for external tools (bun, bwrap, …). `docks-kit toolchain check` prints
   the full doctor table. Bun is the one managed install and is pinned to its
   verified version.
-- **Model catalog** — `SoT/models.json` is the research-verified source for
-  model validation, listings, and pickers.
+- **Model catalog** — enabled harnesses provide live Claude, Codex, or omp
+  model IDs; `SoT/models.json` supplies aliases, notes, and the offline fallback.
 - **Claude runtime** — sync materializes three dependency-free Bun `.mjs`
   programs for statusline, SessionStart, and Notification. Quota display uses
   Claude's native `rate_limits`; there is no OAuth fetch, shared usage cache,
@@ -115,7 +115,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
 | `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json) |
 | `SoT/.agents/` | Universal-skill manifest |
-| `SoT/models.json` | Kit-verified Claude and Codex model catalog |
+| `SoT/models.json` | Curated aliases, notes, and offline Claude/Codex fallback |
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
 | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |

package/cli/docs/flags.md

@@ -14,7 +14,7 @@ docks-kit sync omp                  # opt-in harness
 
 Positional targets are `claude`, `codex`, `agents`, and `omp`. A flag-less
 `sync` deploys the per-machine harness selection stored in
-`~/.docks-kit/state.json`. A missing or invalid state file selects `claude`,
+`~/.docks-kit/kit.db`. A missing selection or an unreadable store selects `claude`,
 `codex`, and `agents`, and never selects `omp`. Choose the stored selection
 with `docks-kit harnesses`.
 
@@ -56,7 +56,7 @@ ignored with a warning; Claude modifiers never touch Codex config and vice versa
 
 | 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` |
+| `--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/kit.db` (table `omp_session`) |
 | `--pick` | Interactive picker over free catalog models; records the choice the same way |
 
 Remaining arguments forward verbatim to omp after the launcher flags.

package/cli/docs/models.md

@@ -1,9 +1,17 @@
 # Models
 
-`SoT/models.json` is the kit-verified model catalog — the single source for
-the engine validators, `docks-kit models`, the interactive picker, and the
-bare-flag helper output. Each tool section carries a `verified` date; update
-the entry and date when a model ships or retires.
+`SoT/models.json` supplies aliases and notes for Claude and Codex. For each
+enabled harness, `docks-kit models` and the picker list live model IDs when
+available. Claude uses the Claude Code login to query the Anthropic models API
+and caches the result for six hours in `~/.docks-kit/kit.db`; Codex reads
+`~/.codex/models_cache.json`; omp runs `omp models --json`. The kit never needs
+omp to list Claude models.
+
+Live lists retain the curated aliases and notes, but omit curated IDs absent
+from the live source. A disabled harness, missing login/cache, or unavailable
+source falls back to the curated IDs. omp has no curated fallback models.
+The `verified` field is the curated section date, not the live fetch date.
+Bare model flags without a value print the curated list without a network call.
 
 ## Validation rules
 
@@ -33,9 +41,10 @@ the entry and date when a model ships or retires.
 ## Commands
 
 ```
-docks-kit models                  # both catalogs
-docks-kit models claude --json    # machine-readable
-docks-kit model claude            # current deployed + SoT + picker (TTY)
+docks-kit models                  # enabled Claude, Codex, and omp catalogs
+docks-kit models claude --json    # source, fetch date, and fallback reason
+docks-kit models claude --refresh # bypass the six-hour Anthropic cache
+docks-kit model claude            # current deployed + live list + picker (TTY)
 docks-kit model claude opus       # per-machine override from the Opus SoT
 docks-kit sync claude --claude-model=opus   # same, as part of a sync
 ```

package/cli/docs/omp-models.md

@@ -12,7 +12,7 @@ against.
 | `slow` | `anthropic/claude-opus-5-5` | xhigh | 56 | $3.46 | 165.20 s |
 | `plan` | `anthropic/claude-opus-5-5` | xhigh | 56 | $3.46 | 165.20 s |
 | `task` | `openai-codex/gpt-6-sol` | high | 43 | $0.37 | n/a |
-| `advisor` | `openai-codex/gpt-6-sol` | medium | 40 | $0.25 | n/a |
+| `advisor` | `anthropic/claude-opus-5-5` | medium | 51 | $1.34 | 22.17 s |
 | `designer` | `anthropic/claude-opus-5-5` | high | 54 | $1.82 | 12.49 s |
 | `vision` | `anthropic/claude-opus-5-5` | medium | 51 | $1.34 | 22.17 s |
 | `smol` / `commit` | `openai-codex/gpt-6-luna` | medium | 29 | $0.02 | n/a |
@@ -83,6 +83,19 @@ chains, `retry.fallbackChains.default` would send either stop to
 Chain entries are concrete selectors, not role aliases, so this pair cannot
 recurse. The hidden `switch_fable` chain stays empty.
 
+### Why `advisor` runs Opus 5.5 medium
+
+`advisor` runs `anthropic/claude-opus-5-5:medium` with an empty fallback
+chain. On 2026-09-24, with omp 18.3.0, an Opus 5.5 session with the advisor
+on `openai-codex/gpt-6-sol:medium` looped. In one session the advisor made
+1,313 requests for 140 main-agent requests. It issued 1,272 `read` calls on
+248 distinct paths, read one 3-line slice 249 times, and never called
+`advise`. The advisor prompt averaged about 317k tokens, above the 272K
+window omp lists for GPT-6 Sol. With the advisor on Opus 5.5 medium, the
+same kind of session made about one advisor request per main-agent request
+and called `advise` normally. The owner excluded GPT-6 Sol from the advisor
+role and its fallback chain.
+
 `modelRoles.web` is `web/firecrawl`, and `retry.fallbackChains.web` lists the
 explicit 20-entry provider order that follows it. The two keys replace the
 retired `providers.webSearchOrder` key, which omp no longer carries in its
@@ -405,8 +418,8 @@ distinct ladders: 21 include `medium`, 3 stop at `low, high, max` or
 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
+The choice persists per machine in `~/.docks-kit/kit.db` (table
+`omp_session`), next to the harness selection. It survives across sessions. It is never
 committed. `--model <selector>` records one selector and derives both levels
 from the catalog row. `--pick` opens an interactive wizard.
 

package/cli/docs/sync-layers.md

@@ -2,7 +2,7 @@
 
 `docks-kit sync [claude] [codex] [agents] [omp]` — targets are positional
 words; no target means this machine's harness selection in
-`~/.docks-kit/state.json`. The default is `claude codex agents`, and
+`~/.docks-kit/kit.db`. The default is `claude codex agents`, and
 `docks-kit harnesses` changes it.
 
 ## claude (→ ~/.claude, ~/.claude.json, shell rc)

package/cli/docs/toolchain.md

@@ -85,4 +85,14 @@ manifest's `verified` version.
 ```text
 docks-kit toolchain check                    # doctor table (also inside docks-kit status)
 docks-kit toolchain ensure bun               # ensure the only managed tool
+docks-kit toolchain outdated [--refresh]     # verified pins vs newest upstream release
 ```
+
+`docks-kit toolchain outdated` reads each tool's optional `upstream` entry in
+`SoT/toolchain.json`. An `npm` entry reads the registry `latest` tag. With a
+`line`, it reads the newest release on that major line instead, so `tsc` stays
+on 6.x. A `github` entry reads the latest release tag and strips `tagPrefix`.
+Set `GITHUB_TOKEN` or `GH_TOKEN` to raise the GitHub rate limit. Successful
+lookups cache for 24 hours in `~/.docks-kit/kit.db`; `--refresh` bypasses the
+cache. The report never installs anything and never edits a pin. A failed
+lookup prints `lookup failed: <reason>` and the command still exits 0.

package/cli/src/commands/harnesses.ts

@@ -4,12 +4,12 @@ import { bail } from "../engine";
 import {
   engineHome,
   HARNESSES,
-  harnessStateFile,
   LEGACY_SELECTION,
   readHarnessSelection,
   writeHarnessSelection,
   type Harness,
 } from "../engine-native/harnesses";
+import { kitDbFile } from "../engine-native/kitDb";
 
 const DESCRIPTIONS: Record<Harness, string> = {
   claude: "Claude Code user configuration",
@@ -50,7 +50,7 @@ export const harnessesCommand = Command.make("harnesses", {}, () =>
     }
 
     yield* Effect.sync(() => writeHarnessSelection(home, answer));
-    yield* Console.log(`Saved harness selection: ${answer.join(", ")} (${harnessStateFile(home)})`);
+    yield* Console.log(`Saved harness selection: ${answer.join(", ")} (${kitDbFile(home)})`);
   }),
 ).pipe(
   Command.withDescription("Choose the harness selection that drives a flag-less docks-kit sync."),

package/cli/src/commands/model.ts

@@ -1,7 +1,8 @@
 import { Argument, Command, Flag, Prompt } from "effect/unstable/cli";
 import { Effect, Option } from "effect";
 import { bail, engine } from "../engine";
-import { modelCatalog } from "../engine-native/models";
+import { engineHome } from "../engine-native/harnesses";
+import { defaultLiveInputs, resolveCatalog } from "../engine-native/liveModels";
 import type { Tool } from "../manifests";
 
 const tool = Argument.String("tool").pipe(Argument.withDescription("Which tool: claude | codex"));
@@ -42,7 +43,9 @@ export const modelCommand = Command.make("model", { tool, value, dryRun, verbose
     // … and offer an interactive picker when attached to a terminal.
     if (!process.stdin.isTTY || !process.stdout.isTTY) return;
 
-    const catalog = modelCatalog(t);
+    const catalog = yield* Effect.promise(() =>
+      resolveCatalog(t, defaultLiveInputs(engineHome(process.env))),
+    );
     const chosen = yield* Prompt.Select({
       message: `Set the deployed ${t} model (deployed config only; a flag-less sync reverts to SoT)`,
       choices: [

package/cli/src/commands/models.ts

@@ -1,48 +1,75 @@
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { Console, Effect, Option } from "effect";
 import { bail } from "../engine";
-import { modelCatalog } from "../engine-native/models";
-import type { Tool } from "../manifests";
+import { engineHome, LEGACY_SELECTION, readHarnessSelection } from "../engine-native/harnesses";
+import { defaultLiveInputs, resolveCatalog } from "../engine-native/liveModels";
+import type { CatalogTool, ResolvedCatalog } from "../engine-native/sharedTypes";
 
 const tool = Argument.String("tool").pipe(
-  Argument.withDescription("claude | codex (omit for both tool catalogs)"),
+  Argument.withDescription("claude | codex | omp (omit for enabled harnesses)"),
   Argument.optional,
 );
 const json = Flag.Boolean("json").pipe(
   Flag.withDescription("Machine-readable output"),
   Flag.withDefault(false),
 );
+const refresh = Flag.Boolean("refresh").pipe(
+  Flag.withDescription("Bypass the kit cache (~/.docks-kit/kit.db) and fetch live lists again"),
+  Flag.withDefault(false),
+);
 
-const renderTool = (t: Tool) =>
+function isCatalogTool(value: string): value is CatalogTool {
+  return value === "claude" || value === "codex" || value === "omp";
+}
+
+const renderTool = (t: CatalogTool, catalog: ResolvedCatalog) =>
   Effect.gen(function* () {
-    const catalog = modelCatalog(t);
-    yield* Console.log(`${t} models (kit-verified ${catalog.verified}):`);
+    yield* Console.log(
+      catalog.source === "curated"
+        ? `${t} models (kit-verified ${catalog.verified}):`
+        : `${t} models (live — ${catalog.source}, fetched ${catalog.fetchedAt ?? "?"}):`,
+    );
+    if (catalog.fallbackReason !== undefined) {
+      yield* Console.log(`  (live list unavailable: ${catalog.fallbackReason})`);
+    }
     for (const m of catalog.models) {
       yield* Console.log(`  ${m.id.padEnd(28)} ${m.kind.padEnd(6)} ${m.note ?? ""}`);
     }
-    yield* Console.log(
-      t === "claude"
-        ? "  (full claude-* model IDs outside the catalog are accepted with a warning)"
-        : "  (well-formed IDs outside the catalog are accepted with a warning)",
-    );
+    if (t === "claude") {
+      yield* Console.log(
+        "  (full claude-* model IDs outside the catalog are accepted with a warning)",
+      );
+    } else if (t === "codex") {
+      yield* Console.log("  (well-formed IDs outside the catalog are accepted with a warning)");
+    }
     yield* Console.log("");
   });
 
-export const modelsCommand = Command.make("models", { tool, json }, (config) =>
+export const modelsCommand = Command.make("models", { tool, json, refresh }, (config) =>
   Effect.gen(function* () {
     const requested = Option.getOrUndefined(config.tool);
-    if (requested !== undefined && requested !== "claude" && requested !== "codex") {
-      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex)`);
-    }
-    const tools: Array<Tool> = requested !== undefined ? [requested as Tool] : ["claude", "codex"];
-
-    if (config.json) {
-      const out = Object.fromEntries(tools.map((t) => [t, modelCatalog(t)]));
-      return yield* Console.log(JSON.stringify(out, null, 2));
+    if (requested !== undefined && !isCatalogTool(requested)) {
+      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex, omp)`);
     }
-
+    const home = engineHome(process.env);
+    const tools: ReadonlyArray<CatalogTool> =
+      requested !== undefined
+        ? [requested]
+        : (readHarnessSelection(home) ?? LEGACY_SELECTION).filter(isCatalogTool);
+    const inputs = defaultLiveInputs(home, config.refresh);
+    const out: Partial<Record<CatalogTool, ResolvedCatalog>> = {};
     for (const t of tools) {
-      yield* renderTool(t);
+      const catalog = yield* Effect.promise(() => resolveCatalog(t, inputs));
+      if (config.json) {
+        out[t] = catalog;
+      } else {
+        yield* renderTool(t, catalog);
+      }
     }
+    if (config.json) yield* Console.log(JSON.stringify(out, null, 2));
   }),
-).pipe(Command.withDescription("List kit-verified Claude and Codex models (SoT/models.json)."));
+).pipe(
+  Command.withDescription(
+    "List models per enabled harness: live from each harness's login or cache, with SoT/models.json aliases and notes as overlay and offline fallback.",
+  ),
+);

package/cli/src/commands/toolchain.ts

@@ -5,7 +5,7 @@ import { bail, engine } from "../engine";
 const MANAGED = ["bun"];
 
 const op = Argument.String("op").pipe(
-  Argument.withDescription("check (default) | ensure <tool>"),
+  Argument.withDescription("check (default) | ensure <tool> | outdated"),
   Argument.optional,
 );
 const tool = Argument.String("tool").pipe(
@@ -17,28 +17,39 @@ const verbose = Flag.Boolean("verbose").pipe(
   Flag.withDescription("Also print no-op confirmations (present, up to date)"),
   Flag.withDefault(false),
 );
+const refresh = Flag.Boolean("refresh").pipe(
+  Flag.withDescription("outdated: bypass the 24 h cache"),
+  Flag.withDefault(false),
+);
 
-export const toolchainCommand = Command.make("toolchain", { op, tool, verbose }, (config) =>
-  Effect.gen(function* () {
-    const operation = Option.getOrElse(config.op, () => "check");
-    const flags = config.verbose ? ["--verbose"] : [];
+export const toolchainCommand = Command.make(
+  "toolchain",
+  { op, tool, verbose, refresh },
+  (config) =>
+    Effect.gen(function* () {
+      const operation = Option.getOrElse(config.op, () => "check");
+      const flags = config.verbose ? ["--verbose"] : [];
 
-    switch (operation) {
-      case "check":
-        return yield* engine(["toolchain", "check", ...(config.verbose ? ["--verbose"] : [])]);
-      case "ensure": {
-        const t = Option.getOrUndefined(config.tool);
-        if (t === undefined || !MANAGED.includes(t)) {
-          return yield* bail(`toolchain ensure needs a managed tool: ${MANAGED.join(", ")}`);
+      switch (operation) {
+        case "check":
+          return yield* engine(["toolchain", "check", ...(config.verbose ? ["--verbose"] : [])]);
+        case "ensure": {
+          const t = Option.getOrUndefined(config.tool);
+          if (t === undefined || !MANAGED.includes(t)) {
+            return yield* bail(`toolchain ensure needs a managed tool: ${MANAGED.join(", ")}`);
+          }
+          return yield* engine(["toolchain", "ensure", t, ...flags]);
         }
-        return yield* engine(["toolchain", "ensure", t, ...flags]);
+        case "outdated":
+          return yield* engine(["toolchain", "outdated", ...(config.refresh ? ["--refresh"] : [])]);
+        default:
+          return yield* bail(
+            `Unknown toolchain op '${operation}' (valid: check, ensure, outdated)`,
+          );
       }
-      default:
-        return yield* bail(`Unknown toolchain op '${operation}' (valid: check, ensure)`);
-    }
-  }),
+    }),
 ).pipe(
   Command.withDescription(
-    "Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing.",
+    "Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing; outdated compares verified pins with the newest upstream release (network, report only).",
   ),
 );

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

@@ -1,13 +1,11 @@
 /**
- * Per-machine harness selection at ~/.docks-kit/state.json. The selection keeps
- * the omp harness opt-in. A missing or unreadable state file is represented by
- * undefined so callers resolve it to LEGACY_SELECTION and existing machines
- * keep today's behavior.
+ * Per-machine harness selection and omp session model, stored in ~/.docks-kit/kit.db (kitDb.ts).
+ * The selection keeps the omp harness opt-in. A missing or unreadable store is
+ * represented by undefined so callers resolve it to LEGACY_SELECTION.
  */
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 
-import { p } from "./exec";
+import { inTransaction, isNonBlankString, nonBlankOrNull, withKitDb } from "./kitDb";
 import type { OmpSessionModel } from "./sharedTypes";
 
 export type Harness = "claude" | "codex" | "agents" | "omp";
@@ -41,49 +39,21 @@ export function engineHome(env: NodeJS.ProcessEnv = process.env): string {
   return home !== undefined && home !== "" ? home : homedir();
 }
 
-export function harnessStateFile(home: string): string {
-  return p(home, ".docks-kit", "state.json");
-}
-
-// 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;
+/** Read the stored selection; corruption, a too-new schema, or I/O errors yield undefined. */
+export function readHarnessSelection(home: string): ReadonlyArray<Harness> | undefined {
   try {
-    parsed = JSON.parse(readFileSync(harnessStateFile(home), "utf8")) as unknown;
+    const selection = withKitDb(home, "read", (db) =>
+      normalizeHarnesses(
+        db
+          .prepare("SELECT harness FROM harness_selection")
+          .all()
+          .map((row) => row["harness"]),
+      ),
+    );
+    return selection !== undefined && selection.length > 0 ? selection : undefined;
   } catch {
     return undefined;
   }
-
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
-  const state = parsed as Record<string, unknown>;
-  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;
 }
 
 export function writeHarnessSelection(home: string, selection: ReadonlyArray<Harness>): void {
@@ -96,34 +66,37 @@ export function writeHarnessSelection(home: string, selection: ReadonlyArray<Har
     throw new Error("Harness selection must contain at least one known harness name");
   }
 
-  writeWholeState(home, { harnesses });
-}
-
-function isNonBlankString(value: unknown): value is string {
-  return typeof value === "string" && value.trim() !== "";
+  withKitDb(home, "write", (db) =>
+    inTransaction(db, () => {
+      db.exec("DELETE FROM harness_selection");
+      const insert = db.prepare("INSERT INTO harness_selection (harness) VALUES (?)");
+      for (const harness of harnesses) insert.run(harness);
+    }),
+  );
 }
 
-// Read the stored session model without throwing so a corrupt entry falls
+// Read the stored session model without throwing so a corrupt store 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"])) {
+  try {
+    return withKitDb(home, "read", (db) => {
+      const row = db
+        .prepare("SELECT selector, thinking, advisor_thinking FROM omp_session WHERE id = 1")
+        .get();
+      const selector = row?.["selector"];
+      if (!isNonBlankString(selector)) return undefined;
+      const thinking = row?.["thinking"];
+      const advisorThinking = row?.["advisor_thinking"];
+      const model: OmpSessionModel = {
+        selector,
+        ...(isNonBlankString(thinking) ? { thinking } : {}),
+        ...(isNonBlankString(advisorThinking) ? { advisorThinking } : {}),
+      };
+      return model;
+    });
+  } catch {
     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 thinking = record["thinking"];
-  const advisorThinking = record["advisorThinking"];
-  const model: OmpSessionModel = {
-    selector: record["selector"],
-    ...(isNonBlankString(thinking) ? { thinking } : {}),
-    ...(isNonBlankString(advisorThinking) ? { advisorThinking } : {}),
-  };
-  return model;
 }
 
 export function writeOmpSessionModel(home: string, model: OmpSessionModel): void {
@@ -132,15 +105,16 @@ export function writeOmpSessionModel(home: string, model: OmpSessionModel): void
   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 thinking = model.thinking;
-  const advisorThinking = model.advisorThinking;
-  const entry: OmpSessionModel = {
-    selector: model.selector,
-    ...(isNonBlankString(thinking) ? { thinking } : {}),
-    ...(isNonBlankString(advisorThinking) ? { advisorThinking } : {}),
-  };
-
-  writeWholeState(home, { ompSession: entry });
+  // Store blank or absent levels as NULL so a switch to a level-free model
+  // leaves no stale level behind.
+  const thinking = nonBlankOrNull(model.thinking);
+  const advisorThinking = nonBlankOrNull(model.advisorThinking);
+  withKitDb(home, "write", (db) =>
+    db
+      .prepare(
+        `INSERT INTO omp_session (id, selector, thinking, advisor_thinking) VALUES (1, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET selector = excluded.selector, thinking = excluded.thinking, advisor_thinking = excluded.advisor_thinking`,
+      )
+      .run(model.selector, thinking, advisorThinking),
+  );
 }

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

@@ -48,7 +48,7 @@ export async function runEngineNative(
     ctx = makeCtx(runServices);
     switch (argv[0]) {
       case "model":
-        return modeModel(ctx, argv.slice(1));
+        return await modeModel(ctx, argv.slice(1));
       case "toolchain":
         return await modeToolchain(ctx, argv.slice(1));
       case "sync":