docks-kit 0.18.1 → 0.19.1

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 |
@@ -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,13 +47,13 @@ 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
-docks-kit docs [topic]                          self-documentation (10 topics)
+docks-kit docs [topic]                          self-documentation (11 topics)
 --help --version --wizard --completions    built-in
 ```
 
@@ -91,16 +91,17 @@ 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 Claude and Codex aliases, notes, and the
+  offline fallback. omp has no curated fallback list.
 - **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 +116,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

@@ -418,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/overview.md

@@ -13,7 +13,7 @@ AI-assisted dev environment on every machine.
 | `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
 | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
 | `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom |
-| `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
+| `SoT/models.json` | Curated Claude and Codex aliases, notes, and offline fallback for the live model lists (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 and the `docks-kit omp` session overlay |

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/docs.ts

@@ -24,8 +24,14 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
     summary: "Deploy-time modifiers and the flag-less-sync-reverts contract",
     body: modifiers,
   },
-  models: { summary: "Model catalog, validation rules, model get/set", body: models },
-  toolchain: { summary: "Verified-version floors and the doctor table", body: toolchain },
+  models: {
+    summary: "Live model lists, the curated overlay, validation, model get/set",
+    body: models,
+  },
+  toolchain: {
+    summary: "Verified-version floors, the doctor table, and the upstream outdated report",
+    body: toolchain,
+  },
   plugins: { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
   install: {
     summary: "Install paths: repo checkout, bun add -g, POSIX/Windows installers",

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,46 @@ 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"] : [];
+      const operand = Option.getOrUndefined(config.tool);
+      const words = operand === undefined ? [] : [operand];
 
-    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", ...words, ...flags]);
+        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",
+            ...words,
+            ...(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/commands/update.ts

@@ -60,9 +60,8 @@ const capturePackageRoot: CapturePackageRoot = (command, args) => {
 
 /**
  * A Bun global home is `<root>/.bun/install/global/node_modules/<pkg>`. Windows
- * reports that path with backslashes, so containment is tested on a normalized
- * copy — but only on Windows, because a backslash is a legal POSIX filename
- * character and must never be read as a separator there.
+ * reports that path with backslashes and compares it without case sensitivity.
+ * On POSIX, a backslash remains a legal filename character, not a separator.
  */
 export const packageManagerForHome = (
   home: string,
@@ -70,13 +69,14 @@ export const packageManagerForHome = (
   host: HostOs = hostOs(),
 ): PackageManager => {
   const normalize = (value: string): string =>
-    host.id === "windows" ? value.replaceAll("\\", "/") : value;
+    host.id === "windows" ? value.replaceAll("\\", "/").toLowerCase() : value;
   const normalizedHome = normalize(home);
   const underEnvironmentRoot = (name: "BUN_INSTALL_GLOBAL_DIR" | "BUN_INSTALL"): boolean => {
     const root = environment[name]?.trim();
     if (root === undefined || root === "") return false;
-    const normalizedRoot = normalize(root);
-    return normalizedHome === normalizedRoot || normalizedHome.startsWith(`${normalizedRoot}/`);
+    const normalizedRoot = normalize(root).replace(/\/+$/, "") || "/";
+    const prefix = normalizedRoot.endsWith("/") ? normalizedRoot : `${normalizedRoot}/`;
+    return normalizedHome === normalizedRoot || normalizedHome.startsWith(prefix);
   };
   return normalizedHome.includes("/.bun/") ||
     underEnvironmentRoot("BUN_INSTALL_GLOBAL_DIR") ||

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

@@ -19,6 +19,9 @@ import {
 import { payloadText } from "../payload";
 import type { JsonObject } from "./sharedTypes";
 
+/** Claude Code's built-in marketplace: always present, never added or pruned by the kit. */
+const OFFICIAL_MARKETPLACE = "claude-plugins-official";
+
 export async function cli(
   args: Array<string>,
 ): Promise<{ ok: boolean; out: string; detail: string }> {
@@ -113,20 +116,31 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     ? repoObj["extraKnownMarketplaces"]
     : {};
   const sotPlugins = isObject(repoObj["enabledPlugins"]) ? repoObj["enabledPlugins"] : {};
-
-  // Pass 1 — add missing marketplaces (SoT insertion order, like to_entries).
-  let addedMp = 0;
-  let f1 = 0;
-  for (const [mpName, mpValue] of Object.entries(sotMarketplaces)) {
+  const knownMarketplace = (mpName: string): boolean => {
     const known = readJsonFile(knownMarketplaces);
-    if (
+    return (
       known !== undefined &&
       isObject(known) &&
       known[mpName] !== undefined &&
       known[mpName] !== null &&
       known[mpName] !== false
-    )
-      continue;
+    );
+  };
+  const addedMarketplaces = new Set<string>();
+  // The official marketplace is built in; a successful add is usable before its inventory is written.
+  // A missing inventory proves absence (fresh home); an unreadable one does not, so refresh as before.
+  const marketplaceReady = (mpName: string): boolean => {
+    if (mpName === OFFICIAL_MARKETPLACE || addedMarketplaces.has(mpName)) return true;
+    if (!existsSync(knownMarketplaces)) return false;
+    const known = readJsonFile(knownMarketplaces);
+    return known === undefined || !isObject(known) || knownMarketplace(mpName);
+  };
+
+  // Pass 1 — add missing marketplaces (SoT insertion order, like to_entries).
+  let addedMp = 0;
+  let f1 = 0;
+  for (const [mpName, mpValue] of Object.entries(sotMarketplaces)) {
+    if (knownMarketplace(mpName)) continue;
     const repo =
       isObject(mpValue) && isObject(mpValue["source"])
         ? String((mpValue["source"] as JsonObject)["repo"] ?? "")
@@ -136,6 +150,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     clearProgress();
     if (marketplaceResult.ok) {
       addedMp++;
+      addedMarketplaces.add(mpName);
     } else {
       recordFailure(
         ctx,
@@ -156,7 +171,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (pluginUserScopeInstalled(installedPlugins, pluginId)) continue;
     const separator = pluginId.lastIndexOf("@");
     const mpName = separator > 0 ? pluginId.slice(separator + 1) : "";
-    if (mpName !== "" && !refreshedMarketplaces.has(mpName)) {
+    if (mpName !== "" && marketplaceReady(mpName) && !refreshedMarketplaces.has(mpName)) {
       progress(`Refreshing marketplace ${mpName}...`);
       const refreshResult = await cli(["plugin", "marketplace", "update", mpName]);
       clearProgress();
@@ -207,7 +222,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   // would duplicate one failure in the ledger and in the failed-operation count.
   if (!ctx.skipPluginRefresh) {
     for (const mpName of [...kitMarketplaces].sort(compareCodepoints)) {
-      if (refreshedMarketplaces.has(mpName)) continue;
+      if (refreshedMarketplaces.has(mpName) || !marketplaceReady(mpName)) continue;
       progress(`Refreshing marketplace ${mpName}...`);
       const refreshResult = await cli(["plugin", "marketplace", "update", mpName]);
       clearProgress();
@@ -263,7 +278,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     // Pass 6 — prune-gated marketplace removal.
     const known = readJsonFile(knownMarketplaces);
     for (const mpName of sortedKeys(known)) {
-      if (mpName === "claude-plugins-official") continue;
+      if (mpName === OFFICIAL_MARKETPLACE) continue;
       if (nonUserMarketplaces.has(mpName)) continue;
       if (kitMarketplaces.has(mpName)) continue;
       progress(`Removing marketplace ${mpName}...`);

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

@@ -7,7 +7,7 @@
 import { copyFileSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 
 import { payloadDisplayPath } from "../payload";
-import { mergeTableSettings, mergeTopLevelSettings } from "./codexToml";
+import { isTomlHeaderLine, mergeTableSettings, mergeTopLevelSettings } from "./codexToml";
 import type { Ctx } from "./index";
 
 // --------------------------------------------------------------- config ----
@@ -68,14 +68,14 @@ function scrubDeprecatedFeaturesText(content: string): string {
   let changed = false;
   for (const line of lines) {
     if (inFeatures) {
-      if (line.startsWith("[")) {
+      if (isTomlHeaderLine(line)) {
         inFeatures = false;
         if (keep) out += `${header}\n${body}`;
         else changed = true;
         out += `${line}\n`;
         continue;
       }
-      if (/^use_legacy_landlock[ \t]*=/.test(line)) {
+      if (/^[ \t]*use_legacy_landlock[ \t]*=/.test(line)) {
         changed = true;
         continue;
       }
@@ -83,7 +83,7 @@ function scrubDeprecatedFeaturesText(content: string): string {
       if (/[^ \t\f\v\r]/.test(line)) keep = true;
       continue;
     }
-    if (/^\[features\][ \t]*$/.test(line)) {
+    if (/^[ \t]*\[features\][ \t]*$/.test(line)) {
       inFeatures = true;
       header = line;
       body = "";
@@ -111,7 +111,7 @@ function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
   change("Codex: scrubbed deprecated [features].use_legacy_landlock");
 }
 
-export const PLUGIN_TABLE_HEADER = /^\[plugins\."([^"]+)"\][ \t]*$/;
+export const PLUGIN_TABLE_HEADER = /^[ \t]*\[plugins\."([^"]+)"\][ \t]*$/;
 /** Plugin ids the kit retired; their deployed tables are stripped on every sync. */
 const RETIRED_PLUGIN_IDS: Readonly<Record<string, true>> = {
   "effect-kit@docks": true,
@@ -130,7 +130,7 @@ export function removeRetiredPluginTablesText(content: string): string {
       skipping = RETIRED_PLUGIN_IDS[header[1]!] === true;
       if (skipping) continue;
     } else if (skipping) {
-      if (!line.startsWith("[")) continue;
+      if (!isTomlHeaderLine(line)) continue;
       skipping = false;
     }
     out += `${line}\n`;