docks-kit 0.21.0 → 0.21.1

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.
package/AGENTS.md CHANGED
@@ -32,8 +32,8 @@ launcher can fall back to Bun source.
32
32
  | `cli/build-binaries.sh` | Compiles the six release binaries. It checksums the six known artifact names rather than globbing `docks-kit-*`, so a packed `docks-kit-<version>.tgz` is never attested as a release binary. It stamps `cli/dist/VERSION` only when the directory holds one version, and on the next build discards every artifact that stamp attributes to a different version, because a launcher refuses to run one and keeping it makes `SHA256SUMS` span two versions. An artifact with no stamp has unknown provenance and may be a hand-built or downloaded recovery binary, so the script keeps it and warns; `--prune` discards those too. Nothing here removes an artifact the stamp vouches for. |
33
33
  | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
34
34
  | `cli/src/engine-native/ompSync.ts` | omp sync orchestration and summary |
35
- | `cli/src/commands/omp.ts` | `docks-kit omp` session launcher: renders the free-model run overlay and forwards args to omp |
36
- | `cli/src/engine-native/ompOverlay.ts` | Free-model overlay render plus catalog parse and thinking-ceiling helpers |
35
+ | `cli/src/commands/omp.ts` | `docks-kit omp` session launcher: rejects model-selecting forwarded flags, checks the free catalog of each candidate profile, renders the free-model run overlay, and starts `omp launch` |
36
+ | `cli/src/engine-native/ompOverlay.ts` | Free-model overlay render, omp argv and child environment, plus catalog parse and thinking-ceiling helpers |
37
37
  | `cli/src/engine-native/scratch.ts` / `cli/src/commands/scratch.ts` | `docks-kit scratch new\|remove`: private agent temporary directories under `~/.cache/docks-kit/scratch/`; removal accepts only a real path strictly inside the scratch root, the system temporary directory, or `/var/tmp` |
38
38
  | `cli/src/engine-native/tidy.ts` / `tidyReport.ts` / `cli/src/commands/tidy.ts` | `docks-kit tidy [--apply] [--repo <path>] [--report]`: plan and apply the safe leftover sweep (merged idle worktrees and their containers, orphaned processes in agent directories, idle scratch); Docker calls run only against a verified local endpoint (`unix:///…` or `npipe:////./pipe/…`); the report is read-only |
39
39
  | `cli/src/engine-native/ompKitPlugin.ts` | Materializes the `SoT/.omp/plugin/` payload to `~/.docks-kit/omp-plugin` with the kit version; `ompPlugins.ts syncPlugins` links it |
@@ -93,8 +93,9 @@ omp SoT notes:
93
93
  - `task.agentIdleTtlMs` is `120000`, so omp parks an idle subagent after 2 minutes instead of 7. `browser.idleCloseSec` is `600`.
94
94
  - By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp prompt rules, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH or a provider CLI such as `wrangler`, `vercel`, `kubectl`, or a remote Docker host) to targets named local, development, dev, test, homolog, homologation, staging, or preview, the plan-lifecycle non-production definition. A production cleanup needs an `ask` immediately before it, must be rare, and a `yolo` invocation does not answer that ask. Prompt rules cannot force an agent to ask, so this rule has no `bash.patterns` guard.
95
95
  - The omp CLI is upstream-owned. It updates through `omp update`, or through the external manager that owns the install, such as Tern or Nix. `omp update` refuses to run on an install that an external manager owns. Sync never installs or upgrades the CLI.
