docks-kit 0.22.12 → 0.22.20

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 (53) hide show
  1. package/AGENTS.md +95 -81
  2. package/README.md +7 -7
  3. package/cli/docs/command-guards.md +7 -3
  4. package/cli/docs/flags.md +59 -9
  5. package/cli/docs/install.md +2 -2
  6. package/cli/docs/omp-context.md +14 -8
  7. package/cli/docs/omp-models.md +1 -1
  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 +29 -15
  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 +56 -15
  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/index.ts +1 -1
  28. package/cli/src/engine-native/kitLock.ts +121 -0
  29. package/cli/src/engine-native/modes.ts +49 -31
  30. package/cli/src/engine-native/ompChild.ts +26 -0
  31. package/cli/src/engine-native/ompFastMode.ts +14 -7
  32. package/cli/src/engine-native/ompFileDeploy.ts +12 -6
  33. package/cli/src/engine-native/ompMarketplace.ts +25 -18
  34. package/cli/src/engine-native/ompPlugins.ts +39 -18
  35. package/cli/src/engine-native/ompRemovals.ts +51 -23
  36. package/cli/src/engine-native/ompSync.ts +78 -38
  37. package/cli/src/engine-native/os/targets.ts +16 -4
  38. package/cli/src/engine-native/os/types.ts +1 -1
  39. package/cli/src/engine-native/parseArgs.ts +27 -17
  40. package/cli/src/engine-native/processes.ts +16 -0
  41. package/cli/src/engine-native/scratch.ts +18 -0
  42. package/cli/src/engine-native/skillsInstall.ts +27 -2
  43. package/cli/src/engine-native/skillsPrune.ts +51 -49
  44. package/cli/src/engine-native/skillsRecords.ts +138 -0
  45. package/cli/src/engine-native/skillsSync.ts +16 -13
  46. package/cli/src/engine-native/syncDispatch.ts +186 -4
  47. package/cli/src/engine-native/tidy.ts +102 -119
  48. package/cli/src/engine-native/tomlLines.ts +92 -0
  49. package/cli/src/generated/sotPayload.ts +5 -5
  50. package/cli/src/main.ts +5 -30
  51. package/cli/src/manifests.ts +24 -4
  52. package/package.json +2 -2
  53. 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
 
@@ -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
@@ -81,10 +84,13 @@ The command must print `-1`.
81
84
 
82
85
  ## The clamp hazard a fixed pin carries
83
86
 
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.
87
+ In omp 18.4.4 through 18.8.7, the fixed-token branch clamps the pinned value
88
+ to `contextWindow - 1`. On any model whose window is at or below the pinned
89
+ value, the reserve collapses to one token, so omp compacts only once the
90
+ context is already full. omp 18.8.8 and later fall back to the reserve-based
91
+ budget for such a pin, so this collapse does not occur there. The kit floor is
92
+ omp 18.4.4, so a supported host can still have the clamp. The reserve-based
93
+ default always leaves at least 15% of the window free.
88
94
 
89
95
  No current role model has a window below 272,000, so the hazard was latent
90
96
  rather than live. Not pinning removes it entirely, including for any future
@@ -346,7 +346,7 @@ has measured both at the other levels.
346
346
  ### GPT-5.6 Sol (OpenAI) - previous generation
347
347
 
348
348
  The role map no longer uses GPT-5.6 Sol. This table stays as the measured
349
- baseline for the current Sol task role.
349
+ baseline for the GPT-6.1 Sol `task` retry fallback.
350
350
 
351
351
  | Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
352
352
  |---|---:|---:|---:|---:|---:|---:|---:|
@@ -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
@@ -84,13 +84,22 @@ config-root registry lists `docks`, omp copies it forward itself: the sync runs
84
84
  plugin operation, the sync reads the inventory again and prints one line that
85
85
  names each plugin with its version change, for example
