docks-kit 0.20.6 → 0.20.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/AGENTS.md +18 -16
  2. package/README.md +17 -6
  3. package/cli/docs/command-guards.md +269 -0
  4. package/cli/docs/install.md +23 -12
  5. package/cli/docs/models.md +3 -2
  6. package/cli/docs/modifiers.md +4 -3
  7. package/cli/docs/omp-context.md +9 -2
  8. package/cli/docs/omp-models.md +43 -19
  9. package/cli/docs/plugins.md +12 -7
  10. package/cli/docs/sync-layers.md +26 -9
  11. package/cli/docs/toolchain.md +7 -4
  12. package/cli/src/argv.ts +2 -0
  13. package/cli/src/argvSurface.ts +23 -0
  14. package/cli/src/argvValidate.ts +3 -3
  15. package/cli/src/commands/docs.ts +6 -1
  16. package/cli/src/commands/harnesses.ts +15 -4
  17. package/cli/src/commands/omp.ts +92 -41
  18. package/cli/src/commands/status.ts +15 -0
  19. package/cli/src/commands/sync.ts +6 -6
  20. package/cli/src/commands/toolchain.ts +8 -2
  21. package/cli/src/commands/update.ts +51 -10
  22. package/cli/src/engine-native/DESIGN.md +56 -35
  23. package/cli/src/engine-native/atomicWrite.ts +64 -0
  24. package/cli/src/engine-native/claudeLsp.ts +9 -2
  25. package/cli/src/engine-native/claudeOptionalPlugins.ts +19 -6
  26. package/cli/src/engine-native/claudePluginPasses.ts +77 -21
  27. package/cli/src/engine-native/claudeRemovals.ts +245 -57
  28. package/cli/src/engine-native/claudeRetired.ts +1 -1
  29. package/cli/src/engine-native/claudeSettings.ts +46 -19
  30. package/cli/src/engine-native/claudeSettingsModifiers.ts +3 -3
  31. package/cli/src/engine-native/claudeSync.ts +18 -16
  32. package/cli/src/engine-native/codexConfig.ts +72 -12
  33. package/cli/src/engine-native/codexHooks.ts +3 -3
  34. package/cli/src/engine-native/codexPaths.ts +14 -0
  35. package/cli/src/engine-native/codexPlugins.ts +48 -23
  36. package/cli/src/engine-native/codexStatus.ts +2 -1
  37. package/cli/src/engine-native/codexSync.ts +33 -7
  38. package/cli/src/engine-native/codexToml.ts +161 -35
  39. package/cli/src/engine-native/deps.ts +4 -9
  40. package/cli/src/engine-native/engineCtx.ts +42 -14
  41. package/cli/src/engine-native/exec.ts +28 -1
  42. package/cli/src/engine-native/harnesses.ts +32 -8
  43. package/cli/src/engine-native/index.ts +6 -1
  44. package/cli/src/engine-native/kitDb.ts +12 -6
  45. package/cli/src/engine-native/liveModels.ts +2 -1
  46. package/cli/src/engine-native/models.ts +6 -3
  47. package/cli/src/engine-native/modes.ts +15 -10
  48. package/cli/src/engine-native/ompFileDeploy.ts +3 -4
  49. package/cli/src/engine-native/ompMarketplace.ts +9 -7
  50. package/cli/src/engine-native/ompOverlay.ts +37 -13
  51. package/cli/src/engine-native/ompPaths.ts +20 -9
  52. package/cli/src/engine-native/ompPlugins.ts +16 -15
  53. package/cli/src/engine-native/ompSync.ts +11 -6
  54. package/cli/src/engine-native/ompYaml.ts +91 -6
  55. package/cli/src/engine-native/os/darwin.ts +2 -0
  56. package/cli/src/engine-native/os/linux.ts +1 -0
  57. package/cli/src/engine-native/os/posix.ts +17 -5
  58. package/cli/src/engine-native/os/types.ts +2 -2
  59. package/cli/src/engine-native/os/windows.ts +24 -16
  60. package/cli/src/engine-native/skillsInstall.ts +10 -5
  61. package/cli/src/engine-native/skillsLinks.ts +14 -1
  62. package/cli/src/engine-native/skillsManifest.ts +20 -0
  63. package/cli/src/engine-native/skillsPrune.ts +33 -26
  64. package/cli/src/engine-native/skillsSync.ts +6 -3
  65. package/cli/src/engine-native/syncDispatch.ts +32 -18
  66. package/cli/src/engine.ts +29 -3
  67. package/cli/src/generated/sotPayload.ts +14 -14
  68. package/cli/src/main.ts +10 -3
  69. package/cli/src/manifests.ts +29 -11
  70. package/docks-kit +6 -3
  71. package/docks-kit.ps1 +22 -11
  72. package/package.json +1 -1
@@ -419,21 +419,31 @@ AA's 1M.
419
419
 
