docks-kit 0.22.13 → 0.22.22

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 (57) hide show
  1. package/AGENTS.md +97 -83
  2. package/README.md +7 -7
  3. package/cli/docs/command-guards.md +12 -7
  4. package/cli/docs/flags.md +59 -9
  5. package/cli/docs/install.md +2 -2
  6. package/cli/docs/omp-context.md +27 -17
  7. package/cli/docs/omp-models.md +91 -70
  8. package/cli/docs/overview.md +1 -1
  9. package/cli/docs/platforms.md +4 -2
  10. package/cli/docs/plugins.md +8 -5
  11. package/cli/docs/sync-layers.md +6 -4
  12. package/cli/docs/toolchain.md +24 -14
  13. package/cli/src/argv.ts +7 -4
  14. package/cli/src/argvValidate.ts +2 -16
  15. package/cli/src/commands/docs.ts +1 -1
  16. package/cli/src/commands/omp.ts +81 -88
  17. package/cli/src/commands/sync.ts +6 -6
  18. package/cli/src/commands/tidy.ts +83 -26
  19. package/cli/src/engine-native/DESIGN.md +93 -56
  20. package/cli/src/engine-native/atomicWrite.ts +168 -8
  21. package/cli/src/engine-native/codexConfig.ts +2 -6
  22. package/cli/src/engine-native/codexPlugins.ts +1 -1
  23. package/cli/src/engine-native/codexSync.ts +137 -26
  24. package/cli/src/engine-native/codexToml.ts +4 -86
  25. package/cli/src/engine-native/deps.ts +51 -51
  26. package/cli/src/engine-native/exec.ts +3 -0
  27. package/cli/src/engine-native/harnesses.ts +5 -11
  28. package/cli/src/engine-native/index.ts +1 -1
  29. package/cli/src/engine-native/kitDb.ts +7 -7
  30. package/cli/src/engine-native/kitLock.ts +121 -0
  31. package/cli/src/engine-native/modes.ts +49 -31
  32. package/cli/src/engine-native/ompChild.ts +26 -0
  33. package/cli/src/engine-native/ompFastMode.ts +14 -7
  34. package/cli/src/engine-native/ompFileDeploy.ts +12 -6
  35. package/cli/src/engine-native/ompMarketplace.ts +25 -18
  36. package/cli/src/engine-native/ompOverlay.ts +23 -69
  37. package/cli/src/engine-native/ompPlugins.ts +23 -14
  38. package/cli/src/engine-native/ompRemovals.ts +97 -30
  39. package/cli/src/engine-native/ompSync.ts +66 -32
  40. package/cli/src/engine-native/os/targets.ts +16 -4
  41. package/cli/src/engine-native/os/types.ts +1 -1
  42. package/cli/src/engine-native/parseArgs.ts +27 -17
  43. package/cli/src/engine-native/processes.ts +16 -0
  44. package/cli/src/engine-native/scratch.ts +18 -0
  45. package/cli/src/engine-native/sharedTypes.d.ts +0 -2
  46. package/cli/src/engine-native/skillsInstall.ts +27 -2
  47. package/cli/src/engine-native/skillsPrune.ts +51 -49
  48. package/cli/src/engine-native/skillsRecords.ts +138 -0
  49. package/cli/src/engine-native/skillsSync.ts +16 -13
  50. package/cli/src/engine-native/syncDispatch.ts +186 -4
  51. package/cli/src/engine-native/tidy.ts +102 -119
  52. package/cli/src/engine-native/tomlLines.ts +92 -0
  53. package/cli/src/generated/sotPayload.ts +5 -5
  54. package/cli/src/main.ts +5 -30
  55. package/cli/src/manifests.ts +24 -4
  56. package/package.json +2 -2
  57. package/cli/src/engine-native/tidyLock.ts +0 -163
package/cli/docs/flags.md CHANGED
@@ -26,11 +26,11 @@ Escape leaves it unchanged.
26
26
 
27
27
  | Flag | Effect |
28
28
  |------|--------|
29
- | `--dry-run` | Preview without applying |
29
+ | `--dry-run` | Preview without applying; takes no sync lock and no folder lock |
30
30
  | `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
31
- | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
31
+ | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, and the universal skills that `~/.agents/.kit-owned-skills` names |
32
32
  | `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