86
86
  `omp plugins synced: docks@docks 0.21.1 -> 0.22.0, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
87
+
87
88
  omp deletes the previous plugin folder on `omp plugin upgrade`. A running omp
88
- session then loses the plugin agents and skill script paths of that folder. For
89
- each marketplace upgrade that changed the version, the sync prints a warning,
90
- for example
91
- `omp plugin docks@docks 0.21.1 -> 0.22.0: running omp sessions lose its plugin agents and skill script paths until they restart.`
89
+ session then loses the plugin agents of that folder. A test on omp 18.16.0
90
+ showed that `/reload-plugins` brings the agents back, and that `skill://`
91
+ resolves to the new folder (#139). The omp marketplace docs still ask for a
92
+ restart for hooks, extension modules, and non-MCP tools. For each marketplace
93
+ upgrade that changed the version, the sync prints a warning, for example
94
+ `omp plugin docks@docks 0.21.1 -> 0.22.0: running omp sessions lose its plugin agents until they run /reload-plugins and read its skills again through skill:// (restart omp instead when the plugin ships hooks, extension modules, or non-MCP tools).`
92
95
  The next step then says
93
- `Restart running omp sessions: a plugin upgrade removed the plugin folders that they loaded.`
96
+ `Run /reload-plugins in each running omp session, then read each plugin skill again through skill://. Restart omp instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools.`
97
+ A version-changing upgrade does not set the restart trigger. Each other plugin
98
+ operation sets it: an install, a reinstall at the same version, an npm install,
99
+ or a link. A changed kit plugin file or omp config file also sets it. The
100
+ restart next step `Restart omp to load any refreshed plugins, skills, or tools.`
101
+ then prints next to the upgrade rule.
102
+
94
103
  The sync also writes one event file for each such upgrade into the upgrade log
95
104
  `~/.cache/docks-kit/omp-plugin-upgrades/` (folder 0700, files 0600). The file
96
105
  name is `<finishedAt ms>-<random>.json`, and the file holds
@@ -108,8 +117,8 @@ the warning and an event with the after version `unknown`, for example
108
117
 
109
118
  A failed write or prune of the upgrade log does not fail the sync, because it
110
119
  is not a harness CLI operation. A failed write warns
111
- `omp plugin upgrade log not written: <error> — running omp sessions get no reminder for these upgrades and must restart`.
112
- The summary line, the upgrade warnings, and the next step stay. A failed prune
120
+ `omp plugin upgrade log not written: <error> — running omp sessions get no reminder for these upgrades; give each of them the advice above`.
121
+ The summary line, the upgrade warnings, and the next steps stay. A failed prune
113
122
  keeps the new events and warns
114
123
  `omp plugin upgrade log not pruned: <error> — it can keep more than 100 event files`.
115
124
 
@@ -117,9 +126,12 @@ The kit plugin extension `pluginUpgrades.ts` reads the upgrade log. In each
117
126
  tool result of a main omp session, it takes the events that finished after
118
127
  its omp process started. It adds one reminder for the events that the session
119
128
  did not get before. The reminder names each plugin with its version change. It
120
- says that the session may still use the removed folders. It tells the agent to
121
- ask the user to restart omp. A folder or file that the extension cannot read
122
- gives no reminder for that tool result. The next tool result reads it again.
129
+ says that the plugin agents of the session may fail. It tells the agent to ask
130
+ the user to run `/reload-plugins`. It then tells the agent to read each plugin
131
+ skill again through `skill://` before it runs a skill script. It asks for a
132
+ restart instead when an upgraded plugin ships hooks, extension modules, or
133
+ non-MCP tools. A folder or file that the extension cannot read gives no
134
+ reminder for that tool result. The next tool result reads it again.
123
135
  These limits apply:
124
136
 
125
137
  - omp imports extension modules only at startup. An omp process that started
@@ -132,7 +144,7 @@ These limits apply:
132
144
  registry still uses. So a session on a project-scope install keeps its
133
145
  folder. For this reason, the reminder says "may".
134
146
  - An omp process that started during the upgrade can get a reminder that it
135
- does not need. A restart is harmless.
147
+ does not need. A reload or a restart is harmless.
136
148
  - The log keeps the newest 100 events. A session that stays idle through more
137
149
  than 100 later upgrades loses the oldest ones.
138
150
 
@@ -147,8 +159,10 @@ directory is `<config root>/agent`, where the config root is
147
159
  directory never moves under XDG. Only the data root that holds
148
160
  `marketplaces.json` does: on Linux and macOS, with no agent-dir override
149
161
  active, an existing `$XDG_DATA_HOME/omp` (or `$XDG_DATA_HOME/omp/profiles/<name>`
150
- for a named profile) is adopted. The intercom file keeps pi-intercom's own
151
- 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`.
152
166
 
153
167
  ## Reconcile flags
154
168
 
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Field | Meaning |
6
6
  |-------|---------|
7
- | `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for npx-invoked tools, e.g. `skills-cli`) |
7
+ | `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool: `npx` for `skills-cli`, `omp install` for `pi-intercom`; the optional `via` field names that tool in the doctor table, and the default is `npx`) |
8
8
  | `policy` | Installation policy; `present` installs when missing and never upgrades |
9
9
  | `floor` | Minimum acceptable version shown in the doctor table |
10
10
  | `verified` | Last kit-tested version and the exact pin for kit-driven installs |
@@ -37,8 +37,10 @@ server as an npm global for the `typescript-lsp` plugin, so an older Node runs
37
37
  a server its own manifest rejects. `docks-kit toolchain check` prints
38
38
  `below-floor` for a Node older than 22.22.2. The sync pass reads the same
39
39
  floor: it skips the `typescript-language-server` install on such a host, warns
40
- with the host Node version, and installs the other language servers. Nothing
41
- else consults the floor, so a host below it still runs every kit operation.
40
+ with the host Node version, and installs the other language servers.
41
+ `docks-kit toolchain upgrade` also reads the floor: it skips the
42
+ `typescript-language-server` upgrade on such a host and warns. Nothing else
43
+ consults the floor, so a host below it still runs every other kit operation.
42
44
 
43
45
  ## rust-analyzer: no floor, no pin
44
46
 
@@ -62,8 +64,9 @@ the component is not installed. When `rust-analyzer --version` does not answer
62
64
  within 60 s, sync warns, stops the probe, and does not add the component on that
63
65
  run. `rustup update` is the user's remedy for an old component.
64
66
 
65
- A lagging server shows as `below-floor` in `docks-kit toolchain check`. To move
66
- the npm servers to their `verified` pins, run:
67
+ A server below its `floor` shows as `below-floor` in `docks-kit toolchain check`.
68
+ A server at or above its floor but below its `verified` pin shows as `ok`.
69
+ To move every npm server that is below its `verified` pin to that pin, run:
67
70
 
68
71
  ```bash