96
- - `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session. The overlay sets the 16 roles in `ompOverlay.ts ROLE_ORDER`, `judge` and `memory` included, to one free model and empties the 13 retry chains in `FALLBACK_ORDER`. Every other deployed chain stays as deployed. In particular, `modelRoles.web` and `retry.fallbackChains.web` keep the deployed web-search provider order. Thus a web search that falls through the `web/*` providers can reach the paid `openai-codex/gpt-6-luna` entry. 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 distinct model-and-level combination its own file, and the digest covers the selector and both levels. omp can re-read the overlay during a live session, so a second launcher with another model or level 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.
97
- - 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`. Every launch, a plain launch included, runs `omp models --json` (as `omp --profile <name> models --json` when the forwarded arguments select a profile) and checks the remembered or default model against the live free catalog. When that model is not in the catalog, the launcher stops with an error and does not start omp. `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 catalog models at zero input and output cost with `pricingStatus` free or unknown.
96
+ - `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session. The overlay sets the 16 roles in `ompOverlay.ts ROLE_ORDER`, `judge` and `memory` included, to one free model, empties the 13 retry chains in `FALLBACK_ORDER`, and empties the chains keyed by the free model (bare, `off`, and every `THINKING_LADDER` level). Every other deployed chain stays as deployed. In particular, `modelRoles.web` and `retry.fallbackChains.web` keep the deployed web-search provider order. Thus a web search that falls through the `web/*` providers can reach the paid `openai-codex/gpt-6-luna` entry. It renders the overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600). `ompOverlay.ts overlayFileName` gives each distinct model-and-level combination its own file, and the digest covers the selector and both levels. omp can re-read the overlay during a live session, so a second launcher with another model or level must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again.
97
+ - The launcher enforces the free model before omp starts. `omp.ts rejectedForwardedFlag` rejects a forwarded `--config`, `--model`, `--smol`, `--slow`, `--plan`, `--models`, `--provider`, `--prewalk-into`, or `--plan-yolo-into`, in both forms and also after a `--`, with exit 2 and a message that names the recoveries. `ompOverlay.ts buildOmpArgs` starts omp as `omp launch --config <overlay> --model <selector>[:<level>] [args...]`, so every forwarded word is message text, no omp subcommand runs through the launcher, and `--continue` or `--resume` keeps the free model. `ompOverlay.ts ompChildEnvironment` sets `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and `PI_PLAN_MODEL` to the free role values, and appends the overlay to `PI_CONFIG_FILES` so an `omp` that the bash tool of the session starts loads it too. The launcher prints one warning for each exported model variable that it replaces. In-session selection (`Alt+M`, `Alt+P`, `/switch`, `/model`, `/modelpreset`, `/resume`, a seance subagent), the `web` role, the model-kind roles `image`, `speech`, and `dictation`, and extensions and hooks stay outside the launcher. An `Alt+M` assignment of `default` writes `modelRoles.default` to the deployed `~/.omp/agent/config.yml`. `cli/docs/omp-models.md` lists these paths.
98
+ - 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`. Every launch, a plain launch included, runs `omp models --json` for the profile of the environment and `omp --profile <name> models --json` for each forwarded `--profile` value, and checks the remembered or default model against each live free catalog. When that model is not free in every one of these catalogs, the launcher stops with an error and does not start omp. `--model` and `--pick` resolve against the catalog of the last forwarded profile. `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 catalog models at zero input and output cost with `pricingStatus` free or unknown.
98
99
  - `docks-kit omp --fast` toggles `tier.openai` in the deployed `~/.omp/agent/config.yml` between `priority` (omp's `/fast on` tier for OpenAI and OpenAI-Codex models) and `none`, prints the change, and exits. `ompFastMode.ts toggleOpenAiFast` edits only that key. `SoT/.omp/config.yml` does not declare `tier.openai`, so the additive merge keeps the toggled value across sync. There is no Ultrafast flag: omp ignores `ultrafast` for a Codex model whose catalog `serviceTiers` omits it, and the current GPT models omit it.
99
100
 
100
101
  For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
@@ -131,7 +132,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
131
132
  - **One exemption: the kit's own package.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version. `cli/test/unit/hostTargets.test.ts` asserts that pin in all four launcher and installer scripts, and `cli/test/unit/install.test.ts` proves `install.sh` passes it to the Bun installer.
132
133
  ## Testing
133
134
 
134
- Run `bun run check` before and after each change: oxlint, `oxfmt --check`, `tsc --noEmit`, unit tests, and both golden suites. Scripts: `lint`, `format:check`, `typecheck`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on push and pull request with Bun 1.4.2. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `oxfmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), `bun run test:runtime:posix`, and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
135
+ Run `bun run check` before and after each change: oxlint, `oxfmt --check`, `bun check`, unit tests, and both golden suites. Scripts: `lint`, `format:check`, `typecheck`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on push and pull request with Bun 1.4.4. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `oxfmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), `bun run test:runtime:posix`, and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
135
136
 
136
137
  Use direct acceptance and focused regressions while iterating, then run the full unit/golden gate once at the pre-commit or release boundary. Reuse still-matching evidence; a later relevant edit invalidates only the affected rung and final gate, not every prior check.
137
138
 
package/README.md CHANGED
@@ -112,21 +112,23 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
112
112
  working legacy hook/statusline setup and reports that migration is deferred.
113
113
  - **Command guards** — omp, Claude Code, and Codex share one fail-closed
114
114
  policy for destructive shell commands; to remove, agents use the trash
115
- (`gio trash -- <path>`, or `trash <path>` on macOS). `rm` of the home
116
- directory or `/` and `HOME` reassignment are denied. omp also denies every
117
- recursive `rm`, `find -delete`, `find -exec rm`, and `xargs rm`, and runs
118
- any other `rm` without a prompt. In omp, `git clean`, `git reset --hard`,
119
- and any `git push` that could force ask; Claude Code and Codex also ask
120
- before `find -delete`, a recursive `rm`, and every `git rm`. An omp
121
- subagent cannot answer an ask, so omp rejects it; a Codex ask can go to its
122
- `auto_review` reviewer. Details, per-tool differences, and gaps:
115
+ (`gio trash -- <path>`, or `trash <path>` on macOS); omp agents remove a
116
+ temporary file or directory with `docks-kit scratch remove`. `rm` of the
117
+ home directory or `/` and `HOME` reassignment are denied. omp also denies
118
+ every recursive `rm`, `find -delete`, `find -exec rm`, and `xargs rm`, and
119
+ runs any other `rm` without a prompt. In omp, `git clean`,
120
+ `git reset --hard`, and any `git push` that could force ask; Claude Code and
121
+ Codex also ask before `find -delete`, a recursive `rm`, and every `git rm`.
122
+ An omp subagent cannot answer an ask, so omp rejects it; a Codex ask can go
123
+ to its `auto_review` reviewer. Details, per-tool differences, and gaps:
123
124
  `docks-kit docs command-guards`.
124
- - **Agent cleanup (omp)** — `docks-kit scratch` creates and removes agent
125
- temporary directories with checked paths, and `docks-kit tidy` removes
126
- merged idle worktrees, their containers, orphaned processes, and idle
127
- scratch directories; `--report` lists other disk and memory use. The kit
128
- omp plugin `docks-kit-omp` exposes these as tools, reminds the agent of
129
- what it created, and runs the sweep at most once per 12 hours.
125
+ - **Agent cleanup (omp)** — `docks-kit scratch` creates agent temporary
126
+ directories and removes agent temporary files and directories with checked
127
+ paths, and `docks-kit tidy` removes merged idle worktrees, their containers,
128
+ orphaned processes, and idle scratch directories; `--report` lists other
129
+ disk and memory use. The kit omp plugin `docks-kit-omp` exposes these as
130
+ tools, reminds the agent of what it created, and runs the sweep at most
131
+ once per 12 hours.
130
132
 
131
133
  ## Repository map
132
134
 
@@ -2,8 +2,9 @@
2
2
 
3
3
  The kit ships one destructive-command policy to omp, Claude Code, and Codex.
4
4
  The short rule for agents: **to remove, use the trash**. Run
5
- `gio trash -- <path>` on Linux or `trash <path>` on macOS. To remove a path
6
- from the git index, run `git rm -- <path>`.
5
+ `gio trash -- <path>` on Linux or `trash <path>` on macOS. In omp, remove a
6
+ temporary file or directory with `docks-kit scratch remove <path>` instead.
7
+ To remove a path from the git index, run `git rm -- <path>`.
7
8
 
8
9
  The policy follows one principle: **fail closed**. A command is allowed only
9
10
  in a canonical form that is safe by construction. Every other form that could
@@ -81,14 +82,16 @@ it shares the `--f` prefix.
81
82
 
82
83
  ## How an agent removes files
83
84
 
84
- 1. Move a file or a directory to the trash with `gio trash -- <path>` on Linux
85
- or `trash <path>` on macOS. The `--` ends option parsing, so `gio` reads
86
- every later argument as a path, and a path such as `--empty` cannot empty
87
- the trash.
88
- 2. `gio trash` does not trash on a system internal mount, such as a `tmpfs`
89
- `/tmp`. In omp, remove a temporary directory with the `scratch_remove`
90
- tool or `docks-kit scratch remove <path>`. In Claude Code and Codex, leave
91
- a temporary file in `/tmp`; the system clears it.
85
+ 1. In omp, remove a temporary file or directory with the `scratch_remove`
86
+ tool or `docks-kit scratch remove <path>`. The command removes only a path
87
+ inside the scratch root, the system temporary directory, or `/var/tmp`.
88
+ `gio trash` does not trash on a system internal mount, such as a `tmpfs`
89
+ `/tmp`.
90
+ 2. Move every other file or directory to the trash with `gio trash -- <path>`
91
+ on Linux or `trash <path>` on macOS. The `--` ends option parsing, so `gio`
92
+ reads every later argument as a path, and a path such as `--empty` cannot
93
+ empty the trash. In Claude Code and Codex, leave a temporary file in
94
+ `/tmp`; the system clears it.
92
95
  3. To remove a path from the git index, run `git rm -- <path>`. To remove a
93
96
  worktree, run `git worktree remove -- <path>`. In omp, when git refuses
94
97
  because the worktree has changes, the agent may pass `--force` once, after
package/cli/docs/flags.md CHANGED
@@ -62,9 +62,26 @@ ignored with a warning; Claude modifiers never touch Codex config and vice versa
62
62
  | `--pick` | Interactive picker over free catalog models; records the choice the same way |
63
63
  | `--fast` | Toggle `tier.openai` between `priority` and `none` in the deployed `~/.omp/agent/config.yml`, print the change, and exit; the same tier omp's `/fast on` selects for OpenAI and Codex models |
64
64
 
65
- Remaining arguments forward verbatim to omp after the launcher flags.
66
- `docks-kit omp -p "..."` runs one prompt. `docks-kit omp --continue` resumes
67
- the previous session. A bare `docks-kit omp` opens an interactive session.
65
+ The launcher starts omp as
66
+ `omp launch --config <overlay> --model <selector>[:<level>]`, followed by the
67
+ remaining arguments in the same order. `docks-kit omp -p "..."` runs one
68
+ prompt. `docks-kit omp --continue` resumes the previous session on the free
69
+ model. A bare `docks-kit omp` opens an interactive session. `launch` makes omp
70
+ read every forwarded word as message text, so no omp subcommand runs through
71
+ the launcher; run `omp` directly for a subcommand.
72
+
73
+ The launcher rejects a forwarded `--config`, `--model`, `--smol`, `--slow`,
74
+ `--plan`, `--models`, `--provider`, `--prewalk-into`, or `--plan-yolo-into`,
75
+ in the `--flag value` and the `--flag=value` form and also after a `--`. It
76
+ exits with code 2 before omp starts. The error names the flag and the
77
+ recoveries: `--model <selector>` before the other arguments or `--pick` for a
78
+ free model, `omp` directly for a paid model, and `PI_CONFIG_FILES` for another
79
+ config file. The launcher sets `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and
80
+ `PI_PLAN_MODEL` to the free role values, warns once for each exported value
81
+ that it replaces, and appends the overlay to `PI_CONFIG_FILES`. See
82
+ [omp-models.md](omp-models.md#free-session-launcher-docks-kit-omp) for the
83
+ full policy and the paths that stay outside the launcher.
84
+
68
85
  The launcher changes no deployed file and never invokes `sync`, except for
69
86
  `--fast`, which changes only `tier.openai` and launches nothing. `--fast` over
70
87
  `ultrafast` selects `priority`.
@@ -75,8 +92,9 @@ never reach omp:
75
92
  - `--model`, `--pick`, `--fast`
76
93
  - `--help`, `--version`, `--log-level`, `--wizard`, `--completions`
77
94
 
78
- The same names on omp stay reachable behind an explicit delimiter. Use
79
- `docks-kit omp -- --help` to ask omp for help.
95
+ The same names, except `--model`, stay reachable on omp behind an explicit
96
+ delimiter. `docks-kit omp -- --help` prints the help of `omp launch`. A
97
+ forwarded `--model` stops the launcher with exit 2, also behind `--`.
80
98
 
81
99
  ## `scratch` and `tidy`
82
100
 
@@ -423,13 +423,17 @@ overlay sets the 16 chat-model roles in `ompOverlay.ts ROLE_ORDER` to that
423
423
  model and empties the 13 retry fallback chains in `ompOverlay.ts
424
424
  FALLBACK_ORDER`. These roles include `memory` and `judge`. The SoT does
425
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.
426
+ and that chain can name a paid model. The overlay also empties the retry
427
+ chains keyed by the free model: the bare selector, `<selector>:off`, and
428
+ `<selector>:<level>` for every level in `ompOverlay.ts THINKING_LADDER`. omp
429
+ uses a chain keyed by the model before a role chain, so a project or
430
+ `PI_CONFIG_FILES` chain for the free model could otherwise reach a paid model.
431
+ The overlay does not set the `web` role or its retry chain. The deployed
432
+ web-search provider order therefore applies, and that order includes the paid
433
+ `openai-codex/gpt-6-luna` entry. omp merges the overlay key by key. Each other
434
+ deployed retry chain, such as a `plan`, `slow`, or `designer` chain, therefore
435
+ stays in the merged config. A retry of the free model does not reach such a
436
+ chain, because omp uses the empty chain keyed by the free model first.
433
437
  The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
434
438
  a model that publishes no thinking ladder, where both keys are omitted and the
435
439
  deployed values apply.
@@ -447,31 +451,70 @@ apart. A session launch never reads or writes `~/.omp/agent/config.yml` or
447
451
  never touches the SoT. The next plain `omp` run uses the paid configuration
448
452
  again.
449
453
 
450
- Every argument after the launcher flags forwards verbatim to omp. `docks-kit
451
- omp -p "..."` runs one prompt. `docks-kit omp --continue` resumes the
452
- previous session. A bare `docks-kit omp` opens an interactive session.
454
+ The launcher starts omp as
455
+ `omp launch --config <overlay> --model <selector>[:<level>] [args...]`, where
456
+ `[args...]` are the arguments after the launcher flags, in the same order.
457
+ `docks-kit omp -p "..."` runs one prompt. `docks-kit omp --continue` resumes
458
+ the previous session. A bare `docks-kit omp` opens an interactive session.
459
+
460
+ `launch` makes omp read every forwarded word as message text. So `docks-kit
461
+ omp commit` sends `commit` to the free model as a prompt, and no omp
462
+ subcommand runs through the launcher. To run an omp subcommand such as
463
+ `commit`, `bench`, or `search`, run `omp` directly. The explicit `--model`
464
+ outranks the model that omp restores from a stored session. So `--continue`,
465
+ `--resume`, and `autoResume` keep the free model and its level.
466
+
467
+ ### Model selection that the launcher controls
453
468
 
454
469
  The overlay ranks above the deployed global and project configuration, and
455
- below runtime overrides and later overlay files. Each input below therefore
456
- selects a model that the overlay does not control:
457
-
458
- - A forwarded later config overlay. The launcher passes its own `--config`
459
- first, and omp applies a later overlay file over an earlier one.
460
- - The runtime model flags `--model`, `--smol`, `--slow`, and `--plan`. The
461
- legacy `--provider` flag selects a provider. `--models` sets the model
462
- patterns that `Ctrl+P` cycling can reach, so cycling can leave the free
463
- model.
470
+ below runtime overrides and later overlay files. The launcher handles each
471
+ known input that can select a model above the overlay:
472
+
473
+ - Forwarded model flags. The launcher rejects `--config`, `--model`,
474
+ `--smol`, `--slow`, `--plan`, `--models`, `--provider`, `--prewalk-into`,
475
+ and `--plan-yolo-into`, in the `--flag value` and the `--flag=value` form.
476
+ It exits with code 2 and starts no omp process. It checks every forwarded
477
+ argument, also after a `--`, because omp can read that `--` as the value of
478
+ a flag such as `--api-key` and then read the next flag. The error names the
479
+ flag and the recoveries. For a free model, put `--model <selector>` before
480
+ the other arguments or use `--pick`. For a paid model, run `omp` directly.
481
+ For another config file, list it in `PI_CONFIG_FILES`.
482
+ - A restored session model. The explicit `--model` keeps the free model.
483
+ - An omp subcommand. `launch` makes it message text.
464
484
  - The model environment variables `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and
465
- `PI_PLAN_MODEL`. `PI_CONFIG_FILES` is not in this set, because those files
466
- load before `--config` overlays.
467
- - The in-session model selector. `Alt+M` sets the roles, and `Alt+P` picks a
468
- model for the current session only.
469
- - A restored persisted session model. `--continue`, `--resume`, and
470
- `autoResume` restore the model of the session they open, so a session that
471
- started under the paid configuration returns to its paid model.
472
-
473
- This list names the known selection paths. It is not a closed set. The
474
- launcher does not reject these inputs today.
485
+ `PI_PLAN_MODEL`. The launcher sets each one to the overlay value of its
486
+ role in the omp environment, and prints one warning for each exported value
487
+ that it replaces. omp fills an unset or empty variable from its `.env`
488
+ files, so the launcher sets the variables instead of removing them.
489
+ - `PI_CONFIG_FILES`. The launcher appends the overlay path to the exported
490
+ entries, so an `omp` that the bash tool of the session starts loads the
491
+ overlay too. omp loads these files below `--config` overlays, so an exported
492
+ entry still applies below the overlay. A `PI_CONFIG_FILES` value in an omp
493
+ `.env` file does not apply in a launcher session, because the launcher
494
+ always sets the variable.
495
+ - The omp profile. The catalog check below covers every profile that the
496
+ launch can select.
497
+
498
+ ### Model selection outside the launcher
499
+
500
+ These paths act after omp starts or outside the chat roles. The launcher does
501
+ not control them:
502
+
503
+ - In-session selection. `Alt+M` (model hub), `Alt+P` (session-only picker),
504
+ `/switch <selector>`, `/model`, and `/modelpreset` can select any catalog
505
+ model. `/resume` and a session switch restore the model of the target
506
+ session. A seance subagent runs on the models of its source session. An
507
+ `Alt+M` assignment of the `default` role writes `modelRoles.default` to the
508
+ deployed `~/.omp/agent/config.yml`, so later plain `omp` runs use it too.
509
+ - The `web` role and its retry chain. By owner decision they keep the
510
+ deployed web-search provider order, which can reach the paid
511
+ `openai-codex/gpt-6-luna` entry.
512
+ - The model-kind roles `image`, `speech`, and `dictation`. A chat model
513
+ cannot serve them, so the overlay does not set them.
514
+ - Extensions and hooks. `-e`, `--hook`, and `--plugin-dir` run arbitrary
515
+ code, and that code can select any model.
516
+
517
+ These lists name the known paths. They are not a closed set.
475
518
 
476
519
  The default model is `opencode-zen/muse-spark-1.3-contributor-free` ("Muse
477
520
  Spark 1.3 Free", 1,048,576-token context) at `xhigh`. `xhigh` is the ceiling
@@ -500,11 +543,11 @@ zero input and output cost with `pricingStatus` `free` or `unknown` (26
500
543
  entries on 2026-09-11). A zero-cost row with another status, such as
501
544
  `variable` or `included`, is billed outside the token price, so the picker
502
545
  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.
505
- Higher-precedence model selection can replace those values. The catalog can
506
- advertise a free model that the account cannot call; omp reports that
507
- provider error unchanged.
546
+ chosen free model and empties the 13 `FALLBACK_ORDER` chains and the chains
547
+ keyed by that model. The `web` role, its chain, and each other deployed chain
548
+ keep the deployed values. The
549
+ catalog can advertise a free model that the account cannot call; omp reports
550
+ that provider error unchanged.
508
551
 
509
552
  After the model, the wizard asks about thinking levels. `ompOverlay.ts
510
553
  planEffortChoice` decides which questions apply, because omp accepts a
@@ -527,16 +570,25 @@ A session whose advisor differs from the other roles reports both on the
527
570
  launch line.
528
571
 
529
572
  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.
573
+ live free catalog of each candidate profile. A plain launch checks the
574
+ remembered model, or the default model, against those catalogs. When the
575
+ model is not there, the launcher stops before omp starts. The model can be
576
+ renamed, repriced, or on a provider that is not logged in. Without this
577
+ check, omp silently starts the default model of the first logged-in
578
+ provider, which can be paid.
579
+
580
+ Each omp profile has its own login and `models.yml`, so a selector can be
581
+ free in one profile and missing or paid in another. The candidate profiles
582
+ are the profile of the environment (`OMP_PROFILE`, `PI_PROFILE`, or the
583
+ default) and each forwarded `--profile <name>` or `--profile=<name>` value.
584
+ The launcher reads every forwarded argument, also after a `--`, because omp
585
+ can read that `--` as a flag value and then select a later profile. It runs
586
+ `omp models --json` for the profile of the environment and
587
+ `omp --profile <name> models --json` for each forwarded name. The session
588
+ model must be free in every one of these catalogs. `--model` and `--pick`
589
+ choose from the catalog of the last forwarded profile, or of the profile of
590
+ the environment when the arguments name none. A `--profile` without a name
591
+ stops the launcher before omp starts.
540
592
 
541
593
  When the catalog renames the free variant, change only the default selector
542
594
  constant. Until then, a plain launch on that default stops with an error. A
@@ -16,6 +16,7 @@ import {
16
16
  advisorRecommendation,
17
17
  buildOmpArgs,
18
18
  ladderCeiling,
19
+ ompChildEnvironment,
19
20
  overlayFileName,
20
21
  planEffortChoice,
21
22
  parseFreeModels,
@@ -80,20 +81,20 @@ export function resolveFreeSelector(
80
81
  }
81
82
 
82
83
  /**
83
- * The omp profile that the forwarded arguments select. omp reads
84
- * `--profile <name>` or `--profile=<name>` before a `--`, the last one wins,
85
- * and it rejects a missing or empty name. The catalog check must query the
86
- * profile the session runs, so it reads the arguments the same way.
84
+ * Every omp profile that the forwarded arguments can select, in argv order.
85
+ * omp reads `--profile <name>` or `--profile=<name>`, the last one wins, and
86
+ * it rejects a missing or empty name. The scan does not stop at `--`,
87
+ * because omp can read that `--` as the value of a flag such as
88
+ * `--system-prompt` and still select a later profile.
87
89
  */