33
- | `--skip-plugin-refresh` | Install missing Claude/Codex plugins but skip refresh-only updates |
33
+ | `--skip-plugin-refresh` | Install missing Claude, Codex, and omp plugins but skip refresh-only updates |
34
34
  | `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
35
35
 
36
36
  ## Environment overrides
@@ -38,6 +38,54 @@ Escape leaves it unchanged.
38
38
  | Variable | Effect |
39
39
  |----------|--------|
40
40
  | `DOCKS_KIT_SYNC_CONCURRENCY=1\|2\|3` | Maximum selected sync pipelines running at once. Default `3`; use `1` for serial golden/debug execution. Invalid values fail `sync` with exit 2 but do not affect `model` or `toolchain`. |
41
+ | `DOCKS_KIT_SYNC_LOCK_WAIT_MS=<ms>` | Time that `sync`, a `model` write, and `omp --fast` wait for another sync to release a sync lock. A non-negative safe integer in milliseconds (at most `9007199254740991`); unset or empty means `120000` (120 s). Any other value prints `DOCKS_KIT_SYNC_LOCK_WAIT_MS must be a non-negative safe integer` and exits 2. |
42
+
43
+ ## Sync lock
44
+
45
+ `sync` and `model <tool> <value>` hold the lock
46
+ `~/.cache/docks-kit/sync-lock.db` while they run, so two runs never write the
47
+ same files at once.
48
+
49
+ - A run waits up to 120 s for another run to release the lock
50
+ (`DOCKS_KIT_SYNC_LOCK_WAIT_MS` changes the wait). It then prints
51
+ `another docks-kit sync holds <path>; run sync again after it ends` and
52
+ exits 1 with no change.
53
+ - Two homes can share a Codex folder (`CODEX_HOME`), an agents folder
54
+ (`AGENTS_DIR`), or an omp folder (`PI_CODING_AGENT_DIR`, `PI_CONFIG_DIR`,
55
+ `XDG_DATA_HOME`, or a symlink). So a writing sync also holds
56
+ `.docks-kit-sync-lock.db` inside each such folder that it writes. For `codex`
57
+ this is the Codex folder, and for `agents` the agents folder. For `omp` it is
58
+ the omp agent folder, the intercom folder, and the omp data root. A
59
+ `model codex <value>` write holds the Codex folder lock too. The held line
60
+ then names that lock file.
61
+ - A writing sync creates a missing folder of this set just before it takes the
62
+ lock of that folder, after the locks of its ancestors in the set. Each folder
63
+ that it creates gets mode 0700. The lock step does not change the mode of an
64
+ existing folder. The omp pipeline then sets mode 0700 on the omp agent folder
65
+ and the intercom folder.
66
+ - A sync finds the omp folders once, before it takes the locks. The omp
67
+ pipeline and each `omp` command that it starts use these folders. When the
68
+ locked data root is the omp config root, each `omp` command starts without
69
+ `XDG_DATA_HOME`. So a `$XDG_DATA_HOME/omp` folder that appears during the
70
+ sync does not move the plugin data to a folder without a lock. A later
71
+ `omp` uses that new folder, so the sync then prints
72
+ `omp data root moved to <root> during the sync; run docks-kit sync again`
73
+ and exits 1. The next sync locks the new folder and installs the plugins
74
+ there.
75
+ - The locks cover the folder that the kit writes into, not the target of a
76
+ symlinked file. Two homes whose `config.yml` (or another deployed file) links
77
+ to one shared file can still overwrite the merge of each other.
78
+ - `docks-kit omp --fast` checks `config.yml` before it takes a lock. When the
79
+ file is missing, it exits 2 and creates no omp folder. Otherwise it holds the
80
+ sync lock and the omp agent folder lock while it rewrites `config.yml`. The
81
+ wait and the held line are those of a sync.
82
+ - A run with `--dry-run`, `-h`, or `--help` takes no lock. A dry run through
83
+ the `DRY_RUN=1` env global of the private `native-raw` engine channel takes
84
+ no lock either. `model <tool>` without a value only reads, so it takes no
85
+ lock.
86
+ - The lock goes when the run ends, also when the process is killed.
87
+ - A held lock also delays the error of an invalid argument until the wait
88
+ ends.
41
89
 
42
90
  ## Per-tool flags
43
91
 
@@ -60,7 +108,7 @@ ignored with a warning; Claude modifiers never touch Codex config and vice versa
60
108
 
61
109
  | Flag | Effect |
62
110
  |------|--------|
63
- | `--model <selector>` | Session model for this run and later runs; rejected unless the live catalog reports zero input and output cost; recorded in `~/.docks-kit/kit.db` (table `omp_session`) |
111
+ | `--model <selector>` | Session model for this run and later runs; rejected unless the live catalog reports zero input and output cost with `pricingStatus` `free` or `unknown`; recorded in `~/.docks-kit/kit.db` (table `omp_session`) |
64
112
  | `--pick` | Interactive picker over free catalog models; records the choice the same way |
65
113
  | `--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 |
66
114
 
@@ -77,10 +125,11 @@ The launcher rejects a forwarded `--config`, `--model`, `--smol`, `--slow`,
77
125
  in the `--flag value` and the `--flag=value` form and also after a `--`. It
78
126
  exits with code 2 before omp starts. The error names the flag and the
79
127
  recoveries: `--model <selector>` before the other arguments or `--pick` for a