69
72
  docks-kit toolchain upgrade --dry-run # print the npm command
@@ -72,8 +75,9 @@ docks-kit toolchain upgrade # run it
72
75
 
73
76
  `toolchain upgrade` (`claudeLsp.ts upgradeLspServers`) reads `npm ls -g` to see
74
77
  which of `intelephense`, `typescript-language-server`, and `typescript` npm
75
- owns. It runs one `npm install -g <pkg>@<verified>` for each npm-owned package
76
- below its pin. A package already at or above its pin stays as it is. It leaves
78
+ owns. It runs one `npm install -g` command that names every npm-owned package
79
+ below its pin as `<pkg>@<verified>`. A package already at or above its pin
80
+ stays as it is. It leaves
77
81
  these alone and warns:
78
82
 
79
83
  - A binary on PATH that npm does not own. It came from another installer, so
@@ -92,13 +96,19 @@ package is not at its pin.
92
96
 
93
97
  ## Supply-chain stance
94
98
 
95
- Every kit-driven install of third-party software is pinned to a
96
- `SoT/toolchain.json` `verified` version — never floating `@latest` (the
97
- npm-worm / Shai-Hulud attack surface). That includes the
98
- `npx skills@<verified>` invocations on agents sync and the release workflow
99
- (actions pinned to commit SHAs, exact bun/npm versions).
100
-
101
- The kit's own package is the single exemption. `install.sh` and `install.ps1`
99
+ Every kit-driven package install from npm, npx, GitHub releases, or
100
+ `omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
101
+ floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
102
+ the `npx skills@<verified>` invocations on agents sync and the release workflow
103
+ (actions pinned to commit SHAs, exact bun/npm versions). Two installs follow
104
+ the host toolchain and have no pin: `rust-analyzer` (rustup) and `bubblewrap`
105
+ (distro package manager). The existing Claude Code, Codex, and omp marketplace
106
+ plugins have no manifest pin either: sync installs and refreshes them at the
107
+ version that their marketplace publishes (see `plugins`). Any new install
108
+ surface, a new marketplace or plugin source included, needs a manifest pin
109
+ first.
110
+
111
+ The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
102
112
  end with `bun add -g docks-kit@latest` because a global installer that pinned
103
113
  itself would install a fixed old kit forever. The exemption covers `docks-kit`
104
114
  alone; both installers still pin the Bun installer they download to the
package/cli/src/argv.ts CHANGED
@@ -19,7 +19,6 @@ import {
19
19
  spliceOmpBoundary,
20
20
  subcommandName as scanSubcommandName,
21
21
  type ArgvSurfaces,
22
- type CommandValue,
23
22
  } from "./argvSurface";
24
23
  import { validateScannedArgv } from "./argvValidate";
25
24
 
@@ -27,13 +26,17 @@ export type ArgvOutcome =
27
26
  | { readonly kind: "reject"; readonly message: string; readonly exitCode: number }
28
27
  | { readonly kind: "accept"; readonly args: ReadonlyArray<string> };
29
28
 
30
- const COMMANDS: ReadonlyArray<CommandValue> = [
29
+ /**
30
+ * The one subcommand list. `main.ts` registers it with Effect, and the argv
31
+ * surfaces below accept the same words. The order is the `--help` order.
32
+ */
33
+ export const COMMANDS = [
31
34
  syncCommand,
32
35
  harnessesCommand,
33
36
  updateCommand,
34
37
  modelCommand,
35
- toolchainCommand,
36
38
  modelsCommand,
39
+ toolchainCommand,
37
40
  statusCommand,
38
41
  pluginsCommand,
39
42
  skillsCommand,
@@ -41,7 +44,7 @@ const COMMANDS: ReadonlyArray<CommandValue> = [
41
44
  ompCommand,
42
45
  scratchCommand,
43
46
  tidyCommand,
44
- ];
47
+ ] as const;
45
48
 
46
49
  const SURFACES: ArgvSurfaces = buildSurfaces(COMMANDS, GlobalFlag.BuiltIns);
47
50
 
@@ -6,25 +6,12 @@
6
6
  */
7
7
 
8
8
  import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseModifiers";
9
+ import { isLegacyFlag, LEGACY_FLAG_HINTS } from "./engine-native/parseArgs";
9
10
  import { modelCatalog } from "./engine-native/models";
10
11
  import { advisorCatalog, advisorFlagGrammar, effortCatalog, effortFlagGrammar } from "./efforts";
11
12
  import type { Tool } from "./manifests";
12
13
  import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
13
14
 
14
- const LEGACY_HINTS: Readonly<Record<string, string>> = {
15
- "--force": "--force was renamed to --reconcile",
16
- "--remove-plugins":
17
- "--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
18
- "--680k": "--680k was renamed to --claude-compact-window=680k",
19
- "--permissive": "--permissive was renamed to --claude-permissive",
20
- "--supabase": "--supabase was renamed to --claude-plugin=supabase",
21
- "--n8n": "--n8n was renamed to --claude-plugin=n8n",
22
- "--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
23
- "--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
24
- "--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
25
- "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'",
26
- };
27
-
28
15
  const modelCatalogHint = (tool: Tool): string => {
29
16
  const catalog = modelCatalog(tool);
30
17
  const list = catalog.models
@@ -76,8 +63,7 @@ export const validateScannedArgv = (
76
63
 
77
64
  if (subcommand === "sync") {
78
65
  for (const flag of flags) {
79
- const hint = LEGACY_HINTS[flag.name];
80
- if (hint !== undefined) return hint;
66
+ if (isLegacyFlag(flag.name)) return LEGACY_FLAG_HINTS[flag.name];
81
67
  }
82
68
  }
83
69
 
@@ -17,7 +17,7 @@ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
17
17
  const TOPICS: Record<string, { summary: string; body: string }> = {
18
18
  overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
19
19
  "sync-layers": {
20
- summary: "The three sync layers and additive-by-default semantics",
20
+ summary: "The four sync targets (claude, codex, agents, omp) and additive-by-default semantics",
21
21
  body: syncLayers,
22
22
  },
23
23
  flags: { summary: "Full flag reference incl. the old→new rename table", body: flags },
@@ -23,8 +23,15 @@ import {
23
23
  renderFreeOverlay,
24
24
  type CatalogModel,
25
25
  } from "../engine-native/ompOverlay";
26
- import { FAST_ON_TIER, toggleDeployedOpenAiFast } from "../engine-native/ompFastMode";
26
+ import {
27
+ FAST_ON_TIER,
28
+ requireDeployedConfig,
29
+ toggleDeployedOpenAiFast,
30
+ type FastToggle,
31
+ } from "../engine-native/ompFastMode";
27
32
  import { ompPaths } from "../engine-native/ompPaths";
33
+ import { ExitError } from "../engine-native/parseArgs";
34
+ import { withHomeAndFolderLocks } from "../engine-native/syncDispatch";
28
35
 
29
36
  const model = Flag.String("model").pipe(
30
37
  Flag.withDescription("Free model selector to use and remember for omp sessions"),
@@ -251,6 +258,49 @@ const pickLevels = (catalogModel: CatalogModel) =>
251
258
  return { thinking, advisorThinking };
252
259
  });
253
260
 
261
+ /**
262
+ * Toggle fast mode under the sync lock of `home` and the folder lock of the
263
+ * omp agent folder, with the wait and the held line of a sync. A sync also
264
+ * merges `config.yml` there. Return 0 after the toggle, 1 for a held lock,
265
+ * and 2 for a failed toggle or an invalid wait bound.
266
+ */
267
+ async function toggleFastUnderLocks(home: string, agentDir: string): Promise<number> {
268
+ const configPath = p(agentDir, "config.yml");
269
+ const err = (line: string) => console.error(line);
270
+ // Check config.yml before any lock. A missing file ends the run before the
271
+ // lock step can create the agent folder, and a folder that a sync creates
272
+ // during the home lock wait is never toggled without its folder lock.
273
+ try {
274
+ requireDeployedConfig(configPath);
275
+ } catch (error) {
276
+ err(error instanceof Error ? error.message : String(error));
277
+ return 2;
278
+ }
279
+ try {
280
+ return await withHomeAndFolderLocks(home, [agentDir], err, async () => {
281
+ let toggle: FastToggle;
282
+ try {
283
+ toggle = toggleDeployedOpenAiFast(configPath);
284
+ } catch (error) {
285
+ err(error instanceof Error ? error.message : String(error));
286
+ return 2;
287
+ }
288
+ const state = toggle.next === FAST_ON_TIER ? "ON" : "OFF";
289
+ console.log(
290
+ `omp fast mode ${state} for OpenAI/Codex models: tier.openai ${toggle.previous} -> ${toggle.next} in ${configPath}`,
291
+ );
292
+ console.log(
293
+ "New omp sessions use it; in a running session, use /fast on|off or restart omp.",
294
+ );
295
+ return 0;
296
+ });
297
+ } catch (error) {
298
+ // An invalid DOCKS_KIT_SYNC_LOCK_WAIT_MS prints its error line, then throws ExitError(2).
299
+ if (error instanceof ExitError) return error.code;
300
+ throw error;
301
+ }
302
+ }
303
+
254
304
  export const ompCommand = Command.make("omp", { model, pick, fast, args }, (config) =>
255
305
  Effect.gen(function* () {
256
306
  // Check the forwarded arguments before omp, the catalog, or kit.db, so a
@@ -266,22 +316,13 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
266
316
  if (Option.isSome(config.model) || config.pick || config.args.length > 0) {
267
317
  return yield* bail("--fast toggles fast mode and exits; pass it alone");
268
318
  }
269
- const configPath = p(
270
- ompPaths({ home: engineHome(process.env), env: process.env, platform: process.platform })
271
- .agentDir,
272
- "config.yml",
273
- );
274
- const toggle = yield* Effect.try({
275
- try: () => toggleDeployedOpenAiFast(configPath),
319
+ const home = engineHome(process.env);
320
+ const agentDir = ompPaths({ home, env: process.env, platform: process.platform }).agentDir;
321
+ const code = yield* Effect.tryPromise({
322
+ try: () => toggleFastUnderLocks(home, agentDir),
276
323
  catch: (error) => (error instanceof Error ? error.message : String(error)),
277
324
  }).pipe(Effect.catch((message) => bail(message)));
278
- const state = toggle.next === FAST_ON_TIER ? "ON" : "OFF";
279
- yield* Console.log(
280
- `omp fast mode ${state} for OpenAI/Codex models: tier.openai ${toggle.previous} -> ${toggle.next} in ${configPath}`,
281
- );
282
- yield* Console.log(
283
- "New omp sessions use it; in a running session, use /fast on|off or restart omp.",
284
- );
325
+ if (code !== 0) return yield* Effect.sync(() => process.exit(code));
285
326
  return;
286
327
  }
287
328
 
@@ -1,27 +1,27 @@
1
1
  import { Argument, Command, Flag } from "effect/cli";
2
2
  import { Effect, Option } from "effect";
3
- import { spawnSync } from "node:child_process";
4
3
  import { existsSync } from "node:fs";
5
4
  import { join } from "node:path";
6
5
  import { bail, engine } from "../engine";
6
+ import { spawnHost } from "../engine-native/exec";
7
7
  import type { Logger } from "../engine-native/logger";
8
8
  import { kitHome } from "../kitHome";
9
9
  import { LoggerService } from "../services";
10
10
 
11
11
  /** Best-effort update autodetection: nudge (never block, never fail) when
12
12
  * the kit checkout is behind its upstream. Silent on detached HEADs, no
13
- * upstream, no network, no git. */
14
- const updateNudge = (logger: Logger): void => {
13
+ * upstream, no network, no git. git starts through spawnHost, so a Windows
14
+ * host never runs a `git.exe` from the current directory. */
15
+ export const updateNudge = (logger: Logger): void => {
15
16
  try {
16
17
  const home = kitHome();
17
18
  if (!existsSync(join(home, ".git"))) return;
18
19
  if (
19
- spawnSync("git", ["-C", home, "fetch", "--quiet"], { stdio: "ignore", timeout: 4000 })
20
+ spawnHost("git", ["-C", home, "fetch", "--quiet"], { stdio: "ignore", timeout: 4000 })
20
21
  .status !== 0
21
22
  )
22
23
  return;
23
- const res = spawnSync("git", ["-C", home, "rev-list", "--count", "HEAD..@{u}"], {
24
- encoding: "utf8",
24
+ const res = spawnHost("git", ["-C", home, "rev-list", "--count", "HEAD..@{u}"], {
25
25
  stdio: ["ignore", "pipe", "ignore"],
26
26
  });
27
27
  const behind = (res.stdout ?? "").trim();