420
420
  `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive
421
421
  omp session with a configuration overlay that selects a free model. The
422
- overlay sets all 14 model roles to that model and empties all 11 retry fallback
423
- chains. Higher-precedence model selection can replace those values.
422
+ overlay sets the 16 chat-model roles in `ompOverlay.ts ROLE_ORDER` to that
423
+ model and empties the 13 retry fallback chains in `ompOverlay.ts
424
+ FALLBACK_ORDER`. These roles include `memory` and `judge`. The SoT does
425
+ not set them, but omp otherwise uses its built-in priority chain for them,
426
+ and that chain can name a paid model. The overlay does not set the `web` role
427
+ or its retry chain. The deployed web-search provider order therefore applies,
428
+ and that order includes the paid `openai-codex/gpt-6-luna` entry. omp merges
429
+ the overlay key by key. Each other deployed retry chain, such as a `plan`,
430
+ `slow`, or `designer` chain, therefore stays as deployed. Such a chain can name
431
+ a paid model. Higher-precedence model selection can replace the overlay
432
+ values.
424
433
  The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
425
434
  a model that publishes no thinking ladder, where both keys are omitted and the
426
435
  deployed values apply.
427
436
 
428
437
  The launcher renders a run overlay to
429
438
  `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
430
- through omp's repeatable `--config` flag. Each model gets its own file,
431
- because omp can re-read the overlay during a live session, and a second
432
- launcher on another model must not rewrite that file. The name sanitizes the
433
- selector for the file system and appends a digest of the exact selector, so
434
- two selectors that differ only in separator characters stay apart. A session
435
- launch never reads or writes `~/.omp/agent/config.yml` or `models.yml`; only
436
- `--fast`, below, edits `config.yml`. It
439
+ through omp's repeatable `--config` flag. Each distinct model-and-level
440
+ combination gets its own file, because omp re-reads a changed overlay during
441
+ a live session, and a second launcher must not change the levels of that
442
+ session. The name sanitizes the selector for the file system and appends a
443
+ digest of the rendered overlay. The digest covers the selector and both
444
+ levels, so two selectors that differ only in separator characters stay
445
+ apart. A session launch never reads or writes `~/.omp/agent/config.yml` or
446
+ `models.yml`; only `--fast`, below, edits `config.yml`. It
437
447
  never touches the SoT. The next plain `omp` run uses the paid configuration
438
448
  again.
439
449
 
@@ -486,11 +496,15 @@ committed. `--model <selector>` records one selector and derives both levels
486
496
  from the catalog row. `--pick` opens an interactive wizard.
487
497
 
488
498
  The picker lists only models the live `omp models --json` catalog reports at
489
- zero input and output cost (26 entries on 2026-09-11). The resulting overlay
490
- sets every role to the chosen free model and empties every retry chain.
499
+ zero input and output cost with `pricingStatus` `free` or `unknown` (26
500
+ entries on 2026-09-11). A zero-cost row with another status, such as
501
+ `variable` or `included`, is billed outside the token price, so the picker
502
+ leaves it out. The resulting overlay sets the 16 `ROLE_ORDER` roles to the
503
+ chosen free model and empties the 13 `FALLBACK_ORDER` chains. The `web` role,
504
+ its chain, and each other deployed chain keep the deployed values.
491
505
  Higher-precedence model selection can replace those values. The catalog can
492
- advertise a free model that the account cannot call; omp reports that provider
493
- error unchanged.
506
+ advertise a free model that the account cannot call; omp reports that
507
+ provider error unchanged.
494
508
 
495
509
  After the model, the wizard asks about thinking levels. `ompOverlay.ts
496
510
  planEffortChoice` decides which questions apply, because omp accepts a
@@ -512,14 +526,24 @@ recommendation equal to the chosen level is omitted rather than duplicated.
512
526
  A session whose advisor differs from the other roles reports both on the
513
527
  launch line.
514
528
 
515
- An omp login is required. The kit owns no login flow. It surfaces omp's own
516
- authentication error unchanged.
529
+ An omp login is required. The kit owns no login flow. Every launch reads the
530
+ live free catalog once. A plain launch checks the remembered model, or the
531
+ default model, against that catalog. When the model is not there, the
532
+ launcher stops before omp starts. The model can be renamed, repriced, or on a
533
+ provider that is not logged in. Without this check, omp silently starts the
534
+ default model of the first logged-in provider, which can be paid. When the
535
+ forwarded arguments include `--profile <name>` or `--profile=<name>`, the
536
+ catalog check queries that same omp profile with
537
+ `omp --profile <name> models --json`. As in omp, the last such flag before a
538
+ `--` wins, and a `--profile` without a name stops the launcher before omp
539
+ starts.
517
540
 
518
541
  When the catalog renames the free variant, change only the default selector