88
90
  export type ForwardedProfile =
89
- | { readonly ok: true; readonly profile: string | undefined }
91
+ | { readonly ok: true; readonly profiles: ReadonlyArray<string> }
90
92
  | { readonly ok: false; readonly message: string };
91
93
 
92
94
  export function forwardedProfile(forwarded: ReadonlyArray<string>): ForwardedProfile {
93
- let profile: string | undefined;
95
+ const profiles: Array<string> = [];
94
96
  for (let index = 0; index < forwarded.length; index++) {
95
97
  const arg = forwarded[index]!;
96
- if (arg === "--") break;
97
98
  let value: string | undefined;
98
99
  if (arg === "--profile") {
99
100
  value = forwarded[index + 1];
@@ -105,9 +106,48 @@ export function forwardedProfile(forwarded: ReadonlyArray<string>): ForwardedPro
105
106
  continue;
106
107
  }
107
108
  if (value === "") return { ok: false, message: "--profile requires a profile name" };
108
- profile = value;
109
+ profiles.push(value);
109
110
  }
110
- return { ok: true, profile };
111
+ return { ok: true, profiles };
112
+ }
113
+
114
+ // omp flags that can select a model the free overlay does not control.
115
+ const MODEL_SELECTING_FLAGS: Record<string, true> = {
116
+ "--config": true,
117
+ "--model": true,
118
+ "--smol": true,
119
+ "--slow": true,
120
+ "--plan": true,
121
+ "--models": true,
122
+ "--provider": true,
123
+ "--prewalk-into": true,
124
+ "--plan-yolo-into": true,
125
+ };
126
+
127
+ export type ForwardedFlagCheck =
128
+ | { readonly ok: true }
129
+ | { readonly ok: false; readonly message: string };
130
+
131
+ /**
132
+ * Reject a forwarded omp flag that can select a model outside the free
133
+ * session. The scan does not stop at `--`, because omp can read that `--` as
134
+ * the value of a flag and then parse the next token as a flag.
135
+ */
136
+ export function rejectedForwardedFlag(forwarded: ReadonlyArray<string>): ForwardedFlagCheck {
137
+ for (const arg of forwarded) {
138
+ const equals = arg.indexOf("=");
139
+ const flag = equals === -1 ? arg : arg.slice(0, equals);
140
+ if (MODEL_SELECTING_FLAGS[flag] !== true) continue;
141
+ const configNote =
142
+ flag === "--config"
143
+ ? " To load another config, list it in PI_CONFIG_FILES, which omp loads below the overlay."
144
+ : "";
145
+ return {
146
+ ok: false,
147
+ message: `Forwarded ${flag} can select a model outside the free session. For a free model, put --model <selector> before other arguments or use --pick; for a paid model, run omp directly.${configNote}`,
148
+ };
149
+ }
150
+ return { ok: true };
111
151
  }
