docks-kit 0.17.1 → 0.17.3

package/AGENTS.md

@@ -28,11 +28,16 @@ launcher can fall back to Bun source.
 
 | Path | Purpose |
 |------|---------|
-| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json`. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
+| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json`. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`, and the mismatch warning names the rebuild remedy. A launcher never deletes a binary: on a host without Bun it is the only remaining recovery path. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
+| `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. |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
 | `cli/src/engine-native/ompSync.ts` | omp file deployment, marketplace registration, and plugin synchronization |
 | `cli/src/commands/omp.ts` | `docks-kit omp` session launcher: renders the free-model run overlay and forwards args to omp |
 | `cli/src/engine-native/ompOverlay.ts` | Free-model overlay render plus catalog parse and thinking-ceiling helpers |
+| `cli/src/engine-native/<axis>.ts` | One change axis per file: `codexConfig`/`codexHooks`/`codexPlugins`/`codexStatus`, `claudeSettings`/`claudeRemovals`/`claudePluginPasses`/`claudeOptionalPlugins`/`claudeLsp`, `parseModifiers`/`parseHelp`, `ompFileDeploy`/`ompMarketplace`/`ompPlugins`, `skillsManifest`/`skillsLinks`/`skillsInstall`/`skillsPrune`, `engineCtx`/`syncConcurrency`/`syncDispatch`; orchestrators keep prior exports |
+| `cli/src/engine-native/sharedTypes.d.ts` | Single definition per shared shape (manifest records, settings edits, omp session model, scalar modifier flags) |
+| `.oxlintrc.json` / `.oxfmtrc.json` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and code format scope |
+| `cli/test/fixtures/` | Golden fixtures: `home-fresh`, `home-drift`, `home-invalid-json`, `codex-toml`, `statusline` |
 | `cli/` | Effect 4 RC CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
@@ -66,15 +71,18 @@ omp SoT notes:
 - `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
 - `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`.
 - `ompSync.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards.
-- `cycleOrder` ends with the `fable` role (`modelRoles.fable` = `anthropic/claude-fable-5-1:medium`, `modelTags.fable` visible, `retry.fallbackChains.fable` empty), so the model switcher reaches Fable 5.1 as its fourth stop and never falls back off it. The hidden `switch_fable` role points at the same model and level.
-- `modelRoles.task` is `openai-codex/gpt-6-astra:low`, chosen for 2.60 s TTFT and 4k output tokens per task at cost parity with the previous `gpt-5.6-sol:high`. `task.agentModelOverrides` points four reviewer names at `@task`; only the bundled `reviewer` and `security-reviewer` are discoverable OMP agents, so those two inherit `task`, and the `code-reviewer` and `plan-reviewer` entries are dormant. Artificial Analysis publishes no per-level Astra Coding Agent Index score, so reviewer output is the signal to watch.
-- `SoT/.omp/models.yml` deploys to `~/.omp/agent/models.yml` through `mergeOmpModels`, which keeps every deployed-only key. A user file may carry provider credentials, so whole-file replacement is wrong. It restricts the `gpt-6-astra` effort ladder to `low`, so every Astra subagent runs `low` while `task.maxEffort: high` lets `scout` and `sonic` reach Luna `high` with `effort: hi`. `cli/docs/omp-models.md` records the verification.
+- `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync, without `--reconcile`. The pass is required because `mergeOmpConfig` is additive, so removing a key from the SoT alone never removes it from a deployed file. A key retired with a recorded value is pruned only while the deployed value still matches that value, so a user edit survives; a key retired outright, such as `providers.webSearchOrder`, is pruned at any value.
+- `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6-astra:xhigh`, and `modelTags.astra` is visible. Astra and Fable fall back to each other through concrete selectors. `modelRoles.fable` remains `anthropic/claude-fable-5-1:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
+- `modelRoles.task` is `openai-codex/gpt-5.6-sol:high`. The four reviewer entries in `task.agentModelOverrides` inherit it through `@task`. Only bundled `reviewer` and `security-reviewer` are discoverable OMP agents; `code-reviewer` and `plan-reviewer` stay dormant.
+- `modelRoles.web` is `web/firecrawl` and `retry.fallbackChains.web` carries the explicit 27-entry provider order. The kit declares both keys because the legacy `providers.webSearchOrder` key is retired: omp expands it in memory into these two keys and then drops it, and never writes that expansion back to disk. An explicit chain replaces omp's built-in web order wholesale, so the list must stay complete.
+- `SoT/.omp/models.yml` declares Astra's full `low, medium, high, xhigh, max` ladder with `defaultLevel: xhigh` as the worked provider ladder-override example. `ompYaml.ts mergeOmpModels` preserves deployed-only keys in `~/.omp/agent/models.yml`, because a user file may carry provider credentials. Whole-file replacement is wrong.
 - `SoT/.omp/AGENTS.md` carries the rule `Please remove all mannered prose.` Anthropic's Fable 5.1 prompting guide documents mannered prose as a Fable 5.1 behavior and gives that sentence as its short-version fix: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
 - `cli/docs/omp-models.md` (topic `omp-models`) records the role map rationale and the Artificial Analysis snapshot behind it. Model choices change with published benchmarks, so update that topic in the same commit as a role change.