80
- free model, `omp` directly for a paid model, and `PI_CONFIG_FILES` for another
81
- config file. The launcher sets `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and
82
- `PI_PLAN_MODEL` to the free role values, warns once for each exported value
83
- that it replaces, and appends the overlay to `PI_CONFIG_FILES`. See
128
+ free model, and `omp` directly for a paid model. For a forwarded `--config`, it
129
+ also names `PI_CONFIG_FILES` for another config file. The launcher sets
130
+ `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and `PI_PLAN_MODEL` to the free role values,
131
+ warns once for each exported value that it replaces, and appends the overlay
132
+ to `PI_CONFIG_FILES`. See
84
133
  [omp-models.md](omp-models.md#free-session-launcher-docks-kit-omp) for the
85
134
  full policy and the paths that stay outside the launcher.
86
135
 
@@ -105,7 +154,7 @@ forwarded `--model` stops the launcher with exit 2, also behind `--`.
105
154
  | `scratch new <label>` | Create a private directory (mode 0700) `~/.cache/docks-kit/scratch/<label>-XXXXXX` and print its path; the label matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` |
106
155
  | `scratch remove <path>...` | Remove each path whose real path is strictly inside the scratch root, the system temporary directory, or `/var/tmp`; print `removed <path>` or `refused <path>: <reason>`; exit 1 when any path is refused |
107
156
  | `tidy` | List the safe leftover actions (`remove`, `stop`) and the kept candidates (`keep`) with reasons; change nothing |
108
- | `tidy --apply` | Perform those actions under the lock `~/.cache/docks-kit/tidy.lock` and append the outcomes to `~/.cache/docks-kit/tidy.log`; exit 1 when an action fails |
157
+ | `tidy --apply` | Take the lock `~/.cache/docks-kit/tidy-lock.db`, then plan, perform those actions, and append the outcomes to `~/.cache/docks-kit/tidy.log`; exit 1 when an action fails. When another run holds the lock, print only `another docks-kit tidy run holds <path>`, with no plan and no report, and exit 0. A dry run (`tidy` without `--apply`) and the `--report` sections take no lock |
109
158
  | `tidy --repo <path>` | Take the worktree candidates only from that repository, at any location |
110
159
  | `tidy --report` | After the plan, print read-only sections on memory, temporary directories, processes, Docker, caches, Trash, git, agent histories, scheduled jobs, and global installs |
111
160
 
@@ -121,3 +170,4 @@ Old flags exit with a rename hint — there is no compat behavior.
121
170
  | `--680k` | `--claude-compact-window=680k` |
122
171
  | `--permissive` | `--claude-permissive` |
123
172
  | `--supabase` / `--n8n` | `--claude-plugin=supabase` / `--claude-plugin=n8n` |
173
+ | `--skip-rtk` | `--skip-bubblewrap` |
@@ -113,8 +113,8 @@ installed plugins even when the kit is already current. Pass `--no-sync`, then
113
113
  run `docks-kit sync --skip-plugin-refresh` to skip the refresh-only work.
114
114
  A compiled binary inside a checkout updates the checkout; on the next invocation
115
115
  the launcher bypasses that now-stale binary and uses updated source until rebuilt.
116
- Every `docks-kit sync` also does a best-effort behind-upstream check and
117
- nudges when the checkout is stale (silent offline / detached / no git).
116
+ Every `docks-kit sync` except `--dry-run` also does a best-effort behind-upstream
117
+ check and nudges when the checkout is stale (silent offline / detached / no git).
118
118
 
119
119
  ## Recovering a broken global install
120
120
 
@@ -1,7 +1,7 @@
1
1
  # omp context and compaction
2
2
 
3
- This topic records why `SoT/.omp/config.yml` does not pin a compaction
4
- threshold, and what omp's reserve-based default computes on each model lane.
3
+ This topic records why `SoT/.omp/config.yml` ships no compaction threshold,
4
+ and what omp's reserve-based default computes on each model lane.
5
5
 
6
6
  ## How omp resolves the trigger
7
7
 
@@ -9,8 +9,10 @@ threshold, and what omp's reserve-based default computes on each model lane.
9
9
  `packages/agent/src/compaction/compaction.ts` selects the trigger from three
10
10
  branches, in priority order.
11
11
 
12
- 1. A positive `compaction.thresholdTokens` wins. omp clamps it to the range 1
13
- through `contextWindow - 1`.
12
+ 1. A positive `compaction.thresholdTokens` wins. A value below the window is
13
+ exact. For a value at or above the window, the behavior depends on the omp
14
+ release. omp 18.4.4 through 18.8.7 clamps the value to `contextWindow - 1`.
15
+ omp 18.8.8 and later fall back to the reserve-based budget of branch 3.
14
16
  2. Otherwise a positive `compaction.thresholdPercent` applies. omp clamps the
15
17
  percent to the range 1 through 99 and computes
16
18
  `floor(contextWindow * percent / 100)`.
@@ -31,10 +33,11 @@ constant.
31
33
 
32
34
  | Lane | Window | Reserve | Threshold | Percent of window |
33
35
  |---|---:|---:|---:|---:|
34
- | `openai-codex/*` | 272,000 | 40,800 | 231,200 | 85.0% |
36
+ | `openai-codex/gpt-6-astra`, `openai-codex/gpt-6-luna` | 272,000 | 40,800 | 231,200 | 85.0% |
37
+ | `openai-codex/gpt-6.1-sol`, `openai-codex/gpt-6.1-terra` | 500,000 | 75,000 | 425,000 | 85.0% |
35
38
  | `anthropic/*` | 1,000,000 | 150,000 | 850,000 | 85.0% |
36
39
 
37
- Both lanes compact at the same fraction of their own window. The absolute
40
+ Every lane compacts at the same fraction of its own window. The absolute
38
41
  trigger differs only because the windows differ.
39
42
 
40
43
  ## Why the kit no longer pins 231200
@@ -59,17 +62,20 @@ No session ran past its window, and omp raised no warning on either lane.
59
62
  Under the reserve-based default none of the 75 Anthropic compactions would
60
63
  have fired, because no session reached 850,000.
61
64
 
62
- ## Why the key ships as -1 rather than being deleted
65
+ ## How sync removes the deployed pin
66
+
67
+ The kit no longer ships `compaction.thresholdTokens`. omp's schema default
68
+ `-1` applies, and that sentinel selects the reserve-based branch.
63
69
 
64
70
  `ompYaml.ts` `mergeOmpConfig` is additive. Its `mergeMappings, deployed-key
65
71
  retention loop` returns every deployed key that the SoT omits to the merged
66
72
  output, and the only drop predicate is `dropFallbackWildcard`, which is scoped
67
- to `retry.fallbackChains`.
73
+ to `retry.fallbackChains`. A key deleted from the SoT therefore stays in every
74
+ already-deployed `~/.omp/agent/config.yml`.
68
75
 
69
- Deleting the key from the SoT would therefore leave the stale `231200` in
70
- every already-deployed `~/.omp/agent/config.yml` permanently. A present key
71
- holding the schema default sentinel `-1` overwrites that stale value on the
72
- next sync.
76
+ `ompRemovals.ts OMP_RETIRED_VALUES` therefore records both values that the kit
77
+ shipped: the former `231200` pin and the later `-1`. Sync prunes the deployed
78
+ key only while it holds one of these values, so a user value survives.
73
79
 
74
80
  Verify the deployed value after a sync:
75
81
 
@@ -77,14 +83,18 @@ Verify the deployed value after a sync:
77
83
  omp config get compaction.thresholdTokens
78
84
  ```
79
85
 
80
- The command must print `-1`.
86
+ The command must print `-1`, the omp default, unless the user set another
87
+ value.
81
88
 
82
89
  ## The clamp hazard a fixed pin carries
83
90
 
84
- The fixed-token branch clamps the pinned value to `contextWindow - 1`. On any
85
- model whose window is below the pinned value, the reserve collapses to one
86
- token, so omp compacts only once the context is already full. The
87
- reserve-based default always leaves at least 15% of the window free.
91
+ In omp 18.4.4 through 18.8.7, the fixed-token branch clamps the pinned value
92
+ to `contextWindow - 1`. On any model whose window is at or below the pinned
93
+ value, the reserve collapses to one token, so omp compacts only once the
94
+ context is already full. omp 18.8.8 and later fall back to the reserve-based
95
+ budget for such a pin, so this collapse does not occur there. The kit floor is
96
+ omp 18.4.4, so a supported host can still have the clamp. The reserve-based
97
+ default always leaves at least 15% of the window free.
88
98
 
89
99
  No current role model has a window below 272,000, so the hazard was latent
90
100
  rather than live. Not pinning removes it entirely, including for any future
@@ -12,13 +12,12 @@ against.
12
12
  | `slow` | `anthropic/claude-opus-5-5` | xhigh | 56 | $3.46 | 136.30 s |
13
13
  | `plan` | `anthropic/claude-opus-5-5` | xhigh | 56 | $3.46 | 136.30 s |
14
14
  | `task` | `anthropic/claude-opus-5-5` | high | 54 | $1.82 | 52.85 s |
15
- | `advisor` | `anthropic/claude-opus-5-5` | medium | 51 | $1.34 | 21.87 s |
16
15
  | `designer` | `anthropic/claude-opus-5-5` | high | 54 | $1.82 | 52.85 s |
17
16
  | `vision` | `anthropic/claude-opus-5-5` | medium | 51 | $1.34 | 21.87 s |
18
17
  | `smol` / `commit` | `openai-codex/gpt-6-luna` | medium | 29 | $0.02 | n/a |
19
18
  | `tiny` | `openai-codex/gpt-6-luna` | low | 21 | $0.0045 | 2.18 s |
20
- | `fable` | `anthropic/claude-fable-5-1` | medium | 49 | $2.98 | 8.00 s |
21
- | `switch_fable` | `anthropic/claude-fable-5-1` | medium | 49 | $2.98 | 8.00 s |
19
+ | `fable` | `anthropic/claude-fable-5-2` | medium | 56 (v5.0.1) | $3.80 (v5.0.1) | 11.23 s (v5.0.1) |
20
+ | `switch_fable` | `anthropic/claude-fable-5-2` | medium | 56 (v5.0.1) | $3.80 (v5.0.1) | 11.23 s (v5.0.1) |
22
21
  | `astra` | `openai-codex/gpt-6-astra` | xhigh | 52 | $2.31 | 126.90 s |
23
22
  | `reviewer` | `openai-codex/gpt-6.1-terra` | high | 42 (v5.0.1) | $0.26 (v5.0.1) | 10.91 s (v5.0.1) |
24
23
  | `web` | `web/firecrawl` | n/a | n/a | n/a | n/a |
@@ -27,10 +26,11 @@ The table reports the measured Artificial Analysis figures for each assigned
27
26
  model and level. It states no motive that the config or omp's own
28
27
  documentation does not establish. AA has not measured output speed or latency
29
28
  for GPT-6 Luna medium, so that row carries `n/a` for TTFT. AA measures no web
30
- search provider, so the `web` row carries no figures. The `reviewer` row comes
31
- from a later capture at Intelligence Index v5.0.1. The 2026-09-29 capture
32
- predates GPT-6.1 Terra. Compare that row only with other v5.0.1 figures (see
33
- GPT-6.1 Terra below). A review benchmark chose the model of that role
29
+ search provider, so the `web` row carries no figures. The `reviewer`, `fable`,
30
+ and `switch_fable` rows come from later captures at Intelligence Index v5.0.1.
31
+ The 2026-09-29 capture predates GPT-6.1 Terra and Fable 5.2. Compare those
32
+ rows only with other v5.0.1 figures (see GPT-6.1 Terra and Claude Fable 5.2
33
+ below). A review benchmark chose the model of the `reviewer` role
34
34
  (DocksDocks/public#130), not these figures. The tier of that role follows the
35
35
  main session (DocksDocks/public#134).
36
36
 
@@ -116,7 +116,7 @@ missed two pre-registered bounds: escaped difference up to 3.26 (bound 2) and
116
116
  recall difference down to -0.07 (bound -0.05). Both intervals include 0, and
117
117
  the user judged the difference as noise.
118
118
 
119
- `retry.fallbackChains.astra` holds `anthropic/claude-fable-5-1:medium`.
119
+ `retry.fallbackChains.astra` holds `anthropic/claude-fable-5-2:medium`.
120
120
  `retry.fallbackChains.fable` holds `openai-codex/gpt-6-astra:xhigh`.
121
121
  Each deliberate cycle stop falls to the other vendor. Without these explicit
122
122
  chains, `retry.fallbackChains.default` would send either stop to
@@ -124,22 +124,21 @@ chains, `retry.fallbackChains.default` would send either stop to
124
124
  Chain entries are concrete selectors, not role aliases, so this pair cannot
125
125
  recurse. The hidden `switch_fable` chain stays empty.
126
126
 
127
- ### Why `advisor` runs Opus 5.5 medium
128
-
129
- `advisor` runs `anthropic/claude-opus-5-5:medium` with an empty fallback
130
- chain. On 2026-09-24, with omp 18.3.0, an Opus 5.5 session with the advisor
131
- on `openai-codex/gpt-6-sol:medium` looped. In one session the advisor made
132
- 1,313 requests for 140 main-agent requests. It issued 1,272 `read` calls on
133
- 248 distinct paths, read one 3-line slice 249 times, and never called
134
- `advise`. The advisor prompt averaged about 317k tokens, above the 272K
135
- window omp lists for GPT-6 Sol. With the advisor on Opus 5.5 medium, the
136
- same kind of session made about one advisor request per main-agent request
137
- and called `advise` normally. The owner excluded GPT-6 Sol from the advisor
138
- role and its fallback chain. On 2026-09-29 the owner extended the exclusion to
139
- every GPT model, including GPT-6.1 Sol and GPT-6 Astra. No GPT model was
140
- tested as the advisor again, and Astra costs too much for this role. Do not
141
- put an `openai-codex/gpt-*` selector in `modelRoles.advisor` or
142
- `retry.fallbackChains.advisor`.
127
+ ### Advisor removed
128
+
129
+ By owner decision (2026-11-12, 0.22.22), the kit sets no omp advisor.
130
+ `SoT/.omp/config.yml` has no `advisor` block, no `modelRoles.advisor`, and no
131
+ `retry.fallbackChains.advisor`. omp keeps the advisor off by default. The
132
+ plan-lifecycle verification loop takes its place: acceptance checks, a fresh
133
+ code review of the diff, and a round limit. Since 2026-11-01, 33 main
134
+ sessions had an advisor log, and no subagent session had one. A session that
135
+ runs `/advisor on` takes its advisor model from the `slow` role, because no
136
+ `advisor` role is set.
137
+
138
+ History: on 2026-09-24, with omp 18.3.0, an advisor on
139
+ `openai-codex/gpt-6-sol:medium` looped and made 1,313 requests for 140
140
+ main-agent requests. The kit then ran the advisor on Opus 5.5 `medium` and
141
+ excluded every GPT model from that role until this removal.
143
142
 
144
143
  `modelRoles.web` is `web/firecrawl`, and `retry.fallbackChains.web` lists the
145
144
  explicit 20-entry provider order that follows it. The two keys replace the
@@ -254,6 +253,34 @@ selector, so no kit role depends on that default. Runs on
254
253
  `anthropic/claude-opus-5-5:high` and `:max` after the prune answered with
255
254
  exit 0.
256
255
 
256
+ ### Claude Fable 5.2 (Anthropic) - `anthropic/claude-fable-5-2`
257
+
258
+ Source: `https://artificialanalysis.ai`, read on 2026-11-12 at Intelligence
259
+ Index v5.0.1, from the metric table of
260
+ `/models/comparisons/<level-slug>-vs-gpt-5-6-sol-high`. AA serves `max` under
261
+ the bare model slug. These figures use another index version than the rest of
262
+ this snapshot, so they do not compare with the v4.3.2 rows above. Compare them
263
+ with GPT-6.1 Terra below.
264
+
265
+ | Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
266
+ |---|---:|---:|---:|---:|---:|---:|---:|
267
+ | max | 65 | $26.54 | 274k | 275M | 98 | 262.29 | 60% |
268
+ | xhigh | 62 | $14.83 | 162k | 144M | 102 | 85.87 | 62% |
269
+ | high | 62 | $9.08 | 98k | 85M | 97 | 27.98 | 60% |
270
+ | medium | 56 | $3.80 | 43k | 41M | 93 | 11.23 | 55% |
271
+ | low | 54 | $3.10 | 36k | 35M | 97 | 8.42 | 55% |
272
+
273
+ Price: $8.00 in, $40.00 out, $0.20 cache hit per 1M. The omp catalog lists
274
+ the same prices, a $10.00 cache write, a 1M context, and 128K maximum output.
275
+ All AA levels run with default fallback. On 2026-11-12, omp 18.19.0 listed
276
+ `claude-fable-5-2` at low, medium, high, xhigh, and max, and an
277
+ `omp -p --mode json --model anthropic/claude-fable-5-2:medium` run recorded
278
+ `claude-fable-5-2` as the serving model.
279
+
280
+ `fable` and `switch_fable` moved from Fable 5.1 to Fable 5.2 at the same
281
+ level, `medium`. The Fable 5.1 table below stays as the previous-generation
282
+ baseline at v4.3.2.
283
+
257
284
  ### Claude Fable 5.1 (Anthropic) - `anthropic/claude-fable-5-1`
258
285
 
259
286
  | Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
@@ -346,7 +373,7 @@ has measured both at the other levels.
346
373
  ### GPT-5.6 Sol (OpenAI) - previous generation
347
374
 
348
375
  The role map no longer uses GPT-5.6 Sol. This table stays as the measured
349
- baseline for the current Sol task role.
376
+ baseline for the GPT-6.1 Sol `task` retry fallback.
350
377
 
351
378
  | Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
352
379
  |---|---:|---:|---:|---:|---:|---:|---:|
@@ -442,18 +469,18 @@ quick answer.
442
469
  `thinking-level: auto`. It resolves Opus 5.5 high. The `:high` suffix on
443
470
  `modelRoles.task` is an explicit level, so it outranks the agent's `auto`,
444
471
  and the auto classifier does not run for a `task` spawn.
445
- - `task.enableEffort` is `false`, so the task tool has no `effort` field and
446
- every spawn runs the level of its agent's role. When the field is on, a
447
- caller can pass `effort: lo`, `med`, or `hi`, and caller effort outranks the
448
- role suffix. omp maps it onto the model's own ladder, not onto level names:
449
- `lo` selects the lowest level, `med` the lower middle, and `hi` the highest
450
- (`resolveTaskEffortLevel` in omp's `packages/tui/src/thinking.ts`,
451
- omp 18.8.5). Then omp caps the result at `task.maxEffort`. On the
452
- `low, medium, high, xhigh, max` ladder, `hi` gave `xhigh` under the
453
- `xhigh` cap, so many `task` spawns ran Opus 5.5 xhigh despite the `:high`
454
- role suffix. On 2026-11-05, a fresh `omp -p` run on omp 18.16.0 with the
455
- field off had no `effort` field, and its `task` child recorded
456
- `resolvedModel: anthropic/claude-opus-5-5:high`.
472
+ - `task.enableEffort` stays at omp's default `false`, so the task tool has no
473
+ `effort` field and every spawn runs the level of its agent's role. When the
474
+ field is on, a caller can pass `effort: lo`, `med`, or `hi`, and caller
475
+ effort outranks the role suffix. omp maps it onto the model's own ladder,
476
+ not onto level names: `lo` selects the lowest level, `med` the lower middle,
477
+ and `hi` the highest (`resolveTaskEffortLevel` in omp's
478
+ `packages/tui/src/thinking.ts`, omp 18.8.5). Then omp caps the result at
479
+ `task.maxEffort`. On the `low, medium, high, xhigh, max` ladder, `hi` gave
480
+ `xhigh` under the `xhigh` cap, so many `task` spawns ran Opus 5.5 xhigh
481
+ despite the `:high` role suffix. On 2026-11-05, a fresh `omp -p` run on omp
482
+ 18.16.0 with the field off had no `effort` field, and its `task` child
483
+ recorded `resolvedModel: anthropic/claude-opus-5-5:high`.
457
484
  - `task.maxEffort` is `xhigh`. With `task.enableEffort` off, the cap applies
458
485
  only to a per-call `model` with a `:level` suffix.
459
486
  - In the deployed config, `scout` and `sonic` run GPT-6 Luna `medium`. The
@@ -475,10 +502,13 @@ AA's 1M.
475
502
  `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive
476
503
  omp session with a configuration overlay that selects a free model. The
477
504
  overlay sets the 16 chat-model roles in `ompOverlay.ts ROLE_ORDER` to that
478
- model and empties the 13 retry fallback chains in `ompOverlay.ts
479
- FALLBACK_ORDER`. These roles include `memory` and `judge`. The SoT does
480
- not set them, but omp otherwise uses its built-in priority chain for them,
481
- and that chain can name a paid model. The overlay also empties the retry
505
+ model and empties the 12 retry fallback chains in `ompOverlay.ts
506
+ FALLBACK_ORDER`. These roles include `memory`, `judge`, and `advisor`. The SoT
507
+ does not set them, but omp otherwise uses its built-in priority chain for
508
+ `memory` and `judge`, and that chain can name a paid model. omp resolves the
509
+ `/advisor on` model from `modelRoles.advisor` before the `slow` role. A
510
+ deployed, user, or project `advisor` role could otherwise send it to a paid
511
+ model. The overlay also empties the retry
482
512
  chains keyed by the free model: the bare selector, `<selector>:off`, and
483
513
  `<selector>:<level>` for every level in `ompOverlay.ts THINKING_LADDER`. omp
484
514
  uses a chain keyed by the model before a role chain, so a project or
@@ -491,16 +521,16 @@ stays in the merged config. A retry of the free model does not reach such a
491
521
  chain, because omp uses the empty chain keyed by the free model first.
492
522
  The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
493
523
  a model that publishes no thinking ladder, where both keys are omitted and the
494
- deployed values apply.
524
+ deployed or omp default values apply.
495
525
 
496
526
  The launcher renders a run overlay to
497
527
  `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
498
528
  through omp's repeatable `--config` flag. Each distinct model-and-level
499
529
  combination gets its own file, because omp re-reads a changed overlay during
500
- a live session, and a second launcher must not change the levels of that
530
+ a live session, and a second launcher must not change the level of that
501
531
  session. The name sanitizes the selector for the file system and appends a
502
- digest of the rendered overlay. The digest covers the selector and both
503
- levels, so two selectors that differ only in separator characters stay
532
+ digest of the rendered overlay. The digest covers the selector and the
533
+ level, so two selectors that differ only in separator characters stay
504
534
  apart. A session launch never reads or writes `~/.omp/agent/config.yml` or
505
535
  `models.yml`; only `--fast`, below, edits `config.yml`. It
506
536
  never touches the SoT. The next plain `omp` run uses the paid configuration
@@ -576,11 +606,9 @@ Spark 1.3 Free", 1,048,576-token context) at `xhigh`. `xhigh` is the ceiling
576
606
  of that model ladder: `minimal, low, medium, high, xhigh`. The paid
577
607
  `muse-spark-1.3` sibling also offers `max`. The free variant does not.
578
608
 
579
- Both levels come from the ladder of the chosen model, never from a fixed
580
- list. The session level is the ceiling of that ladder. The advisor level is
581
- the highest level at or below `medium`, because the advisor performs quick
582
- review passes. When every level of a ladder is above `medium`, the advisor
583
- takes the lowest level, so it never becomes the most expensive role.
609
+ The level comes from the ladder of the chosen model, never from a fixed list.
610
+ Every role, `advisor` included, runs the same level. Under `--model`, that
611
+ level is the ceiling of the ladder.
584
612
 
585
613
  Free ladders are not uniform. On 2026-09-11 the 26 free models published six
586
614
  distinct ladders: 21 include `medium`, 3 stop at `low, high, max` or
@@ -590,7 +618,7 @@ fail when the session starts.
590
618
 
591
619
  The choice persists per machine in `~/.docks-kit/kit.db` (table
592
620
  `omp_session`), next to the harness selection. It survives across sessions. It is never
593
- committed. `--model <selector>` records one selector and derives both levels
621
+ committed. `--model <selector>` records one selector and derives the level
594
622
  from the catalog row. `--pick` opens an interactive wizard.
595
623
 
596
624
  The picker lists only models the live `omp models --json` catalog reports at
@@ -598,31 +626,24 @@ zero input and output cost with `pricingStatus` `free` or `unknown` (26
598
626
  entries on 2026-09-11). A zero-cost row with another status, such as
599
627
  `variable` or `included`, is billed outside the token price, so the picker
600
628
  leaves it out. The resulting overlay sets the 16 `ROLE_ORDER` roles to the
601
- chosen free model and empties the 13 `FALLBACK_ORDER` chains and the chains
629
+ chosen free model and empties the 12 `FALLBACK_ORDER` chains and the chains
602
630
  keyed by that model. The `web` role, its chain, and each other deployed chain
603
631
  keep the deployed values. The
604
632
  catalog can advertise a free model that the account cannot call; omp reports
605
633
  that provider error unchanged.
606
634
 
607
- After the model, the wizard asks about thinking levels. `ompOverlay.ts
608
- planEffortChoice` decides which questions apply, because omp accepts a
635
+ After the model, the wizard asks about the thinking level. `ompOverlay.ts
636
+ planEffortChoice` decides whether the question applies, because omp accepts a
609
637
  `:level` suffix only for a level the chosen model publishes:
610
638
 
611
639
  - No ladder: the wizard asks nothing and the overlay omits every level.
612
640
  - One level: the wizard states that level and asks nothing.
613
- - Two or more levels: the wizard asks whether every role uses the same
614
- level. Yes takes the highest level the model offers. No asks one level for
615
- all roles except the advisor, then one level for the advisor.
616
-
617
- The advisor question leads with a recommendation from `ompOverlay.ts
618
- advisorRecommendation`: two steps down the model own ladder, clamped to the
619
- lowest level that model publishes. The recommendation is the first row
620
- because `Prompt.Select` starts on the first entry and accepts no initial
621
- index, so `Enter` takes it. The full ladder follows in ladder order. A
622
- recommendation equal to the chosen level is omitted rather than duplicated.
641
+ - Two or more levels: the wizard asks one question, the thinking level for
642
+ every role. It lists the levels of the model from the highest down, so
643
+ `Enter` keeps the highest level.
623
644
 
624
- A session whose advisor differs from the other roles reports both on the
625
- launch line.
645
+ The launch line names the selector and the level, or the model default level
646
+ for a model without a ladder. It reports no separate advisor level.
626
647
 
627
648
  An omp login is required. The kit owns no login flow. Every launch reads the
628
649
  live free catalog of each candidate profile. A plain launch checks the
@@ -647,9 +668,9 @@ stops the launcher before omp starts.
647
668
 
648
669
  When the catalog renames the free variant, change only the default selector
649
670
  constant. Until then, a plain launch on that default stops with an error. A
650
- ladder change needs no code change. Under `--model` both levels are derived
671
+ ladder change needs no code change. Under `--model` the level is derived
651
672
  from the catalog row of the chosen model, and under `--pick` the user chooses
652
- them from the ladder that same row publishes. Refresh the recorded default
673
+ it from the ladder that same row publishes. Refresh the recorded default
653
674
  and the ladder counts in these docs in the same commit.
654
675
 
655
676
  ## OpenAI fast mode (`docks-kit omp --fast`)
@@ -670,8 +691,8 @@ The four review agents inherit the live tier of the main session
670
691
  and on standard processing when it is `none`. A running session keeps the tier
671
692
  it started with, so its reviewers do not follow a later toggle.
672
693
 
673
- `--fast` never changes the Anthropic tier, and sync sets the deployed
674
- `tier.anthropic` to the SoT value `none`, so each session starts with it. In omp
694
+ `--fast` never changes the Anthropic tier. The SoT leaves `tier.anthropic` at
695
+ omp's default `none`, so each session starts with it. In omp
675
696
  18.16.0, `/fast on` in a session whose current
676
697
  model is Anthropic sets `anthropic: priority` for that session. The reviewers
677
698
  then inherit it, so their Opus 5.5 fallback also runs fast. omp has no
@@ -12,7 +12,7 @@ AI-assisted dev environment on every machine.
12
12
  | `SoT/.claude/` | Claude Code config (settings template, Bun runtime programs, CLAUDE.md) |
13
13
  | `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
14
14
  | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
15
- | `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom |
15
+ | `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom, plus the `plugin/` tree, deployed to `~/.docks-kit/omp-plugin` and linked as the `docks-kit-omp` omp plugin |
16
16
  | `SoT/models.json` | Curated Claude and Codex aliases, notes, and offline fallback for the live model lists (see `docks-kit docs models`) |
17
17
  | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
18
18
  | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
@@ -18,5 +18,7 @@ Rosetta reports `x86_64` and gets the unsupported-host message, so run
18
18
  docks-kit from a native arm64 shell.
19
19
 
20
20
  EngineNative is the only supported engine on supported hosts.
21
- `DOCKS_KIT_ENGINE=bash` exits with the removed-engine message and points at the
22
- `bash-engine-final` tag for historical recovery.
21
+ When `DOCKS_KIT_ENGINE=bash` is set, the commands that run the engine (`sync`,
22
+ `model`, `toolchain`, `status`) exit 2 with the removed-engine message. The
23
+ message points at the `bash-engine-final` tag for historical recovery. Other
24
+ commands ignore the variable.
@@ -38,11 +38,14 @@ A marketplace or plugin command that exits non-zero is warned in place AND
38
38
  recorded, then listed under a `--- Failures ---` block after the summary; the
39
39
  sync exits 1. A stale plugin therefore no longer looks like a clean sync.
40
40
 
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
+ Not a failure: a missing harness CLI, missing git, and a missing LSP, Bun, or
42
+ `pi-intercom` pin in `SoT/toolchain.json`. Those stay warn-and-skip with exit
43
+ 0, so a host without Claude, Codex, or omp installed still syncs its deployed
44
+ config cleanly. A missing `skills-cli` pin is different: when `npx` is
45
+ available and `SoT/.agents/skills.txt` names a skill that is not installed yet,
46
+ the agents sync stops with exit 1, in a dry run too. An unavailable plugin
47
+ inventory warns without a ledger row and falls back to the full refresh, whose
48
+ failed commands are recorded.
46
49
 
47
50
  ## Optional opt-ins
48
51
 
@@ -70,8 +70,8 @@ the retired kit `bash.patterns` rules in `OMP_RETIRED_BASH_RULES` (exact
70
70
  `match` and `approval` pairs, including the 492 former kit prompt rules
71
71
  retired in 0.22.8), config.yml keys whose deployed value still equals the value the kit used to
72
72
  ship, `providers.webSearchOrder` at any value, and the retired
73
- `anthropic.modelOverrides.claude-opus-5-5` block in models.yml while it still
74
- matches the shipped block.
73
+ `providers.anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
74
+ it still matches the shipped block.
75
75
  Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
76
76
  registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
77
77
  through `omp plugin`, and `pi-intercom` is installed at its
@@ -159,8 +159,10 @@ directory is `<config root>/agent`, where the config root is
159
159
  directory never moves under XDG. Only the data root that holds
160
160
  `marketplaces.json` does: on Linux and macOS, with no agent-dir override
161
161
  active, an existing `$XDG_DATA_HOME/omp` (or `$XDG_DATA_HOME/omp/profiles/<name>`
162
- for a named profile) is adopted. The intercom file keeps pi-intercom's own
163
- root: `$PI_CODING_AGENT_DIR/intercom`, else `~/.pi/agent/intercom`.
162
+ for a named profile) is adopted. Under a named profile, the intercom file goes
163
+ into `<agent directory>/intercom`. Otherwise it goes into
164
+ `$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
165
+ `~/.pi/agent/intercom`.
164
166
 
165
167
  ## Reconcile flags
166
168