docks-kit 0.20.5 → 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 +19 -17
  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 +61 -31
  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 +39 -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
@@ -20,6 +20,7 @@ against.
20
20
  | `fable` | `anthropic/claude-fable-5-1` | medium | 49 | $2.98 | 8.00 s |
21
21
  | `switch_fable` | `anthropic/claude-fable-5-1` | medium | 49 | $2.98 | 8.00 s |
22
22
  | `astra` | `openai-codex/gpt-6-astra` | xhigh | 52 | $2.31 | 126.90 s |
23
+ | `reviewer` | `openai-codex/gpt-6.1-sol` | xhigh | 51 | $0.39 | 68.65 s |
23
24
  | `web` | `web/firecrawl` | n/a | n/a | n/a | n/a |
24
25
 
25
26
  The table reports the measured Artificial Analysis figures for each assigned
@@ -75,16 +76,20 @@ What omp's settings catalog establishes about these roles:
75
76
  - `tiny` overrides the model for lightweight background tasks: titles, memory,
76
77
  auto-thinking, and unexpected-stop detection.
77
78
  - `modelTags` carries role metadata and can introduce roles; `hidden: true`
78
- keeps `switch_fable` out of the switcher list.
79
+ keeps `switch_fable` and `reviewer` out of the switcher list.
79
80
 
81
+ `modelRoles.reviewer` is a kit-defined role, not an omp built-in. It runs
82
+ `openai-codex/gpt-6.1-sol:xhigh`. omp resolves `@<name>` for any key in
83
+ `modelRoles` (`getModelRoleAlias` in omp's `model-resolver.ts`, omp 18.8.5).
80
84
  `task.agentModelOverrides` maps `reviewer`, `security-reviewer`,
81
- `code-reviewer`, and `plan-reviewer` to `@task`. Only the bundled `reviewer`
82
- and `security-reviewer` exist as OMP agents (omp's task tool lists `scout`,
83
- `reviewer`, `security-reviewer`, `task`, and `sonic`), so those two inherit
84
- whatever `task` resolves to. The `code-reviewer` and `plan-reviewer` entries
85
- are dormant until an OMP agent with that name exists.
86
- `retry.fallbackChains.task` holds `openai-codex/gpt-6.1-sol:high` as a
87
- cross-vendor fallback.
85
+ `code-reviewer`, and `plan-reviewer` to `@reviewer`, so one key sets the
86
+ model for every reviewer. Only the bundled `reviewer` and `security-reviewer`
87
+ exist as OMP agents (omp's task tool lists `scout`, `reviewer`,
88
+ `security-reviewer`, `task`, and `sonic`). The `code-reviewer` and
89
+ `plan-reviewer` entries are dormant until an OMP agent with that name exists.
90
+ `retry.fallbackChains.reviewer` holds `anthropic/claude-opus-5-5:xhigh`, and
91
+ `retry.fallbackChains.task` holds `openai-codex/gpt-6.1-sol:high`; both are
92
+ cross-vendor fallbacks.
88
93
 
89
94
  `retry.fallbackChains.astra` holds `anthropic/claude-fable-5-1:medium`.
90
95
  `retry.fallbackChains.fable` holds `openai-codex/gpt-6-astra:xhigh`.
@@ -395,11 +400,12 @@ quick answer.
395
400
  gave `max`: on 2026-10-09, `task` spawns with `effort: hi` ran GPT-6.1 Sol
396
401
  at `max` despite the `:high` role suffix. `scout` and `sonic` run GPT-6 Luna
397
402
  `medium` by default and GPT-6 Luna `xhigh` with `effort: hi`.
398
- - The bundled `reviewer` and `security-reviewer` inherit `@task`, now
399
- Opus 5.5 high.
403
+ - The bundled `reviewer` and `security-reviewer` resolve `@reviewer`, which is
404
+ GPT-6.1 Sol xhigh. A caller `effort` still outranks the `:xhigh` suffix:
405
+ `med` gives `high`, and `hi` gives `xhigh` under the `task.maxEffort` cap.
400
406
  - The `code-reviewer` and `plan-reviewer` override entries remain dormant.
401
- Both point to `@task`, now Opus 5.5 high. omp's task tool rejects both
402
- names as unknown agents, so neither can spawn.
407
+ Both point to `@reviewer`. omp's task tool rejects both names as unknown
408
+ agents, so neither can spawn.
403
409
 
404
410
  The runtime per-agent measurement from fresh `omp -p` runs on 2026-09-09
405
411
  predates this change. It applies to the retired Astra-low `task` configuration,
@@ -413,21 +419,31 @@ AA's 1M.
413
419
 
414
420
  `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive
415
421
  omp session with a configuration overlay that selects a free model. The
416
- overlay sets all 13 model roles to that model and empties all 10 retry fallback
417
- 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.
418
433
  The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
419
434
  a model that publishes no thinking ladder, where both keys are omitted and the
420
435
  deployed values apply.
421
436
 
422
437
  The launcher renders a run overlay to
423
438
  `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
424
- through omp's repeatable `--config` flag. Each model gets its own file,
425
- because omp can re-read the overlay during a live session, and a second
426
- launcher on another model must not rewrite that file. The name sanitizes the
427
- selector for the file system and appends a digest of the exact selector, so
428
- two selectors that differ only in separator characters stay apart. A session
429
- launch never reads or writes `~/.omp/agent/config.yml` or `models.yml`; only
430
- `--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
431
447
  never touches the SoT. The next plain `omp` run uses the paid configuration
432
448
  again.
433
449
 
@@ -480,11 +496,15 @@ committed. `--model <selector>` records one selector and derives both levels
480
496
  from the catalog row. `--pick` opens an interactive wizard.
481
497
 
482
498
  The picker lists only models the live `omp models --json` catalog reports at
483
- zero input and output cost (26 entries on 2026-09-11). The resulting overlay
484
- 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.
485
505
  Higher-precedence model selection can replace those values. The catalog can
486
- advertise a free model that the account cannot call; omp reports that provider
487
- error unchanged.
506
+ advertise a free model that the account cannot call; omp reports that
507
+ provider error unchanged.
488
508
 
489
509
  After the model, the wizard asks about thinking levels. `ompOverlay.ts
490
510
  planEffortChoice` decides which questions apply, because omp accepts a
@@ -506,14 +526,24 @@ recommendation equal to the chosen level is omitted rather than duplicated.
506
526
  A session whose advisor differs from the other roles reports both on the
507
527
  launch line.
508
528
 
509
- An omp login is required. The kit owns no login flow. It surfaces omp's own
510
- 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.
511
540
 
512
541
  When the catalog renames the free variant, change only the default selector
513
- constant. A ladder change needs no code change. Under `--model` both levels
514
- are derived from the catalog row of the chosen model, and under `--pick` the
515
- user chooses them from the ladder that same row publishes. Refresh the
516
- 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.
517
547
 
518
548
  ## OpenAI fast mode (`docks-kit omp --fast`)
519
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
  );