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
@@ -15,12 +15,14 @@
15
15
  import { randomBytes } from "node:crypto";
16
16
  import { chmodSync, mkdirSync, readdirSync, realpathSync, unlinkSync } from "node:fs";
17
17
 
18
- import { replaceFile } from "./atomicWrite";
19
- import { p, processFailureSummary, spawnProcess } from "./exec";
18
+ import { removeStaleTemporaries, replaceFile } from "./atomicWrite";
19
+ import { p, processFailureSummary } from "./exec";
20
20
  import { recordFailure } from "./failures";
21
21
  import type { Ctx } from "./index";
22
22
  import { isObject, parseJson } from "./jq";
23
+ import { spawnOmp } from "./ompChild";
23
24
  import { KIT_PLUGIN_NAME, kitPluginDir } from "./ompKitPlugin";
25
+ import type { OmpPaths } from "./ompPaths";
24
26
  import { kitCacheDir } from "./scratch";
25
27
  import { field } from "./toolchain";
26
28
 
@@ -85,10 +87,8 @@ function marketplaceEntryVersion(entries: unknown): string | undefined {
85
87
  return undefined;
86
88
  }
87
89
 
88
- async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined> {
89
- const result = await spawnProcess("omp", ["plugin", "list", "--json"], {
90
- stdio: ["ignore", "pipe", "ignore"],
91
- });
90
+ async function installedPluginIdsFromCli(paths: OmpPaths): Promise<InstalledPlugins | undefined> {
91
+ const result = await spawnOmp(paths, ["plugin", "list", "--json"], ["ignore", "pipe", "ignore"]);
92
92
  if (result.error !== undefined || result.exitCode !== 0) return undefined;
93
93
 
94
94
  const value = parseJson(result.stdout);
@@ -145,12 +145,13 @@ function describeOperation(
145
145
 
146
146
  async function runPluginCommand(
147
147
  ctx: Ctx,
148
+ paths: OmpPaths,
148
149
  plugin: string,
149
150
  args: ReadonlyArray<string>,
150
151
  ): Promise<boolean> {
151
152
  const { clearProgress, progress } = ctx.services.logger;
152
153
  progress(`Updating omp plugin ${plugin}...`);
153
- const result = await spawnProcess("omp", args, { stdio: ["ignore", "pipe", "pipe"] });
154
+ const result = await spawnOmp(paths, args, ["ignore", "pipe", "pipe"]);
154
155
  clearProgress();
155
156
  if (result.error === undefined && result.exitCode === 0) return true;
156
157
 
@@ -194,8 +195,15 @@ function versionChanges(
194
195
  return upgrades;
195
196
  }
196
197
 
197
- /** Removes the oldest event files beyond the newest UPGRADE_EVENTS_KEPT. */
198
+ /**
199
+ * Removes the oldest event files beyond the newest UPGRADE_EVENTS_KEPT, and
200
+ * the temporary files that killed event writes left.
201
+ */
198
202
  function pruneUpgradeLog(dir: string): void {
203
+ removeStaleTemporaries(
204
+ dir,
205
+ (target) => target.kind === "name" && UPGRADE_EVENT_FILE.test(target.name),
206
+ );
199
207
  const events = readdirSync(dir).flatMap((name) => {
200
208
  const match = UPGRADE_EVENT_FILE.exec(name);
201
209
  return match === null ? [] : [{ name, finishedAt: Number(match[1]) }];
@@ -250,7 +258,8 @@ function recordUpgrades(home: string, upgrades: ReadonlyArray<PluginUpgrade>): s
250
258
  return undefined;
251
259
  }
252
260
 
253
- export async function syncPlugins(ctx: Ctx): Promise<number> {
261
+ /** Run the plugin pass. `paths` are the omp paths that the sync locked. */
262
+ export async function syncPlugins(ctx: Ctx, paths: OmpPaths): Promise<number> {
254
263
  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
255
264
 
256
265
  if (ctx.services.deps.probe("omp").state === "missing") {
@@ -289,7 +298,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
289
298
  const piIntercomPin = field("pi-intercom", "verified");
290
299
 
291
300
  progress("Checking installed omp plugins...");
292
- const installed = await installedPluginIdsFromCli();
301
+ const installed = await installedPluginIdsFromCli(paths);
293
302
  clearProgress();
294
303
  if (installed === undefined) {
295
304
  warn("omp plugin inventory unavailable — falling back to the full refresh path");
@@ -313,7 +322,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
313
322
  const args = present
314
323
  ? ["plugin", "upgrade", "--scope", "user", pluginId]
315
324
  : ["plugin", "install", "--scope", "user", pluginId];
316
- const succeeded = await runPluginCommand(ctx, pluginId, args);
325
+ const succeeded = await runPluginCommand(ctx, paths, pluginId, args);
317
326
  // The operation boundary: an omp process that started later loaded the new folder.
318
327
  const finishedAt = Date.now();
319
328
  if (succeeded) {
@@ -341,7 +350,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
341
350
  const args = present
342
351
  ? ["install", "--force", `pi-intercom@${piIntercomPin}`]
343
352
  : ["install", `pi-intercom@${piIntercomPin}`];
344
- if (await runPluginCommand(ctx, "pi-intercom", args)) {
353
+ if (await runPluginCommand(ctx, paths, "pi-intercom", args)) {
345
354
  operations.push({
346
355
  kind: "npm",
347
356
  id: "pi-intercom",
@@ -360,7 +369,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
360
369
  const linkedTarget = kitPluginPath === undefined ? undefined : realPath(kitPluginPath);
361
370
  if (linkedTarget !== undefined && linkedTarget === realPath(kitDir)) {
362
371
  verbose(`omp kit plugin ${KIT_PLUGIN_NAME} already linked`);
363
- } else if (await runPluginCommand(ctx, KIT_PLUGIN_NAME, ["plugin", "link", kitDir])) {
372
+ } else if (await runPluginCommand(ctx, paths, KIT_PLUGIN_NAME, ["plugin", "link", kitDir])) {
364
373
  operations.push({ kind: "link", id: KIT_PLUGIN_NAME });
365
374
  if (installed?.npm.has(KIT_PLUGIN_NAME) !== true) pluginsInstalled++;
366
375
  }
@@ -368,7 +377,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
368
377
  if (operations.length > 0) {
369
378
  // A second inventory read gives the versions that the operations left.
370
379
  progress("Reading omp plugin versions...");
371
- const after = await installedPluginIdsFromCli();
380
+ const after = await installedPluginIdsFromCli(paths);
372
381
  clearProgress();
373
382
  const items = operations.map((operation) => describeOperation(operation, after));
374
383
  change(`omp plugins synced: ${items.join(", ")}`);
@@ -9,24 +9,39 @@
9
9
  * sync, without `--reconcile`. Message strings and prune semantics are part of
10
10
  * the contract.
11
11
  */
12
- import { existsSync, readFileSync, writeFileSync } from "node:fs";
12
+ import { existsSync, readFileSync } from "node:fs";
13
13
  import { isDeepStrictEqual } from "node:util";
14
14
  import { isMap, isScalar, isSeq, parseDocument, type YAMLMap } from "yaml";
15
+ import { replaceFile } from "./atomicWrite";
15
16
  import type { Ctx } from "./index";
17
+ import { backupPrivateFile } from "./ompFileDeploy";
16
18
  import { bashPatternKey, bashRuleKey } from "./ompYaml";
17
19
 
18
- type RetiredScalar = string | number | boolean;
20
+ /** A retired leaf value: a scalar, or a sequence the kit shipped as one value. */
21
+ type RetiredValue = string | number | boolean | ReadonlyArray<string>;
19
22
 
20
23
  /**
21
24
  * Keys the kit used to deploy, each paired with the exact value it deployed. A
22
25
  * key is pruned only while the deployed value still equals that value, so a
23
- * user who changed the setting keeps it. Every recorded value except
24
- * `retry.usageAwareFallback` also equals omp's current default, so pruning those
25
- * changes no behavior today and lets a later upstream default change take
26
- * effect. Pruning `retry.usageAwareFallback: true` restores omp's default
27
- * `false`, which removes the coding-plan reserve prompt.
26
+ * user who changed the setting keeps it. A key listed twice shipped both
27
+ * values at different times.
28
+ *
29
+ * Most recorded values equal omp's current default, so pruning them changes no
30
+ * behavior today and lets a later upstream default change take effect. These
31
+ * entries differ from the default, and pruning them is intended:
32
+ * - `retry.usageAwareFallback: true` restores omp's default `false`, which
33
+ * removes the coding-plan reserve prompt.
34
+ * - `advisor.enabled: true` and `advisor.syncBacklog: "1"` (defaults `false`
35
+ * and `"off"`), `modelRoles.advisor`, and the empty
36
+ * `retry.fallbackChains.advisor` chain: the owner removed the advisor. omp
37
+ * keeps it off, and an `/advisor on` session runs on the `slow` role.
38
+ * - `codexResets.autoRedeem: "no"`: omp migrates this legacy key in memory to
39
+ * `autoRedeem5h` and `autoRedeemWeekly`, which the SoT now declares with the
40
+ * same value.
41
+ * - `compaction.thresholdTokens: 231200`: an old fixed compaction trigger.
42
+ * Pruning it restores omp's reserve-based default `-1`.
28
43
  */
29
- const OMP_RETIRED_VALUES: ReadonlyArray<readonly [string, RetiredScalar]> = [
44
+ export const OMP_RETIRED_VALUES: ReadonlyArray<readonly [string, RetiredValue]> = [
30
45
  ["symbolPreset", "unicode"],
31
46
  ["theme.dark", "titanium"],
32
47
  ["statusLine.preset", "default"],
@@ -46,6 +61,30 @@ const OMP_RETIRED_VALUES: ReadonlyArray<readonly [string, RetiredScalar]> = [
46
61
  ["autoResume", false],
47
62
  ["startup.changelogMode", "summary"],
48
63
  ["retry.usageAwareFallback", true],
64
+ ["defaultThinkingLevel", "high"],
65
+ ["tier.anthropic", "none"],
66
+ ["advisor.enabled", true],
67
+ ["advisor.enabled", false],
68
+ ["advisor.syncBacklog", "1"],
69
+ ["task.softRequestBudget", 200],
70
+ ["task.softRequestBudgetNotice", true],
71
+ ["task.batch", true],
72
+ ["task.enableEffort", false],
73
+ ["task.maxRecursionDepth", 2],
74
+ ["modelRoles.advisor", "anthropic/claude-opus-5-5:medium"],
75
+ ["providers.anthropic.serverSideFallback", false],
76
+ ["providers.fetch", "auto"],
77
+ ["retry.fallbackChains.advisor", []],
78
+ ["includeWorkspaceTree", false],
79
+ ["commands.enableOpencodeUser", false],
80
+ ["skills.enableClaudeUser", false],
81
+ ["skills.enableCodexUser", false],
82
+ ["skills.enableAgentsUser", true],
83
+ ["compaction.thresholdTokens", -1],
84
+ ["compaction.thresholdTokens", 231200],
85
+ ["textVerbosity", "low"],
86
+ ["codexResets.autoRedeem", "no"],
87
+ ["tools.approvalMode", "yolo"],
49
88
  ];
50
89
 
51
90
  /**
@@ -296,12 +335,17 @@ const retiredBashRules: Pruner = (root) => {
296
335
  return pruned;
297
336
  };
298
337
 
299
- /** Applies each pruner to one deployed omp YAML file. */
338
+ /**
339
+ * Applies each pruner to one deployed omp YAML file. `alreadyBackedUp` is true
340
+ * when the merge of this sync already wrote `<file>.bak`; a second backup would
341
+ * replace those pre-sync bytes with the merged bytes.
342
+ */
300
343
  function pruneRetired(
301
344
  ctx: Ctx,
302
345
  file: string,
303
346
  label: string,
304
347
  pruners: ReadonlyArray<Pruner>,
348
+ alreadyBackedUp: boolean,
305
349
  ): number {
306
350
  const { change, echo, verbose, warn } = ctx.services.logger;
307
351
  if (!existsSync(file)) return 0;
@@ -325,33 +369,56 @@ function pruneRetired(
325
369
  echo(`[dry-run] prune ${file}: ${pruned.join(", ")}`);
326
370
  return pruned.length;
327
371
  }
328
- writeFileSync(file, String(doc));
329
- change(`omp ${label} pruned ${pruned.length} retired entr(ies): ${pruned.join(", ")}`);
372
+ if (!alreadyBackedUp) backupPrivateFile(file);
373
+ // replaceFile writes through a symlinked file, so the link stays.
374
+ replaceFile(file, String(doc), { mode: 0o600 });
375
+ const backupNote = alreadyBackedUp ? "" : ` (backup at ${label}.bak)`;
376
+ change(
377
+ `omp ${label} pruned ${pruned.length} retired entr(ies): ${pruned.join(", ")}${backupNote}`,
378
+ );
330
379
  return pruned.length;
331
380
  }
332
381
 
333
382
  /** Prunes retired kit-owned keys and bash rules from a deployed omp config.yml. */
334
- export function syncOmpRemovals(ctx: Ctx, configFile: string): number {
335
- return pruneRetired(ctx, configFile, "config.yml", [
336
- retiredKeys([
337
- ...OMP_RETIRED_VALUES.map(([path, value]): RetiredEntry => [
338
- path,
339
- (node) => isScalar(node) && node.value === value,
383
+ export function syncOmpRemovals(ctx: Ctx, configFile: string, alreadyBackedUp: boolean): number {
384
+ return pruneRetired(
385
+ ctx,
386
+ configFile,
387
+ "config.yml",
388
+ [
389
+ retiredKeys([
390
+ ...OMP_RETIRED_VALUES.map(([path, value]): RetiredEntry => [
391
+ path,
392
+ Array.isArray(value)
393
+ ? (node) => isSeq(node) && isDeepStrictEqual(node.toJSON(), value)
394
+ : (node) => isScalar(node) && node.value === value,
395
+ ]),
396
+ ...OMP_RETIRED_KEYS.map((path): RetiredEntry => [path, () => true]),
340
397
  ]),
341
- ...OMP_RETIRED_KEYS.map((path): RetiredEntry => [path, () => true]),
342
- ]),
343
- retiredBashRules,
344
- ]);
398
+ retiredBashRules,
399
+ ],
400
+ alreadyBackedUp,
401
+ );
345
402
  }
346
403
 
347
404
  /** Prunes retired kit-owned blocks from a deployed omp models.yml. */
348
- export function syncOmpModelRemovals(ctx: Ctx, modelsFile: string): number {
349
- return pruneRetired(ctx, modelsFile, "models.yml", [
350
- retiredKeys(
351
- OMP_RETIRED_MODEL_BLOCKS.map(([path, block]): RetiredEntry => [
352
- path,
353
- (node) => isMap(node) && isDeepStrictEqual(node.toJSON(), block),
354
- ]),
355
- ),
356
- ]);
405
+ export function syncOmpModelRemovals(
406
+ ctx: Ctx,
407
+ modelsFile: string,
408
+ alreadyBackedUp: boolean,
409
+ ): number {
410
+ return pruneRetired(
411
+ ctx,
412
+ modelsFile,
413
+ "models.yml",
414
+ [
415
+ retiredKeys(
416
+ OMP_RETIRED_MODEL_BLOCKS.map(([path, block]): RetiredEntry => [
417
+ path,
418
+ (node) => isMap(node) && isDeepStrictEqual(node.toJSON(), block),
419
+ ]),
420
+ ),
421
+ ],
422
+ alreadyBackedUp,
423
+ );
357
424
  }
@@ -2,7 +2,8 @@
2
2
  * EngineNative `sync omp` pipeline. config.yml merges through mergeOmpConfig
3
3
  * and models.yml through mergeOmpModels. Both preserve user-only keys.
4
4
  * Paths come from ompPaths because profiles, PI_CONFIG_DIR,
5
- * PI_CODING_AGENT_DIR, and XDG roots each move them.
5
+ * PI_CODING_AGENT_DIR, and XDG roots each move them. `runSync` resolves them
6
+ * once, before it takes the folder locks, and the pipeline writes only there.
6
7
  * Resolution stays within the environment and filesystem probes so no omp
7
8
  * subcommand runs under ctx.dryRun.
8
9
  *
@@ -15,8 +16,9 @@ import { isAbsolute, resolve } from "node:path";
15
16
 
16
17
  import { bunBootstrap } from "./bun";
17
18
  import { p } from "./exec";
19
+ import { recordFailure } from "./failures";
18
20
  import type { Ctx } from "./index";
19
- import { ompPaths } from "./ompPaths";
21
+ import { ompPaths, type OmpPaths } from "./ompPaths";
20
22
  import { mergeOmpConfig, mergeOmpModels } from "./ompYaml";
21
23
  import { ensureDirectory, syncMergedYaml, syncWholeFile } from "./ompFileDeploy";
22
24
  import { syncKitPlugin } from "./ompKitPlugin";
@@ -26,16 +28,49 @@ import { syncOmpModelRemovals, syncOmpRemovals } from "./ompRemovals";
26
28
 
27
29
  export interface OmpState {
28
30
  readonly pluginsInstalled: number;
31
+ /** The omp agent folder that the sync wrote. */
32
+ readonly agentDir: string;
29
33
  }
30
34
 
31
- export async function ompSync(ctx: Ctx): Promise<OmpState> {
32
- await bunBootstrap(ctx, ctx.services);
35
+ /** The omp folders that a sync writes. */
36
+ export interface OmpWriteFolders {
37
+ readonly paths: OmpPaths;
38
+ /** The folder of the pi-intercom `config.json`. */
39
+ readonly intercomDir: string;
40
+ }
33
41
 
42
+ /**
43
+ * Resolve the omp paths and the intercom folder of this run. `runSync` calls
44
+ * it once, takes a folder lock in each folder, and gives the result to
45
+ * `ompSync`. A second resolution could pick an XDG data root that another
46
+ * sync created after the locks.
47
+ */
48
+ export function ompWriteFolders(ctx: Ctx): OmpWriteFolders {
34
49
  const paths = ompPaths({
35
50
  home: ctx.home,
36
51
  env: process.env,
37
52
  platform: ctx.services.platform.raw(),
38
53
  });
54
+ // omp exports PI_CODING_AGENT_DIR as the agent directory of a named profile,
55
+ // and pi-intercom reads the trimmed value. Without a profile, the kit uses
56
+ // the PI_CODING_AGENT_DIR value when it is set, else ~/.pi/agent.
57
+ const intercomRootSetting = process.env["PI_CODING_AGENT_DIR"]?.trim();
58
+ const intercomRoot =
59
+ paths.profile !== undefined
60
+ ? paths.agentDir
61
+ : intercomRootSetting !== undefined && intercomRootSetting !== ""
62
+ ? isAbsolute(intercomRootSetting)
63
+ ? intercomRootSetting
64
+ : resolve(process.cwd(), intercomRootSetting)
65
+ : p(ctx.home, ".pi", "agent");
66
+ return { paths, intercomDir: p(intercomRoot, "intercom") };
67
+ }
68
+
69
+ /** Run the omp pipeline in `folders`, the folders that `runSync` resolved and locked. */
70
+ export async function ompSync(ctx: Ctx, folders: OmpWriteFolders): Promise<OmpState> {
71
+ await bunBootstrap(ctx, ctx.services);
72
+
73
+ const { paths, intercomDir } = folders;
39
74
  const agentDir = paths.agentDir;
40
75
  if (!ctx.dryRun) ensureDirectory(agentDir);
41
76
 
@@ -53,25 +88,14 @@ export async function ompSync(ctx: Ctx): Promise<OmpState> {
53
88
  "omp mcp.json already in sync",
54
89
  "omp mcp.json synced",
55
90
  );
56
- syncMergedYaml(ctx, "SoT/.omp/config.yml", p(agentDir, "config.yml"), mergeOmpConfig);
91
+ const configFile = p(agentDir, "config.yml");
92
+ const configBackedUp = syncMergedYaml(ctx, "SoT/.omp/config.yml", configFile, mergeOmpConfig);
57
93
  // mergeOmpConfig is additive, so the prune must run on the merged result.
58
- syncOmpRemovals(ctx, p(agentDir, "config.yml"));
59
- syncMergedYaml(ctx, "SoT/.omp/models.yml", p(agentDir, "models.yml"), mergeOmpModels);
60
- syncOmpModelRemovals(ctx, p(agentDir, "models.yml"));
94
+ syncOmpRemovals(ctx, configFile, configBackedUp);
95
+ const modelsFile = p(agentDir, "models.yml");
96
+ const modelsBackedUp = syncMergedYaml(ctx, "SoT/.omp/models.yml", modelsFile, mergeOmpModels);
97
+ syncOmpModelRemovals(ctx, modelsFile, modelsBackedUp);
61
98
 
62
- // omp exports PI_CODING_AGENT_DIR as the agent directory of a named profile,
63
- // and pi-intercom reads the trimmed value. Without a profile, the kit uses
64
- // the PI_CODING_AGENT_DIR value when it is set, else ~/.pi/agent.
65
- const intercomRootSetting = process.env["PI_CODING_AGENT_DIR"]?.trim();
66
- const intercomRoot =
67
- paths.profile !== undefined
68
- ? paths.agentDir
69
- : intercomRootSetting !== undefined && intercomRootSetting !== ""
70
- ? isAbsolute(intercomRootSetting)
71
- ? intercomRootSetting
72
- : resolve(process.cwd(), intercomRootSetting)
73
- : p(ctx.home, ".pi", "agent");
74
- const intercomDir = p(intercomRoot, "intercom");
75
99
  if (!ctx.dryRun) ensureDirectory(intercomDir);
76
100
  syncWholeFile(
77
101
  ctx,
@@ -83,23 +107,33 @@ export async function ompSync(ctx: Ctx): Promise<OmpState> {
83
107
  // The plugin pass links this directory, so the files must exist first.
84
108
  syncKitPlugin(ctx);
85
109
 
86
- const legacyRegistryFile =
87
- paths.dataRoot === paths.configRoot ? undefined : p(paths.configRoot, "marketplaces.json");
88
- await syncMarketplace(ctx, p(paths.dataRoot, "marketplaces.json"), legacyRegistryFile);
89
- const pluginsInstalled = await syncPlugins(ctx);
90
- return { pluginsInstalled };
110
+ await syncMarketplace(ctx, paths);
111
+ const pluginsInstalled = await syncPlugins(ctx, paths);
112
+
113
+ // omp adopts `$XDG_DATA_HOME/omp` once it exists. When another sync created
114
+ // it during this run, a later omp process uses that root and does not see
115
+ // the plugins of the locked root. The next sync locks and fills the new root.
116
+ if (!ctx.dryRun) {
117
+ const currentRoot = ompPaths({
118
+ home: ctx.home,
119
+ env: process.env,
120
+ platform: ctx.services.platform.raw(),
121
+ }).dataRoot;
122
+ if (currentRoot !== paths.dataRoot) {
123
+ recordFailure(
124
+ ctx,
125
+ `omp data root moved to ${currentRoot} during the sync; run docks-kit sync again`,
126
+ );
127
+ }
128
+ }
129
+ return { pluginsInstalled, agentDir };
91
130
  }
92
131
 
93
132
  // -------------------------------------------------------------- summary ----
94
133
 
95
134
  export function ompSummary(ctx: Ctx, state: OmpState): void {
96
135
  const { echo } = ctx.services.logger;
97
- const agentDir = ompPaths({
98
- home: ctx.home,
99
- env: process.env,
100
- platform: ctx.services.platform.raw(),
101
- }).agentDir;
102
- echo(`omp: ${agentDir}`);
136
+ echo(`omp: ${state.agentDir}`);
103
137
  if (!ctx.dryRun) echo(`omp plugins: ${state.pluginsInstalled} installed`);
104
138
  }
105
139
 
@@ -1,8 +1,20 @@
1
1
  /**
2
- * Host-to-artifact map (Platform seam in DESIGN.md). Every launcher, installer,
3
- * build script, and release workflow selects a compiled binary from this one
4
- * table; cli/test/unit/hostTargets.test.ts parses those scripts and fails when
5
- * any of them drifts from it.
2
+ * Host-to-artifact map (Platform seam in DESIGN.md). The two launchers select
3
+ * a compiled binary from this table, `cli/build-binaries.sh` builds its
4
+ * targets, and `release-cli.yml` publishes its artifacts. Each of these files
5
+ * lists the names by hand, so `cli/test/unit/hostTargets.test.ts` checks them
6
+ * against this table:
7
+ * - the artifact names and `uname` keys in the Bash launcher `docks-kit`;
8
+ * - the artifact name and processor architecture in `docks-kit.ps1`;
9
+ * - the default `TARGETS` list of `cli/build-binaries.sh`;
10
+ * - the four artifact names in each of the two lists of
11
+ * `.github/workflows/release-cli.yml`: the `with.path` list of the
12
+ * `actions/upload-artifact` step in job `build`, and the `for asset in`
13
+ * list of the `gh release upload` step in job `github-release`.
14
+ * The same test also checks two facts outside this table: the generated Bun
15
+ * pin in the two launchers and the two installers equals the
16
+ * `SoT/toolchain.json` pin, and `docks-kit.ps1` and `install.ps1` hold only
17
+ * ASCII bytes.
6
18
  *
7
19
  * Membership here is the support matrix: adding a row is how a host becomes
8
20
  * supported, and `requireSupportedHost` in cli/src/engine.ts admits exactly the
@@ -54,7 +54,7 @@ export interface HostOs {
54
54
  readonly toolchainOs: string;
55
55
  /** Bubblewrap is the Linux-only Codex sandbox runtime. */
56
56
  readonly supportsBubblewrap: boolean;
57
- /** Directory-link mechanisms tried in order before `skillsSync.ts linkOrCopy` copies. */
57
+ /** Directory-link mechanisms tried in order before `skillsLinks.ts linkOrCopy` copies. */
58
58
  readonly directoryLinkKinds: ReadonlyArray<DirectoryLinkKind>;
59
59
  /** One-line install command for a tool whose package differs per OS. */
60
60
  readonly installHint: (tool: HintedTool) => string;
@@ -36,6 +36,32 @@ const TARGET_FLAGS = {
36
36
  omp: "syncOmp",
37
37
  } satisfies Record<Harness, TargetFlag>;
38
38
 
39
+ /**
40
+ * The rename hint for each retired sync flag. The engine prints it here, and
41
+ * the public CLI layer (`argvValidate.ts`) rejects the same flag with the same
42
+ * text, so the two paths cannot drift.
43
+ */
44
+ export const LEGACY_FLAG_HINTS = {
45
+ "--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
46
+ "--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
47
+ "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'",
48
+ "--omp": "--omp was renamed: pass the target as a word, e.g. 'sync omp'",
49
+ "--force": "--force was renamed to --reconcile",
50
+ "--remove-plugins":
51
+ "--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
52
+ "--680k": "--680k was renamed to --claude-compact-window=680k",
53
+ "--permissive": "--permissive was renamed to --claude-permissive",
54
+ "--supabase": "--supabase was renamed to --claude-plugin=supabase",
55
+ "--n8n": "--n8n was renamed to --claude-plugin=n8n",
56
+ "--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
57
+ } as const satisfies Record<string, string>;
58
+
59
+ type LegacyFlag = keyof typeof LEGACY_FLAG_HINTS;
60
+
61
+ /** Own-key check, so a word such as `constructor` never reads an Object prototype member. */
62
+ export const isLegacyFlag = (flag: string): flag is LegacyFlag =>
63
+ Object.hasOwn(LEGACY_FLAG_HINTS, flag);
64
+
39
65
  function selectTarget(ctx: Ctx, target: Harness): void {
40
66
  ctx[TARGET_FLAGS[target]] = true;
41
67
  ctx.targetFilterSet = true;
@@ -131,30 +157,14 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
131
157
  case "--codex":
132
158
  case "--agents":
133
159
  case "--omp":
134
- err(`${arg} was renamed: pass the target as a word, e.g. 'sync ${arg.slice(2)}'`);
135
- throw new ExitError(2);
136
160
  case "--force":
137
- err("--force was renamed to --reconcile");
138
- throw new ExitError(2);
139
161
  case "--remove-plugins":
140
- err(
141
- "--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
142
- );
143
- throw new ExitError(2);
144
162
  case "--680k":
145
- err("--680k was renamed to --claude-compact-window=680k");
146
- throw new ExitError(2);
147
163
  case "--permissive":
148
- err("--permissive was renamed to --claude-permissive");
149
- throw new ExitError(2);
150
164
  case "--supabase":
151
- err("--supabase was renamed to --claude-plugin=supabase");
152
- throw new ExitError(2);
153
165
  case "--n8n":
154
- err("--n8n was renamed to --claude-plugin=n8n");
155
- throw new ExitError(2);
156
166
  case "--skip-rtk":
157
- err("--skip-rtk was renamed to --skip-bubblewrap");
167
+ err(LEGACY_FLAG_HINTS[arg]);
158
168
  throw new ExitError(2);
159
169
  case "-h":
160
170
  case "--help":
@@ -0,0 +1,16 @@
1
+ /** Checks on other processes by PID. */
2
+
3
+ /**
4
+ * True only when no process has `pid`: `process.kill(pid, 0)` throws ESRCH.
5
+ * A live process, a process of another user (EPERM), and every other error
6
+ * give false. So a caller that removes the files of an exited process keeps
7
+ * them when it is not sure.
8
+ */
9
+ export function processExited(pid: number): boolean {
10
+ try {
11
+ process.kill(pid, 0);
12
+ return false;
13
+ } catch (cause) {
14
+ return typeof cause === "object" && cause !== null && "code" in cause && cause.code === "ESRCH";
15
+ }
16
+ }
@@ -24,6 +24,24 @@ export function kitCacheDir(home: string): string {
24
24
  return p(home, ".cache", "docks-kit");
25
25
  }
26
26
 
27
+ /** The `kitLock.ts` lock that `docks-kit tidy --apply` holds while it plans and applies. */
28
+ export function tidyApplyLockPath(home: string): string {
29
+ return join(kitCacheDir(home), "tidy-lock.db");
30
+ }
31
+
32
+ /** The `kitLock.ts` lock that `docks-kit sync` and `docks-kit model` hold while they write. */
33
+ export function syncLockPath(home: string): string {
34
+ return join(kitCacheDir(home), "sync-lock.db");
35
+ }
36
+
37
+ /**
38
+ * The `kitLock.ts` lock inside a Codex, agents, or omp folder that a sync
39
+ * writes. Syncs of different homes that share the folder all take it.
40
+ */
41
+ export function folderSyncLockPath(folder: string): string {
42
+ return join(folder, ".docks-kit-sync-lock.db");
43
+ }
44
+
27
45
  export function scratchRoot(home: string): string {
28
46
  return p(kitCacheDir(home), "scratch");
29
47
  }
@@ -47,8 +47,6 @@ export interface OmpSessionModel {
47
47
  // Session ceiling; absent when the model publishes no ladder, so no
48
48
  // invented level ever reaches a selector that omp must resolve.
49
49
  readonly thinking?: string;
50
- // Advisor level; absent when the model publishes no ladder.
51
- readonly advisorThinking?: string;
52
50
  }
53
51
 
54
52
  /**
@@ -1,12 +1,23 @@
1
1
  /**
2
2
  * EngineNative universal-skill install pass (`npx skills@<pin> add`) with
3
3
  * Claude symlink healing. Split from skillsSync.ts; the orchestration still
4
- * lives there.
4
+ * lives there. The pass records a slug as pending before its install only
5
+ * when the canonical directory does not exist (`skillsRecords.ts`). After
6
+ * the install, it moves the slug to the owned record when its directory
7
+ * exists. It writes both records before the next install starts. A canonical
8
+ * directory that existed before is reused and never recorded.
5
9
  */
6
10
  import { p, spawnProcess } from "./exec";
7
11
  import type { Ctx } from "./index";
8
12
  import { ExitError } from "./parseArgs";
9
13
  import { healClaudeSymlink, isDir } from "./skillsLinks";
14
+ import {
15
+ canonicalAbsent,
16
+ recordPendingInstall,
17
+ settlePendingSlug,
18
+ writeSkillRecords,
19
+ type SkillRecords,
20
+ } from "./skillsRecords";
10
21
  import { normalizeManifest, skillBase } from "./skillsManifest";
11
22
  import { field } from "./toolchain";
12
23
 
@@ -29,6 +40,7 @@ export async function syncUniversal(
29
40
  state: SkillsState,
30
41
  skillsDir: string,
31
42
  manifest: string,
43
+ records: SkillRecords,
32
44
  ): Promise<void> {
33
45
  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
34
46
  if (ctx.services.deps.probe("npx").state === "missing") {
@@ -60,19 +72,32 @@ export async function syncUniversal(
60
72
 
61
73
  if (isDir(p(skillsDir, base))) {
62
74
  already++;
75
+ if (!records.owned.has(slug) && !records.legacy.has(slug)) {
76
+ warn(
77
+ `Universal skill ${slug}: reused the existing ~/.agents/skills/${base}; the kit did not install it, so --prune keeps it`,
78
+ );
79
+ }
63
80
  if (healClaudeSymlink(ctx, skillsDir, base)) healed++;
64
81
  continue;
65
82
  }
66
83
 
84
+ const cli = skillsCli(ctx);
85
+ const pending = canonicalAbsent(skillsDir, slug);
86
+ if (pending) recordPendingInstall(records, slug);
67
87
  progress(`Installing universal skill ${slug}...`);
68
88
  const res = await spawnProcess(
69
89
  "npx",
70
- ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"],
90
+ ["--yes", cli, "add", slug, "-g", "-y", "-a", "claude-code", "codex"],
71
91
  {
72
92
  stdio: "ignore",
73
93
  },
74
94
  );
75
95
  clearProgress();
96
+ if (pending) {
97
+ // The owned record goes first, so a stop between the writes keeps the slug pending.
98
+ settlePendingSlug(records, skillsDir, slug);
99
+ writeSkillRecords(ctx, records);
100
+ }
76
101
  if (res.error === undefined && res.exitCode === 0) {
77
102
  added++;
78
103
  if (!isDir(p(skillsDir, base))) {