+- `SoT/.omp/config.yml` sets `compaction.thresholdTokens` to `-1`, omp's schema default sentinel selecting reserve-based behavior: the trigger becomes `contextWindow` minus `max(floor(contextWindow * 0.15), 16384)`, which is 231,200 on the 272,000-token Codex window and 850,000 on the 1,000,000-token Anthropic window. The key ships as `-1` rather than being deleted because `ompYaml.ts mergeOmpConfig` is additive, so removing a key from SoT never removes it from a deployed file. `cli/docs/omp-context.md` (topic `omp-context`) carries the derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.
 - Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope.
 - Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
 - The omp CLI is upstream-owned and self-updating through `omp update`. Sync never installs or upgrades the CLI.
-- `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session on a single free model. It renders a run overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600) and passes it through omp's repeatable `--config` flag. `ompOverlay.ts overlayFileName` gives each model its own file, because omp can re-read the overlay during a live session and a second launcher on another model must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again. Remaining arguments forward verbatim to omp.
+- `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session with every model role set to one free model and every retry chain empty. Higher-precedence model selection can replace those overlay values. It renders the overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600) and passes it through omp's repeatable `--config` flag. `ompOverlay.ts overlayFileName` gives each model its own file, because omp can re-read the overlay during a live session and a second launcher on another model must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again. Remaining arguments forward verbatim to omp.
 - The session model persists per machine in `~/.docks-kit/state.json` under `ompSession`, next to `harnesses`. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both levels from the ladder of the chosen model for the `--model` path, and `ompOverlay.ts planEffortChoice` drives the `--pick` wizard, which asks whether every role shares one level and otherwise takes one level for the main roles and one for the advisor from that model's own ladder. Levels never come from a fixed list: free ladders are not uniform, three free models publish no `medium`, and two publish no ladder, which the overlay renders as bare selectors. The picker lists only zero-cost catalog models.
 
 For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
@@ -90,8 +98,10 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 - **Per-machine harness selection.** `~/.docks-kit/state.json` drives a flag-less sync. A missing file selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection file. `docks-kit harnesses` is the only command that writes the `harnesses` selection. The same state file also carries the independent `ompSession` key, which only `docks-kit omp` writes; every writer merges over the stored record, so neither key can drop the other.
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claudeSync.ts REMOVED_MANIFEST, baseline removal inventory`), a curated list of unambiguous kit-owned artifacts that `claudeSync.ts syncRemovals, baseline artifact prune` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.
-- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing and validation. `toolchain.ts` owns verified-version floor reporting over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own their tool-specific sync logic. `ompSync.ts` owns omp file and plugin sync. `ompYaml.ts` owns the omp YAML merge. `harnesses.ts` owns per-machine harness selection. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
+- **SOLID-aligned modules.** Axis modules own one concern each (see layout); orchestrators (`claudeSync.ts`, `codexSync.ts`, `skillsSync.ts`, `ompSync.ts`, `index.ts`, `argv.ts`, `parseArgs.ts`) keep prior exports. New shared shapes go in `sharedTypes.d.ts`, never a second local copy. The public CLI seam is `cli/src/engine.ts`.
 - **Small, reviewable changes.** Bundled multi-concern PRs are harder to review and revert. Split an engine/CLI change and a per-tool config change unless the change requires atomicity.
+- **Version bumps.** Bump `package.json` on user-visible behavior change; bump a `SoT/toolchain.json` `verified` pin only after testing that release. Refactors, splits, and doc edits bump nothing.
+- **Regenerate the payload.** After `SoT/`, `notification.mp3`, `package.json`, or `cli/tsconfig.json` changes, run `bun cli/scripts/generate-sot-payload.ts`; `bun run check:generated` verifies it. After file moves, clamp cited `metadata.source_files[].lines` ranges so `skillMetadata.test.ts` passes.
 - **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in the per-tool file) before invoking `--reconcile` or `--prune`. User-added permissions / env vars / plugins absent from SoT will be discarded.
 - **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md`, `SoT/.codex/AGENTS.md`, and `SoT/.omp/AGENTS.md` are loaded into agent sessions' prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `CLAUDE.md` / `AGENTS.md` at the repo root (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: …
 - **Cache-invariance for kit-authored prompt surfaces.** Never put timestamps, counters, or mutable state into SoT prompt files, hook outputs that land in the cached prefix, or tool definitions — cache breaks force cold-start writes. Dynamic context belongs in runtime-injected messages (e.g. SessionStart hook output), which is exactly how the kit's date/config injection works.