112
152
 
113
153
  const loadFreeCatalog = (
@@ -213,6 +253,11 @@ const pickLevels = (catalogModel: CatalogModel) =>
213
253
 
214
254
  export const ompCommand = Command.make("omp", { model, pick, fast, args }, (config) =>
215
255
  Effect.gen(function* () {
256
+ // Check the forwarded arguments before omp, the catalog, or kit.db, so a
257
+ // rejected launch starts no process and writes nothing.
258
+ const forwardedFlag = rejectedForwardedFlag(config.args);
259
+ if (!forwardedFlag.ok) return yield* bail(forwardedFlag.message);
260
+
216
261
  if (Option.isSome(config.model) && config.pick) {
217
262
  return yield* bail("Pass either --model <selector> or --pick, not both");
218
263
  }
@@ -251,13 +296,24 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
251
296
  if (config.pick && (!process.stdin.isTTY || !process.stdout.isTTY)) {
252
297
  return yield* bail("Picking needs a terminal; pass --model <selector> instead");
253
298
  }
254
- // Every launch reads the live catalog once, because a remembered or
255
- // default model can be renamed, repriced, or lose its provider login.
256
- // omp then silently starts a paid default model instead. The catalog
257
- // comes from the profile that the forwarded arguments select.
299
+ // Every launch reads the live catalog, because a remembered or default
300
+ // model can be renamed, repriced, or lose its provider login. omp then
301
+ // silently starts a paid default model instead. omp can run the
302
+ // environment's profile or any forwarded one, so the session model must
303
+ // be free in the catalog of each.
258
304
  const profile = forwardedProfile(config.args);
259
305
  if (!profile.ok) return yield* bail(profile.message);
260
- const free = yield* loadFreeCatalog(omp, profile.profile);
306
+ const candidates: Array<string | undefined> = [undefined];
307
+ for (const name of profile.profiles) {
308
+ if (!candidates.includes(name)) candidates.push(name);
309
+ }
310
+ const catalogs: Array<ReadonlyArray<CatalogModel>> = [];
311
+ for (const candidate of candidates) {
312
+ catalogs.push(yield* loadFreeCatalog(omp, candidate));
313
+ }
314
+ // --model and --pick choose from the catalog of the last forwarded
315
+ // profile, which omp selects when no flag consumes it.
316
+ const free = catalogs[candidates.indexOf(profile.profiles.at(-1))]!;
261
317
  // The value the launcher writes is the value it runs, so a concurrent
262
318
  // launcher or a failed read of kit.db cannot change this session.
263
319
  let chosen: OmpSessionModel | undefined;
@@ -298,19 +354,22 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
298
354
  };
299
355
  }
300
356
 
301
- if (chosen !== undefined) {
302
- const remembered = chosen;
303
- yield* Effect.sync(() => writeOmpSessionModel(home, remembered));
304
- }
305
-
306
357
  const session: OmpSessionModel =
307
358
  chosen ?? (yield* Effect.sync(() => readOmpSessionModel(home))) ?? DEFAULT_OMP_SESSION_MODEL;
308
- if (!free.some((candidate) => candidate.selector === session.selector)) {
359
+ const freeInEveryProfile = catalogs.every((catalog) =>
360
+ catalog.some((candidate) => candidate.selector === session.selector),
361
+ );
362
+ if (!freeInEveryProfile) {
309
363
  return yield* bail(
310
364
  `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`,
311
365
  );
312
366
  }
313
367
 
368
+ if (chosen !== undefined) {
369
+ const remembered = chosen;
370
+ yield* Effect.sync(() => writeOmpSessionModel(home, remembered));
371
+ }
372
+
314
373
  // A stable cache path, not a temp file deleted at exit, because omp may
315
374
  // re-read the overlay during a live session. The name carries a digest of
316
375
  // the rendered overlay, so a second launcher on another model or level
@@ -344,8 +403,20 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
344
403
  `Starting omp with ${session.selector} at ${levelText}${advisorText} (session only; deployed config unchanged)`,
345
404
  );
346
405
 
406
+ // An exported model variable would set its role above the overlay, so the
407
+ // session gets the overlay value and the user sees what changed.
408
+ const childEnvironment = ompChildEnvironment(process.env, overlayPath, session);
409
+ for (const name of childEnvironment.replaced) {
410
+ yield* Console.error(
411
+ `${name} is set; this session uses ${childEnvironment.env[name]} instead`,
412
+ );
413
+ }
414
+
347
415
  const child = yield* Effect.sync(() =>
348
- spawnHost("omp", buildOmpArgs(overlayPath, config.args), { stdio: "inherit" }),
416
+ spawnHost("omp", buildOmpArgs(overlayPath, session, config.args), {
417
+ stdio: "inherit",
418
+ env: childEnvironment.env,
419
+ }),
349
420
  );
350
421
  if (child.error !== undefined) {
351
422
  return yield* bail(
@@ -357,6 +428,6 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
357
428
  }),
358
429
  ).pipe(
359
430
  Command.withDescription(
360
- "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.",
431
+ "Start omp with every chat-model role set to the remembered free model for this run only. The launcher starts 'omp launch' with an explicit --model, so omp reads a forwarded subcommand name as message text and a resumed session keeps the free model. It rejects forwarded flags that can select another model (--config, --model, --smol, --slow, --plan, --models, --provider, --prewalk-into, --plan-yolo-into); run omp directly for a paid model or a subcommand. 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 of each candidate profile. --fast instead toggles OpenAI/Codex fast mode in the deployed omp config and exits.",
361
432
  ),
362
433
  );
@@ -70,6 +70,6 @@ export const scratchCommand = Command.make("scratch", { action, operands }, (con
70
70
  }),
71
71
  ).pipe(
72
72
  Command.withDescription(
73
- "Create or remove agent temporary directories; removal accepts only paths inside the scratch root, the system temporary directory, or /var/tmp.",
73
+ "Create an agent temporary directory, or remove agent temporary files and directories; removal accepts only paths inside the scratch root, the system temporary directory, or /var/tmp.",
74
74
  ),
75
75
  );