519
- constant. A ladder change needs no code change. Under `--model` both levels
520
- are derived from the catalog row of the chosen model, and under `--pick` the
521
- user chooses them from the ladder that same row publishes. Refresh the
522
- recorded default and the ladder counts in these docs in the same commit.
542
+ constant. Until then, a plain launch on that default stops with an error. A
543
+ ladder change needs no code change. Under `--model` both levels are derived
544
+ from the catalog row of the chosen model, and under `--pick` the user chooses
545
+ them from the ladder that same row publishes. Refresh the recorded default
546
+ and the ladder counts in these docs in the same commit.
523
547
 
524
548
  ## OpenAI fast mode (`docks-kit omp --fast`)
525
549
 
@@ -14,7 +14,8 @@ is absent from user settings.
14
14
 
15
15
  ## Sync passes (idempotent, via the `claude plugin` CLI)
16
16
 
17
- 1. Add SoT marketplaces not yet known
17
+ 1. Add SoT marketplaces not yet known, plus `anthropics/claude-plugins-official`
18
+ when a kit plugin needs it and Claude Code has not registered it yet
18
19
  2. Install SoT-declared plugins missing at user scope, refreshing each
19
20
  plugin's source marketplace once first
20
21
  3. Refresh the remaining kit-owned marketplaces (skipped by
@@ -22,22 +23,26 @@ is absent from user settings.
22
23
  4. Update the kit-owned installed plugins (skipped by `--skip-plugin-refresh`)
23
24
  5. (`--prune` only) uninstall user-scope plugins that are neither
24
25
  SoT-declared nor opted in on this run
25
- 6. (`--prune` only) remove marketplaces no kit-owned plugin needs (built-in
26
- `claude-plugins-official` and marketplaces behind project- or local-scope
26
+ 6. (`--prune` only) remove marketplaces no kit-owned plugin needs
27
+ (`claude-plugins-official` and marketplaces behind project- or local-scope
27
28
  installs are never removed)
28
29
  7. Re-assert SoT enabled-state (undoes install's enable side effect on
29
30
  false-keyed plugins)
30
31
 
32
+ Every `claude plugin` command runs from the system temp directory, so a sync
33
+ started inside a project never edits that project's `.claude` settings.
34
+
31
35
  ## Failed operations fail the sync
32
36
 
33
37
  A marketplace or plugin command that exits non-zero is warned in place AND
34
38
  recorded, then listed under a `--- Failures ---` block after the summary; the
35
39
  sync exits 1. A stale plugin therefore no longer looks like a clean sync.
36
40
 
37
- Not a failure: a missing harness CLI, missing git, a missing
38
- `SoT/toolchain.json` pin, and an unavailable plugin inventory. Those stay
39
- warn-and-skip with exit 0, so a host without Claude, Codex, or omp installed
40
- still syncs its deployed config cleanly.
41
+ Not a failure: a missing harness CLI, missing git, and a missing
42
+ `SoT/toolchain.json` pin. Those stay warn-and-skip with exit 0, so a host
43
+ without Claude, Codex, or omp installed still syncs its deployed config
44
+ cleanly. An unavailable plugin inventory warns without a ledger row and falls
45
+ back to the full refresh, whose failed commands are recorded.
41
46
 
42
47
  ## Optional opt-ins
43
48
 
@@ -35,13 +35,20 @@ Order matters — runtime readiness and settings form one transaction:
35
35
  The statusline reads Claude's native `rate_limits`. There is no OAuth request,
36
36
  usage cache, jq/curl runtime dependency, or Stop fetch hook.
37
37
 
38
- ## codex (→ ~/.codex, ~/.agents/plugins)
38
+ ## codex (→ Codex home, ~/.agents/plugins)
39
39
 
40
- bubblewrap check (Linux), config.toml merge (top-level keys replaced
41
- per-key, [table] blocks replaced wholesale, user-only keys/tables preserved,
42
- and retired kit-owned `[plugins."<id>"]` tables stripped), `--codex-model`
43
- then `--codex-effort` modifiers, rules, AGENTS.md, personal marketplace file,
44
- and `codex plugin add` refresh.
40
+ bubblewrap bootstrap (Linux): when `bwrap` is missing, sync runs
41
+ `sudo apt-get|dnf|pacman|zypper install bubblewrap` (a sudo prompt may appear)
42
+ and then probes unprivileged user namespaces; `--skip-bubblewrap` only warns,
43
+ and `--dry-run` only prints the step. Then config.toml merge (top-level keys
44
+ replaced per-key, [table] blocks replaced wholesale, user-only keys/tables
45
+ preserved, and retired kit-owned `[plugins."<id>"]` tables stripped),
46
+ `--codex-model` then `--codex-effort` modifiers, rules, AGENTS.md, personal
47
+ marketplace file, and `codex plugin add` refresh.
48
+
49
+ The Codex home is `$CODEX_HOME` when that variable is set and not empty, else
50
+ `~/.codex`. Like Codex, the kit resolves a relative `CODEX_HOME` against the
51
+ current directory. Every kit read or write of Codex state uses this directory.
45
52
 
46
53
  ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
47
54
 
@@ -50,9 +57,19 @@ kit-managed snapshot that `--prune` reconciles against.
50
57
 
51
58
  ## omp (→ resolved agent dir, intercom root)
52
59
 
53
- AGENTS.md, mcp.json, and intercom config.json are whole-file deploys;
54
- config.yml is deep-merged (SoT keys win, mapping nodes merge, deployed-only
55
- keys survive, stale slash-bearing `retry.fallbackChains` wildcards pruned).
60
+ AGENTS.md, mcp.json, and intercom config.json are whole-file deploys.
61
+ config.yml and models.yml are deep-merged (SoT keys win, mapping nodes merge,
62
+ deployed-only keys survive; config.yml also drops stale slash-bearing
63
+ `retry.fallbackChains` wildcards). A SoT list replaces the deployed list, except
64
+ config.yml `bash.patterns`: the merge keeps user rules and groups all rules as
65
+ kit deny, user deny, user prompt, kit allow exceptions (the `-- *` forms), kit
66
+ prompt, other user rules, and kit allow, so no allow loosens a deny or a prompt (see
67
+ `docks-kit docs command-guards`). After each merge, every sync (no
68
+ `--reconcile` needed) force-prunes the `ompRemovals.ts` retired-key inventory:
69
+ config.yml keys whose deployed value still equals the value the kit used to
70
+ ship, `providers.webSearchOrder` at any value, and the retired
71
+ `anthropic.modelOverrides.claude-opus-5-5` block in models.yml while it still
72
+ matches the shipped block.
56
73
  Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
57
74
  registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
58
75
  through `omp plugin`, and `pi-intercom` is installed at its
@@ -22,7 +22,8 @@ Their generated Bun floor is intentionally separate from the generated `verified
22
22
  shared by the Claude runtime and direct `toolchain ensure bun` on every
23
23
  supported host. The POSIX modules download `install.sh` with curl and run it
24
24
  with Bash. The Windows module downloads `install.ps1` with curl and runs it
25
- through `powershell.exe`.
25
+ through `powershell.exe`. When Bun is already present, `toolchain ensure bun`
26
+ installs nothing and warns if that Bun is below the `floor`.
26
27
 
27
28
  jq and curl are `check` rows, not global prerequisites. jq is not consumed by
28
29
  normal sync. curl is checked only when a requested Bun bootstrap must download
@@ -50,14 +51,15 @@ the installed version and judges nothing.
50
51
 
51
52
  ## Language-server upgrades
52
53
 
53
- `claudeSync syncLspServers` installs `intelephense`, `typescript-language-server`,
54
+ `claudeLsp.ts syncLspServers` installs `intelephense`, `typescript-language-server`,
54
55
  `typescript`, and `rust-analyzer` only when the binary is missing. It never
55
56
  upgrades a server that is already present. A `verified` bump therefore reaches
56
57
  a fresh host immediately and leaves an existing install alone.
57
58
 
58
59
  The rustup channel follows the same rule. Sync adds the component only when the
59
- `rust-analyzer` binary is missing, and `rustup update` is the user's remedy for
60
- an old component.
60
+ `rust-analyzer` binary is missing or is a rustup proxy that cannot run because
61
+ the component is not installed. `rustup update` is the user's remedy for an old
62
+ component.
61
63
 
62
64
  A lagging server shows as `below-floor` in `docks-kit toolchain check`. To move
63
65
  the npm servers to their `verified` pins, run:
@@ -106,6 +108,7 @@ manifest's `verified` version.
106
108
  ```text
107
109
  docks-kit toolchain check # doctor table (also inside docks-kit status)
108
110
  docks-kit toolchain ensure bun # ensure the only managed tool
111
+ docks-kit toolchain ensure bun --dry-run # preview the Bun install
109
112
  docks-kit toolchain outdated [--refresh] # verified pins vs newest upstream release
110
113
  docks-kit toolchain upgrade [--dry-run] # npm LSP servers below verified -> verified
111
114
  ```
package/cli/src/argv.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { GlobalFlag } from "effect/unstable/cli";
2
2
  import { docsCommand } from "./commands/docs";
3
+ import { harnessesCommand } from "./commands/harnesses";
3
4
  import { modelCommand } from "./commands/model";
4
5
  import { modelsCommand } from "./commands/models";
5
6
  import { pluginsCommand } from "./commands/plugins";
@@ -26,6 +27,7 @@ export type ArgvOutcome =
26
27
 
27
28
  const COMMANDS: ReadonlyArray<CommandValue> = [
28
29
  syncCommand,
30
+ harnessesCommand,
29
31
  updateCommand,
30
32
  modelCommand,
31
33
  toolchainCommand,
@@ -235,6 +235,21 @@ export interface ScannedArgv {
235
235
  readonly normalizations: ReadonlyArray<ArgvNormalization>;
236
236
  }
237
237
 
238
+ // Mirrors effect Schema.TrueLiterals/FalseLiterals (case-sensitive): Effect 4 lets a
239
+ // Boolean flag consume the next token as its value when that token is one of these.
240
+ const EFFECT_BOOLEAN_LITERALS: Readonly<Record<string, true>> = {
241
+ true: true,
242
+ yes: true,
243
+ on: true,
244
+ "1": true,
245
+ y: true,
246
+ false: true,
247
+ no: true,
248
+ off: true,
249
+ "0": true,
250
+ n: true,
251
+ };
252
+
238
253
  export const scanArgv = (
239
254
  args: ReadonlyArray<string>,
240
255
  commandSurface: FlagSurface | undefined,
@@ -278,6 +293,14 @@ export const scanArgv = (
278
293
  }
279
294
  }
280
295
 
296
+ if (canonicalName !== undefined && !takesValue && !hasValue) {
297
+ const next = args[index + 1];
298
+ if (next !== undefined && Object.hasOwn(EFFECT_BOOLEAN_LITERALS, next)) {
299
+ hasValue = true;
300
+ index++;
301
+ }
302
+ }
303
+
281
304
  flags.push({ token, name, canonicalName, hasValue, takesValue });
282
305
  }
283
306
 
@@ -90,9 +90,9 @@ export const validateScannedArgv = (
90
90
  }
91
91
 
92
92
  for (const flag of flags) {
93
- if (!flag.token.includes("=") || flag.takesValue) continue;
94
- // These booleans are presence-based; Effect 4 would otherwise let
95
- // `--dry-run=false` read as a dry run while performing a real mutating sync.
93
+ if (!flag.hasValue || flag.takesValue) continue;
94
+ // These booleans are presence-based; Effect 4 would otherwise let `--dry-run=false`
95
+ // or `--dry-run false` read as no dry run while performing a real mutating sync.
96
96
  return `flag ${flag.name} does not take a value`;
97
97
  }
98
98
 
@@ -12,6 +12,7 @@ import install from "../../docs/install.md" with { type: "text" };
12
12
  import platforms from "../../docs/platforms.md" with { type: "text" };
13
13
  import ompModels from "../../docs/omp-models.md" with { type: "text" };
14
14
  import ompContext from "../../docs/omp-context.md" with { type: "text" };
15
+ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
15
16
 
16
17
  const TOPICS: Record<string, { summary: string; body: string }> = {
17
18
  overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
@@ -49,6 +50,10 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
49
50
  summary: "omp compaction trigger, the reserve-based default, and context-window lanes",
50
51
  body: ompContext,
51
52
  },
53
+ "command-guards": {
54
+ summary: "Deny, ask, and allow tiers for destructive shell commands in omp, Claude, and Codex",
55
+ body: commandGuards,
56
+ },
52
57
  };
53
58
 
54
59
  const topic = Argument.String("topic").pipe(
@@ -81,7 +86,7 @@ export const docsCommand = Command.make("docs", { topic, json }, (config) =>
81
86
  return;
82
87
  }
83
88
 
84
- const entry = TOPICS[requested];
89
+ const entry = Object.hasOwn(TOPICS, requested) ? TOPICS[requested] : undefined;
85
90
  if (entry === undefined) {
86
91
  return yield* bail(`Unknown topic '${requested}'. Valid: ${Object.keys(TOPICS).join(", ")}`);
87
92
  }
@@ -5,7 +5,7 @@ import {
5
5
  engineHome,
6
6
  HARNESSES,
7
7
  LEGACY_SELECTION,
8
- readHarnessSelection,
8
+ loadHarnessSelection,
9
9
  writeHarnessSelection,
10
10
  type Harness,
11
11
  } from "../engine-native/harnesses";
@@ -21,7 +21,11 @@ const DESCRIPTIONS: Record<Harness, string> = {
21
21
  export const harnessesCommand = Command.make("harnesses", {}, () =>
22
22
  Effect.gen(function* () {
23
23
  const home = engineHome(process.env);
24
- const stored = yield* Effect.sync(() => readHarnessSelection(home));
24
+ const loaded = yield* Effect.sync(() => loadHarnessSelection(home));
25
+ if (loaded.kind === "unreadable") {
26
+ return yield* bail(`Cannot read ${kitDbFile(home)}: ${loaded.reason}`, 1);
27
+ }
28
+ const stored = loaded.kind === "stored" ? loaded.selection : undefined;
25
29
  const selection = stored ?? LEGACY_SELECTION;
26
30
  const names = selection.join(", ");
27
31
 
@@ -33,7 +37,7 @@ export const harnessesCommand = Command.make("harnesses", {}, () =>
33
37
  yield* Console.log(`Harness selection: ${names}`);
34
38
  }
35
39
 
36
- if (!process.stdout.isTTY) return;
40
+ if (!process.stdin.isTTY || !process.stdout.isTTY) return;
37
41
 
38
42
  const answer = yield* Prompt.MultiSelect({
39
43
  message: "Choose the harnesses for a flag-less docks-kit sync",
@@ -52,7 +56,14 @@ export const harnessesCommand = Command.make("harnesses", {}, () =>
52
56
  return yield* bail("Select at least one harness. The stored selection was not changed.");
53
57
  }
54
58
 
55
- yield* Effect.sync(() => writeHarnessSelection(home, answer));
59
+ yield* Effect.try({
60
+ try: () => writeHarnessSelection(home, answer),
61
+ catch: (error) => (error instanceof Error ? error.message : String(error)),
62
+ }).pipe(
63
+ Effect.catch((reason) =>
64
+ bail(`Cannot save the harness selection to ${kitDbFile(home)}: ${reason}`, 1),
65
+ ),
66
+ );
56
67
  yield* Console.log(`Saved harness selection: ${answer.join(", ")} (${kitDbFile(home)})`);
57
68
  }),
58
69
  ).pipe(
@@ -78,12 +78,53 @@ export function resolveFreeSelector(
78
78
  };
79
79
  }
80
80
 
81
- const loadFreeCatalog = (omp: string): Effect.Effect<ReadonlyArray<CatalogModel>> =>
81
+ /**
82
+ * The omp profile that the forwarded arguments select. omp reads
83
+ * `--profile <name>` or `--profile=<name>` before a `--`, the last one wins,
84
+ * and it rejects a missing or empty name. The catalog check must query the
85
+ * profile the session runs, so it reads the arguments the same way.
86
+ */
87
+ export type ForwardedProfile =
88
+ | { readonly ok: true; readonly profile: string | undefined }
89
+ | { readonly ok: false; readonly message: string };
90
+
91
+ export function forwardedProfile(forwarded: ReadonlyArray<string>): ForwardedProfile {
92
+ let profile: string | undefined;
93
+ for (let index = 0; index < forwarded.length; index++) {
94
+ const arg = forwarded[index]!;
95
+ if (arg === "--") break;
96
+ let value: string | undefined;
97
+ if (arg === "--profile") {
98
+ value = forwarded[index + 1];
99
+ if (value === undefined || value.startsWith("-")) value = "";
100
+ else index++;
101
+ } else if (arg.startsWith("--profile=")) {
102
+ value = arg.slice("--profile=".length);
103
+ } else {
104
+ continue;
105
+ }
106
+ if (value === "") return { ok: false, message: "--profile requires a profile name" };
107
+ profile = value;
108
+ }
109
+ return { ok: true, profile };
110
+ }
111
+
112
+ const loadFreeCatalog = (
113
+ omp: string,
114
+ profile: string | undefined,
115
+ ): Effect.Effect<ReadonlyArray<CatalogModel>> =>
82
116
  Effect.gen(function* () {
83
- const raw = yield* Effect.promise(() => capture(omp, ["models", "--json"]));
117
+ // omp takes --profile only before its subcommand.
118
+ const catalogArgs = [
119
+ ...(profile === undefined ? [] : ["--profile", profile]),
120
+ "models",
121
+ "--json",
122
+ ];
123
+ const command = `omp ${catalogArgs.join(" ")}`;
124
+ const raw = yield* Effect.promise(() => capture(omp, catalogArgs));
84
125
  if (raw === "") {
85
126
  return yield* bail(
86
- "'omp models --json' returned no output; verify omp runs on this host, then retry",
127
+ `'${command}' returned no output; verify omp runs on this host, then retry`,
87
128
  );
88
129
  }
89
130
  let parsed: unknown;
@@ -91,14 +132,12 @@ const loadFreeCatalog = (omp: string): Effect.Effect<ReadonlyArray<CatalogModel>
91
132
  parsed = JSON.parse(raw) as unknown;
92
133
  } catch {
93
134
  return yield* bail(
94
- "'omp models --json' returned output that is not JSON; verify the omp version, then retry",
135
+ `'${command}' returned output that is not JSON; verify the omp version, then retry`,
95
136
  );
96
137
  }
97
138
  const free = parseFreeModels(parsed);
98
139
  if (free.length === 0) {
99
- return yield* bail(
100
- "'omp models --json' listed no free models; verify the omp login, then retry",
101
- );
140
+ return yield* bail(`'${command}' listed no free models; verify the omp login, then retry`);
102
141
  }
103
142
  return free;
104
143
  });
@@ -206,31 +245,33 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
206
245
  }
207
246
 
208
247
  const home = engineHome(process.env);
248
+ // Check the terminal before the catalog spawn, so a non-interactive run
249
+ // fails with the actionable message instead of an omp subprocess first.
250
+ if (config.pick && (!process.stdin.isTTY || !process.stdout.isTTY)) {
251
+ return yield* bail("Picking needs a terminal; pass --model <selector> instead");
252
+ }
253
+ // Every launch reads the live catalog once, because a remembered or
254
+ // default model can be renamed, repriced, or lose its provider login.
255
+ // omp then silently starts a paid default model instead. The catalog
256
+ // comes from the profile that the forwarded arguments select.
257
+ const profile = forwardedProfile(config.args);
258
+ if (!profile.ok) return yield* bail(profile.message);
259
+ const free = yield* loadFreeCatalog(omp, profile.profile);
260
+ // The value the launcher writes is the value it runs, so a concurrent
261
+ // launcher or a failed read of kit.db cannot change this session.
262
+ let chosen: OmpSessionModel | undefined;
209
263
  if (Option.isSome(config.model)) {
210
- const free = yield* loadFreeCatalog(omp);
211
264
  const resolved = resolveFreeSelector(config.model.value, free);
212
265
  if (!resolved.ok) return yield* bail(resolved.message);
213
- // Compute both levels once from the catalog row so a plain launch
214
- // never needs the catalog again.
215
- const thinking = ladderCeiling(resolved.model.thinking);
216
- const advisorThinking = advisorLevelFor(resolved.model.thinking);
217
- yield* Effect.sync(() =>
218
- writeOmpSessionModel(home, {
219
- selector: resolved.model.selector,
220
- thinking,
221
- advisorThinking,
222
- }),
223
- );
266
+ chosen = {
267
+ selector: resolved.model.selector,
268
+ thinking: ladderCeiling(resolved.model.thinking),
269
+ advisorThinking: advisorLevelFor(resolved.model.thinking),
270
+ };
224
271
  }
225
272
 
226
273
  if (config.pick) {
227
- // Check the terminal before the catalog spawn, so a non-interactive run
228
- // fails with the actionable message instead of an omp subprocess first.
229
- if (!process.stdin.isTTY || !process.stdout.isTTY) {
230
- return yield* bail("Picking needs a terminal; pass --model <selector> instead");
231
- }
232
- const free = yield* loadFreeCatalog(omp);
233
- const chosen = yield* Prompt.Select({
274
+ const pickedSelector = yield* Prompt.Select({
234
275
  message: "Choose the free model for this omp session",
235
276
  choices: free.map((candidate) => {
236
277
  const ceiling = ladderCeiling(candidate.thinking);
@@ -244,27 +285,37 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
244
285
  };
245
286
  }),
246
287
  });
247
- const match = free.find((candidate) => candidate.selector === chosen);
248
- if (match === undefined) return yield* bail(`Model '${chosen}' is not in the free catalog`);
288
+ const match = free.find((candidate) => candidate.selector === pickedSelector);
289
+ if (match === undefined) {
290
+ return yield* bail(`Model '${pickedSelector}' is not in the free catalog`);
291
+ }
249
292
  const chosenLevels = yield* pickLevels(match);
250
- yield* Effect.sync(() =>
251
- writeOmpSessionModel(home, {
252
- selector: match.selector,
253
- thinking: chosenLevels.thinking,
254
- advisorThinking: chosenLevels.advisorThinking,
255
- }),
256
- );
293
+ chosen = {
294
+ selector: match.selector,
295
+ thinking: chosenLevels.thinking,
296
+ advisorThinking: chosenLevels.advisorThinking,
297
+ };
298
+ }
299
+
300
+ if (chosen !== undefined) {
301
+ const remembered = chosen;
302
+ yield* Effect.sync(() => writeOmpSessionModel(home, remembered));
257
303
  }
258
304
 
259
305
  const session: OmpSessionModel =
260
- (yield* Effect.sync(() => readOmpSessionModel(home))) ?? DEFAULT_OMP_SESSION_MODEL;
306
+ chosen ?? (yield* Effect.sync(() => readOmpSessionModel(home))) ?? DEFAULT_OMP_SESSION_MODEL;
307
+ if (!free.some((candidate) => candidate.selector === session.selector)) {
308
+ return yield* bail(
309
+ `free model '${session.selector}' is not available in the omp catalog (renamed, repriced, or provider not logged in); log in to its provider or choose another with --model or --pick`,
310
+ );
311
+ }
261
312
 
262
313
  // A stable cache path, not a temp file deleted at exit, because omp may
263
- // re-read the overlay during a live session. The name carries the model,
264
- // so a second launcher on another model cannot rewrite the file a running
265
- // session still reads.
314
+ // re-read the overlay during a live session. The name carries a digest of
315
+ // the rendered overlay, so a second launcher on another model or level
316
+ // cannot rewrite the file a running session still reads.
266
317
  const directory = p(home, ".cache", "docks-kit");
267
- const overlayPath = p(directory, overlayFileName(session.selector));
318
+ const overlayPath = p(directory, overlayFileName(session));
268
319
  yield* Effect.sync(() => {
269
320
  // `mode` applies only when mkdir creates the path, so an existing
270
321
  // permissive cache directory keeps its mode until the chmod below.
@@ -305,6 +356,6 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
305
356
  }),
306
357
  ).pipe(
307
358
  Command.withDescription(
308
- "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). --fast instead toggles OpenAI/Codex fast mode in the deployed omp config and exits.",
359
+ "Start omp with every chat-model role set to the remembered free model for this run only. The web-search role keeps the deployed provider order, which can include a paid model. No deployed configuration changes; --model or --pick remembers a new free default. Every launch checks the model against the live free catalog. --fast instead toggles OpenAI/Codex fast mode in the deployed omp config and exits.",
309
360
  ),
310
361
  );
@@ -4,6 +4,7 @@ import { engineCapture, type EngineCaptureError } from "../engine";
4
4
  import {
5
5
  deployedClaudeSettings,
6
6
  deployedCodexModel,
7
+ installedPluginsState,
7
8
  pluginsView,
8
9
  skillsView,
9
10
  sotClaudeSettings,
@@ -28,6 +29,9 @@ type ClaudeDeployment =
28
29
  | { readonly state: "valid"; readonly settings: Record<string, unknown> }
29
30
  | { readonly state: "malformed"; readonly diagnostic: string };
30
31
 
32
+ const MALFORMED_PLUGINS_DIAGNOSTIC =
33
+ "installed Claude plugins file must contain a JSON object with an object 'plugins' field";
34
+
31
35
  const captureToolchainStatus = () =>
32
36
  engineCapture(["toolchain", "check"]).pipe(
33
37
  Effect.map((table) => ({ state: "valid" as const, table })),
@@ -112,6 +116,7 @@ export const statusCommand = Command.make("status", { json }, (config) =>
112
116
  Effect.gen(function* () {
113
117
  const { drift, claudeDeployment } = gatherDrift();
114
118
  const plugins = pluginsView();
119
+ const pluginsState = installedPluginsState();
115
120
  const skills = skillsView();
116
121
  const toolchain = yield* captureToolchainStatus();
117
122
  const diagnostics = new Array<{ source: string; message: string; exitCode: number }>();
@@ -122,6 +127,13 @@ export const statusCommand = Command.make("status", { json }, (config) =>
122
127
  exitCode: 1,
123
128
  });
124
129
  }
130
+ if (pluginsState === "malformed") {
131
+ diagnostics.push({
132
+ source: "claude.plugins",
133
+ message: MALFORMED_PLUGINS_DIAGNOSTIC,
134
+ exitCode: 1,
135
+ });
136
+ }
125
137
  if (toolchain.state === "failed") {
126
138
  diagnostics.push({
127
139
  source: "toolchain",
@@ -162,6 +174,9 @@ export const statusCommand = Command.make("status", { json }, (config) =>
162
174
  if (claudeDeployment.state === "malformed") {
163
175
  yield* Console.log(` ERROR claude.settings: ${claudeDeployment.diagnostic}`);
164
176
  }
177
+ if (pluginsState === "malformed") {
178
+ yield* Console.log(` ERROR claude.plugins: ${MALFORMED_PLUGINS_DIAGNOSTIC}`);
179
+ }
165
180
  yield* Console.log("\nToolchain:");
166
181
  if (toolchain.state === "failed") {
167
182
  yield* Console.log(` ERROR: ${toolchain.diagnostic}`);
@@ -165,15 +165,15 @@ export const syncCommand = Command.make(
165
165
  Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`));