@@ -109,7 +119,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 - **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, and `cli/test/unit/install.test.ts` asserts that pin in all four launcher and installer scripts.
 ## Testing
 
-Automated coverage includes `bun run test:unit`, `bun run golden:dryrun`, and `bun run golden:mutation`; prove-red modes must exit non-zero after detecting planted mismatches. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
+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.
 
 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.
 
@@ -142,7 +152,7 @@ The Output Standard wins.
 Use `unslop` only for its pattern-detection lists.
 
 <constraint>
-When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agents/*.md` + its `.codex/agents/*.toml` twin) cites EngineNative internals, name the **module + exported/local function + semantic anchor** (e.g. `claudePlugins.ts syncPlugins, pass 5 uninstall guard`) — never a raw `file:NNN` line number, which goes stale on every refactor. Keep exactly one coarse `metadata.source_files[].lines` range per skill file as the sole intentional line-number touchpoint.
+When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agents/*.md` + its `.codex/agents/*.toml` twin) cites EngineNative internals, name the **module + exported/local function + semantic anchor** (e.g. `claudePluginPasses.ts syncPlugins, pass 5 uninstall guard`) — never a raw `file:NNN` line number, which goes stale on every refactor. Keep exactly one coarse `metadata.source_files[].lines` range per skill file as the sole intentional line-number touchpoint.
 </constraint>
 
 **Universal-skill bootstrap.** `SoT/.agents/skills.txt` is intentionally empty, so the default sync exposes no universal skills. The generic opt-in contract remains: each [agentskills.io](https://agentskills.io/specification) slug is installed by `skillsSync.ts` with `npx skills add <slug> -g -y -a claude-code codex`. The slug comes first because `-a/--agent` is variadic; naming both supported agents preserves the canonical `~/.agents/skills/<name>/SKILL.md` plus Claude's `~/.claude/skills/<name>` symlink. Existing canonical directories are reused idempotently, `--prune` removes only entries tracked in `~/.agents/.kit-managed-skills`, and skills requiring a separate CLI retain explicit helpers in `skillsSync.ts`.
@@ -158,33 +168,31 @@ non-`local` effect.
 
 <constraint>
 The plan record is a GitHub issue. Its body starts with
-`<!-- plan-contract: v3 -->`, then a blank line and the exact eight `##`
-sections; it has no frontmatter. GitHub owns title, open-work phase, owner,
-timestamps, and completion, and no plan markdown is tracked in the repository.
-Exactly three skills own the workflow: `plan-workspace` maintains the workspace;
-main-context `plan-manager` runs six phases - decide, draft, research, plan
-review, implement, code review - with bounded repair and fresh re-review in both
-review phases, then archives; internal `plan-reviewer` returns one readable
-pre-implementation verdict block per round. Two read-only reviewer wrappers
-ship, `plan-reviewer` and `code-reviewer`, and nothing else in the lifecycle has
-a wrapper.
+`<!-- plan-contract: v4 -->`, followed by one blank line and seven `##`
+sections. It has no frontmatter. GitHub owns the title, open-work phase, owner,
+timestamps, and completion. The repository tracks no plan markdown.
+Exactly three skills own the workflow. `plan-workspace` maintains the workspace.
+Main-context `plan-manager` runs six phases: decide, draft, research, plan
+review, implement, and code review. It uses bounded repair and fresh re-review
+in both review phases, then archives. Internal `plan-reviewer` returns one
+readable pre-implementation verdict block per round. Two read-only reviewer
+wrappers ship: `plan-reviewer` and `code-reviewer`.
 </constraint>
 
-After the marker and blank line, the record carries exactly `## Goal`,
-`## Research`, `## Steps`, `## Acceptance`, `## Do not touch`,
-`## Open questions`, `## Review`, and `## Verification Results`, in that order
-and once each. `## Goal` carries exactly one mode line. Open-work phase is one
-of `drafting`, `planned`, `ongoing`, or `blocked` in a `plan:<phase>` label; a
-blocked plan starts `## Open questions` with `Blocked: <one-line reason>`.
-Closed completion derives from GitHub `state` and `stateReason`. `## Review`
-contains exactly `_Review records are stored in issue comments._`. Each reviewer
-returns one markdown block, and the manager posts that whole block as one issue
-comment. The latest trusted well-formed record per review kind wins; its author
-must equal the plan's sole assignee. A legacy body verdict is consulted only
-when no trusted comment record exists for that kind. Both review phases use
-fresh inputs and run at most five rounds, stopping on pass, no progress, a
-finding surviving its fix, or `repair` or `fixes-required` in round five. A
-plan-review `blocked` verdict always routes its user-only decision through
+After the marker and blank line, the record carries exactly seven sections.
+They appear once each in this order: `## Goal`, `## Research`, `## Steps`,
+`## Acceptance`, `## Do not touch`, `## Open questions`, and
+`## Verification Results`. `## Goal` carries exactly one mode line.
+Open-work phase is `drafting`, `planned`, `ongoing`, or `blocked`.
+Every plan carries `plan`. A `plan:<phase>` label stores the open phase.
+A blocked plan starts `## Open questions` with `Blocked: <one-line reason>`.
+GitHub `state` and `stateReason` determine closed status. Review records live
+only in issue comments. Each reviewer returns one markdown block.
+The manager posts that block as one issue comment. The latest trusted eligible
+comment per review kind wins. Its author must equal the plan's sole assignee.
+Both review phases use fresh inputs and run at most five rounds. They stop on
+pass, no progress, a finding that survives repair, or a round-five non-pass.
+A plan-review `blocked` verdict routes its user-only decision through
 `## Open questions` and `ask`.
 
 The record carries no hash, permit, run identity, lock, or bundle, and the

package/cli/docs/omp-context.md

@@ -0,0 +1,104 @@
+# omp context and compaction
+
+This topic records why `SoT/.omp/config.yml` does not pin a compaction
+threshold, and what omp's reserve-based default computes on each model lane.
+
+## How omp resolves the trigger
+
+`resolveThresholdTokens` in omp source
+`packages/agent/src/compaction/compaction.ts` selects the trigger from three
+branches, in priority order.
+
+1. A positive `compaction.thresholdTokens` wins. omp clamps it to the range 1
+   through `contextWindow - 1`.
+2. Otherwise a positive `compaction.thresholdPercent` applies. omp clamps the
+   percent to the range 1 through 99 and computes
+   `floor(contextWindow * percent / 100)`.
+3. Otherwise, when both keys hold `-1`, reserve-based behavior applies.
+
+The reserve-based branch computes the trigger from the window itself:
+
+```text
+threshold = contextWindow - max(floor(contextWindow * 0.15), 16384)
+```
+
+omp names the 16384 constant `DEFAULT_RESERVE_TOKENS`. The 15% proportional
+reserve dominates on any window above roughly 109,227 tokens, so every lane
+the kit uses resolves through the proportional term and never through the flat
+constant.
+
+## Per-lane result
+
+| Lane | Window | Reserve | Threshold | Percent of window |
+|---|---:|---:|---:|---:|
+| `openai-codex/*` | 272,000 | 40,800 | 231,200 | 85.0% |
+| `anthropic/*` | 1,000,000 | 150,000 | 850,000 | 85.0% |
+
+Both lanes compact at the same fraction of their own window. The absolute
+trigger differs only because the windows differ.
+
+## Why the kit no longer pins 231200
+
+The kit previously shipped `compaction.thresholdTokens: 231200`. That value is
+exactly the reserve-based default for a 272,000-token window. It was therefore
+identical to the default on the Codex lane and changed nothing there. Its only
+real effect was forcing the Anthropic lane to compact at 23.1% of its window
+instead of 85%.
+
+The evidence below records 83 compactions measured between 2026-09-12 and
+2026-09-21, after omp 18.1.18 introduced the Anthropic server-side compaction
+lane.
+
+| Lane | Compactions | Maximum tokens before | Over window | Warnings |
+|---|---:|---:|---:|---:|
+| `anthropic` | 75 | 248,583 (24.9% of window) | 0 | 0 |
+| `openai-codex` | 8 | 263,591 (96.9% of window) | 0 | 0 |
+
+The median context freed was 64.8%. The pin was safe rather than dangerous.
+No session ran past its window, and omp raised no warning on either lane.
+Under the reserve-based default none of the 75 Anthropic compactions would
+have fired, because no session reached 850,000.
+
+## Why the key ships as -1 rather than being deleted
+
+`ompYaml.ts` `mergeOmpConfig` is additive. Its `mergeMappings, deployed-key
+retention loop` returns every deployed key that the SoT omits to the merged
+output, and the only drop predicate is `dropFallbackWildcard`, which is scoped
+to `retry.fallbackChains`.
+
+Deleting the key from the SoT would therefore leave the stale `231200` in
+every already-deployed `~/.omp/agent/config.yml` permanently. A present key
+holding the schema default sentinel `-1` overwrites that stale value on the
+next sync.
+
+Verify the deployed value after a sync:
+
+```bash
+omp config get compaction.thresholdTokens
+```
+
+The command must print `-1`.
+
+## The clamp hazard a fixed pin carries
+
+The fixed-token branch clamps the pinned value to `contextWindow - 1`. On any
+model whose window is below the pinned value, the reserve collapses to one
+token, so omp compacts only once the context is already full. The
+reserve-based default always leaves at least 15% of the window free.
+
+No current role model has a window below 272,000, so the hazard was latent
+rather than live. Not pinning removes it entirely, including for any future
+model with a smaller window.
+
+## Related settings left at their omp defaults
+
+| Setting | Value | Reason |
+|---|---|---|
+| `extendedContext` | `false` | omp 17.4.0 added the setting defaulting on, and a later release flipped the default to off. It caps a model carrying a premium long-context price tier at that model's standard-pricing window, so `openai-codex/gpt-5.6-sol` reports 272,000 rather than about 1,050,000. Enabling it makes a Codex window overrun structurally impossible. The cost is a cliff rather than a marginal rate: any request above the 272,000 threshold bills the whole request at input $10 instead of $4, cache read $1.00 instead of $0.40, and cache write $12.50 instead of $5.00. |
+| `compaction.idleEnabled` | `true` | omp default. Idle compaction fires below the reserve-based trigger on both lanes. A compaction whose reason is `idle` skips the progress guard. |
+| `compaction.idleThresholdTokens` | `200000` | omp default. |
+| `compaction.idleTimeoutSeconds` | `300` | omp default. |
+| `compaction.methodOrder` | `["remote","snapcompact","handoff","shake","soft"]` | omp default, remote first. Since omp 18.1.18 the Anthropic server-side lane handles Anthropic models, so snapcompact is a fallback rather than the primary path. |
+
+Every row records a decision to leave the omp default in place. None of these
+keys carries a kit value that differs from the default omp already applies.

package/cli/docs/omp-models.md

@@ -11,7 +11,7 @@ against.
 | `default` | `anthropic/claude-opus-5` | high | 48 | $3.61 | 16.96 s | 66 (Claude Code) |
 | `slow` | `anthropic/claude-opus-5` | xhigh | 50 | $4.88 | 28.65 s | 68 (Claude Code) |
 | `plan` | `anthropic/claude-opus-5` | xhigh | 50 | $4.88 | 28.65 s | 68 (Claude Code) |
-| `task` | `openai-codex/gpt-6-astra` | low | 46 | $0.82 | 2.60 s | n/a |
+| `task` | `openai-codex/gpt-5.6-sol` | high | 42 | $0.81 | 11.26 s | 64 (Codex) |
 | `advisor` | `openai-codex/gpt-5.6-sol` | medium | 39 | $0.50 | 4.90 s | 62 (Codex) |
 | `designer` | `anthropic/claude-opus-5` | high | 48 | $3.61 | 16.96 s | 66 (Claude Code) |
 | `vision` | `anthropic/claude-opus-5` | medium | 45 | $2.19 | 3.79 s | 64 (Claude Code) |
@@ -19,17 +19,19 @@ against.
 | `tiny` | `openai-codex/gpt-5.6-luna` | low | 22 | n/a | 1.78 s | 25 (Codex) |
 | `fable` | `anthropic/claude-fable-5-1` | medium | 49 | $2.98 | 9.65 s | n/a |
 | `switch_fable` | `anthropic/claude-fable-5-1` | medium | 49 | $2.98 | 9.65 s | n/a |
+| `astra` | `openai-codex/gpt-6-astra` | xhigh | 53 | $2.31 | 161.65 s | n/a |
+| `web` | `web/firecrawl` | n/a | n/a | n/a | n/a | n/a |
 
 The table reports the measured Artificial Analysis figures for each assigned
 model and level. It states no motive that the config or omp's own
 documentation does not establish. AA lists no cost per task for Luna medium
 and low, and no Coding Agent Index for any Astra or Fable 5.1 level except
-max.
+max. AA measures no web search provider, so the `web` row carries no figures.
 
 What omp's settings catalog establishes about these roles:
 
-- `cycleOrder` lists the roles the model switcher cycles, so `fable` is the
-  fourth `Ctrl+P` stop.
+- `cycleOrder` lists the roles the model switcher cycles. `fable` is the
+  fourth `Ctrl+P` stop, and `astra` is the fifth and last stop.
 - `tiny` overrides the model for lightweight background tasks: titles, memory,
   auto-thinking, and unexpected-stop detection.
 - `modelTags` carries role metadata and can introduce roles; `hidden: true`
@@ -44,6 +46,28 @@ are dormant until an OMP agent with that name exists.
 `retry.fallbackChains.task` keeps `anthropic/claude-opus-5:high` as a
 cross-vendor fallback.
 
+`retry.fallbackChains.astra` holds `anthropic/claude-fable-5-1:medium`.
+`retry.fallbackChains.fable` holds `openai-codex/gpt-6-astra:xhigh`.
+Each deliberate cycle stop falls to the other vendor. Without these explicit
+chains, `retry.fallbackChains.default` would send either stop to
+`openai-codex/gpt-5.6-sol:high`.
+Chain entries are concrete selectors, not role aliases, so this pair cannot
+recurse. The hidden `switch_fable` chain stays empty.
+
+`modelRoles.web` is `web/firecrawl`, and `retry.fallbackChains.web` lists the
+explicit 27-entry provider order that follows it. The two keys replace the
+retired `providers.webSearchOrder` key, which omp no longer carries in its
+settings schema. omp still accepts that key in a deployed file, expands it in
+memory into the same two keys, and then drops it, but it never writes the
+expansion back to disk. The kit therefore declares both keys itself.
+
+The chain is the verbatim expansion omp produces today, read back with
+`omp config get retry.fallbackChains`. It must stay complete. An explicit
+chain replaces omp's built-in web order wholesale, so a shortened list drops
+providers instead of reordering them. The first five entries keep the previous
+Firecrawl, Exa, Perplexity, Gemini, Codex preference; the remaining entries
+are omp's own ordering of the providers behind it.
+
 ## Artificial Analysis snapshot
 
 Source: `https://artificialanalysis.ai`, read on 2026-09-08. Every score below
@@ -139,9 +163,14 @@ published numeric cache price. Context 1M.
 Price: $0.20 in, $1.20 out, $0.02 cache read per 1M; no published cache-write
 price. Context 1M. AA lists cost per task only for max and xhigh.
 
-## Why `task` points at Astra low
+## Why `task` returns to Sol high
+
+`task` runs `openai-codex/gpt-5.6-sol:high`. The owner uses Astra only for
+main orchestration, so Astra now has a dedicated `astra` cycle stop at `xhigh`.
+The comparison below records the retired Astra-low choice beside the current
+Sol-high choice and the other measured alternatives.
 
-| Metric | Astra low | Sol high | Sol max | Opus 5 high |
+| Metric | Astra low, retired task | Sol high, current task | Sol max | Opus 5 high |
 |---|---:|---:|---:|---:|
 | Intelligence Index | 46 | 42 | 47 | 48 |
 | Cost per Index task | $0.82 | $0.81 | $1.99 | $3.61 |
@@ -154,58 +183,53 @@ price. Context 1M. AA lists cost per task only for max and xhigh.
 | AA-Briefcase | 1253 | 1361 | 1475 | 1557 |
 | AA-Omniscience | 41 | 20 | 22 | 34 |
 
-Astra low beats the previous `task` model, Sol high, on intelligence, latency,
-and token use at the same cost per task. Astra costs 2.5× per token and spends
-about one third the tokens, so the price rise and the efficiency gain cancel:
-this is a latency and token-budget win, not a cost saving.
-
-Sol medium is the cheaper measured alternative, and it was not chosen: index
-39, Coding Agent Index 62 (Codex), $0.50 per task, 4.90 s TTFT. Against it,
-Astra low costs 64% more per task and scores 7 index points higher, with no
-published Astra coding-agent score at that level.
-
-Two risks come with it. Astra low loses AA-Briefcase, the eval closest to this
-kit's agent workload, and AA publishes no Coding Agent Index score for any Astra
-level except max. Watch reviewer output, because `reviewer` and
-`security-reviewer` inherit `@task`. If review quality drops, pin those agents
-to `anthropic/claude-opus-5:high` rather than reverting the whole role.
-
-## What resolves to Astra low in practice
-
-`modelRoles.task` sets the model. The `:low` suffix alone does not cap every
-spawn. `SoT/.omp/models.yml` restricts the `openai-codex/gpt-6-astra` effort
-ladder to `[low]` through
-`providers.openai-codex.modelOverrides.gpt-6-astra.thinking`. omp clamps any
-requested effort to the model ladder, and `auto` has only one choice. Every
-Astra spawn therefore runs `low`, regardless of its `effort` hint.
+Astra low beat Sol high on intelligence, latency, and token use at effectively
+equal cost per task. It cost $0.82 against $0.81 and used 4k output tokens
+per task against 13k. Its 2.60 s TTFT beat Sol high's 11.26 s.
+That was a latency and token-budget win, not a cost saving.
+The owner reversed that trade on purpose to reserve Astra for interactive
+orchestration.
+
+Sol high scores 64 in the Codex Coding Agent Index and 1361 on AA-Briefcase.
+Astra low scores 1253 on AA-Briefcase. AA publishes no Astra Coding Agent
+Index except max, which scores 67 in Codex.
+The new Astra xhigh cycle stop scores 53 on the Intelligence Index, costs
+$2.31 per index task, and has 161.65 s TTFT.
+It has no published Coding Agent Index.
+
+## How Astra is selected in practice
+
+No subagent role or `task.agentModelOverrides` entry resolves Astra.
+`modelRoles.astra` is reachable only through the model switcher as a main
+orchestrator role. The explicit Fable retry chain can also select Astra.
+No subagent selects Astra automatically.
+
+`SoT/.omp/models.yml` declares the full `low, medium, high, xhigh, max` ladder
+with `defaultLevel: xhigh` under
+`providers.openai-codex.modelOverrides.gpt-6-astra.thinking`.
+The override stays as the kit's worked example of a provider ladder
+redefinition. The in-session thinking control can still select `low` for a
+quick answer.
 
 - The bundled `scout` and `sonic` agents carry `model: "@smol"` and
   `thinking-level: medium` in their embedded frontmatter, so they run Luna,
-  not Astra. To move them, change `modelRoles.smol` or add a
+  not Sol or Astra. To move them, change `modelRoles.smol` or add a
   `task.agentModelOverrides` entry for the agent name.
 - The bundled `task` agent carries `model: "@task"` and
-  `thinking-level: auto`. `auto` classifies each prompt and picks a level for
-  the resolved model, but Astra's ladder permits only `low`.
+  `thinking-level: auto`. It resolves Sol, and `auto` classifies each prompt
+  to choose a thinking level.
 - `task.enableEffort` is `true`, so a caller can pass `effort: lo`, `med`, or
   `hi`, which overrides `auto`.
-- `task.maxEffort` is `high`, so `scout` and `sonic` run Luna `medium` by
-  default and Luna `high` with `effort: hi`.
+- `task.maxEffort` is `max`, so `scout` and `sonic` run Luna `medium` by
+  default and Luna `max` with `effort: hi`.
+- The bundled `reviewer` and `security-reviewer` inherit `@task`, now Sol high.
 - The `code-reviewer` and `plan-reviewer` override entries remain dormant.
-  omp's task tool rejects both names as unknown agents, so neither can spawn.
-
-Fresh `omp -p` runs on 2026-09-09 verified the model ladder with
-`task.maxEffort: high`. Child session logs recorded these results:
+  Both point to `@task`, now Sol high. omp's task tool rejects both names as
+  unknown agents, so neither can spawn.
 
-| Agent | Effort hint | Resolved model and level |
-|---|---|---|
-| `task` | `hi` | `gpt-6-astra:low` |
-| `task` | None, complex prompt | `gpt-6-astra:low` |
-| `reviewer` | `hi` | `gpt-6-astra:low` |
-| `security-reviewer` | None | `gpt-6-astra:low` |
-| `scout` | `hi` | `gpt-5.6-luna:high` |
-| `sonic` | `hi` | `gpt-5.6-luna:high` |
-
-The complex `task` run completed with 682 output tokens.
+The runtime per-agent measurement from fresh `omp -p` runs on 2026-09-09
+predates this change. It applies to the retired Astra-low `task` configuration,
+not the current role map.
 
 omp's 272k context window is the `/extended-context off` window for Astra.
 `/extended-context on` uses the 922k input window, 1.05M total, which matches
@@ -214,8 +238,9 @@ AA's 1M.
 ## Free session launcher (`docks-kit omp`)
 
 `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive
-omp session on a single free model. All 12 model roles resolve to that model.
-All 9 retry fallback chains are empty, so a retry cannot reach a paid model.
+omp session with a configuration overlay that selects a free model. The
+overlay sets all 13 model roles to that model and empties all 10 retry fallback
+chains. Higher-precedence model selection can replace those values.
 The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
 a model that publishes no thinking ladder, where both keys are omitted and the
 deployed values apply.
@@ -235,6 +260,28 @@ Every argument after the launcher flags forwards verbatim to omp. `docks-kit
 omp -p "..."` runs one prompt. `docks-kit omp --continue` resumes the
 previous session. A bare `docks-kit omp` opens an interactive session.
 
+The overlay ranks above the deployed global and project configuration, and
+below runtime overrides and later overlay files. Each input below therefore
+selects a model that the overlay does not control:
+
+- A forwarded later config overlay. The launcher passes its own `--config`
+  first, and omp applies a later overlay file over an earlier one.
+- The runtime model flags `--model`, `--smol`, `--slow`, and `--plan`. The
+  legacy `--provider` flag selects a provider. `--models` sets the model
+  patterns that `Ctrl+P` cycling can reach, so cycling can leave the free
+  model.
+- The model environment variables `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and
+  `PI_PLAN_MODEL`. `PI_CONFIG_FILES` is not in this set, because those files
+  load before `--config` overlays.
+- The in-session model selector. `Alt+M` sets the roles, and `Alt+P` picks a
+  model for the current session only.
+- A restored persisted session model. `--continue`, `--resume`, and
+  `autoResume` restore the model of the session they open, so a session that
+  started under the paid configuration returns to its paid model.
+
+This list names the known selection paths. It is not a closed set. The
+launcher does not reject these inputs today.
+
 The default model is `opencode-zen/muse-spark-1.3-contributor-free` ("Muse
 Spark 1.3 Free", 1,048,576-token context) at `xhigh`. `xhigh` is the ceiling
 of that model ladder: `minimal, low, medium, high, xhigh`. The paid
@@ -258,9 +305,11 @@ committed. `--model <selector>` records one selector and derives both levels
 from the catalog row. `--pick` opens an interactive wizard.
 
 The picker lists only models the live `omp models --json` catalog reports at
-zero input and output cost (26 entries on 2026-09-11). This path cannot start
-a paid session. The catalog can advertise a free model that the account
-cannot call; omp reports that provider error unchanged.
+zero input and output cost (26 entries on 2026-09-11). The resulting overlay
+sets every role to the chosen free model and empties every retry chain.
+Higher-precedence model selection can replace those values. The catalog can
+advertise a free model that the account cannot call; omp reports that provider
+error unchanged.
 
 After the model, the wizard asks about thinking levels. `ompOverlay.ts
 planEffortChoice` decides which questions apply, because omp accepts a
@@ -299,5 +348,6 @@ recorded default and the ladder counts in these docs in the same commit.
 - Record the index version with the numbers. AA changes index composition
   between versions, so a score from another version is not a comparison.
 - Update the capture date in the same commit as any number.
-- Verify changes to the Astra ladder in `SoT/.omp/models.yml` and to
-  `task.maxEffort` together with a fresh `omp -p` spawn per bundled agent.
+- Verify Astra ladder changes in `SoT/.omp/models.yml` through the model
+  switcher and in-session thinking control.
+- Verify `task.maxEffort` changes with a fresh `omp -p` spawn per bundled agent.