166
166
  Option.map(config.codexEffort, (level) => args.push(`--codex-effort=${level}`));
167
167
  for (const occurrence of config.claudePlugin) {
168
- if (occurrence.trim() === "") {
168
+ const names = occurrence
169
+ .split(",")
170
+ .map((p) => p.trim())
171
+ .filter((p) => p.length > 0);
172
+ if (names.length === 0) {
169
173
  args.push("--claude-plugin=");
170
174
  continue;
171
175
  }
172
- occurrence
173
- .split(",")
174
- .map((p) => p.trim())
175
- .filter((p) => p.length > 0)
176
- .forEach((p) => args.push(`--claude-plugin=${p}`));
176
+ for (const name of names) args.push(`--claude-plugin=${name}`);
177
177
  }
178
178
 
179
179
  // Not on --dry-run: the nudge's git fetch writes FETCH_HEAD/remote
@@ -22,7 +22,7 @@ const refresh = Flag.Boolean("refresh").pipe(
22
22
  Flag.withDefault(false),
23
23
  );
24
24
  const dryRun = Flag.Boolean("dry-run").pipe(
25
- Flag.withDescription("upgrade: print the npm command without running it"),
25
+ Flag.withDescription("ensure/upgrade: preview without installing or running npm"),
26
26
  Flag.withDefault(false),
27
27
  );
28
28
 
@@ -44,7 +44,13 @@ export const toolchainCommand = Command.make(
44
44
  if (t === undefined || !MANAGED.includes(t)) {
45
45
  return yield* bail(`toolchain ensure needs a managed tool: ${MANAGED.join(", ")}`);
46
46
  }
47
- return yield* engine(["toolchain", "ensure", t, ...flags]);
47
+ return yield* engine([
48
+ "toolchain",
49
+ "ensure",
50
+ t,
51
+ ...flags,
52
+ ...(config.dryRun ? ["--dry-run"] : []),
53
+ ]);
48
54
  }
49
55
  case "outdated":
50
56
  return yield* engine([