owenloop 0.5.9 → 0.5.11

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 (86) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1200 -166
  28. package/dist/src/defs.d.ts +41 -1
  29. package/dist/src/defs.js +461 -92
  30. package/dist/src/engine.d.ts +108 -22
  31. package/dist/src/engine.js +573 -85
  32. package/dist/src/factory.js +5 -3
  33. package/dist/src/hub.d.ts +77 -0
  34. package/dist/src/hub.js +162 -0
  35. package/dist/src/implements.d.ts +37 -0
  36. package/dist/src/implements.js +790 -0
  37. package/dist/src/index.d.ts +12 -10
  38. package/dist/src/index.js +7 -6
  39. package/dist/src/mcp/serve.js +254 -45
  40. package/dist/src/mcp/server.d.ts +10 -7
  41. package/dist/src/mcp/server.js +53 -8
  42. package/dist/src/model.d.ts +46 -10
  43. package/dist/src/model.js +224 -78
  44. package/dist/src/order-resolver.js +1 -0
  45. package/dist/src/store/def-source.d.ts +19 -0
  46. package/dist/src/store/def-source.js +87 -17
  47. package/dist/src/store/gc-recovery.d.ts +46 -0
  48. package/dist/src/store/gc-recovery.js +258 -0
  49. package/dist/src/store/gc.d.ts +94 -0
  50. package/dist/src/store/gc.js +563 -0
  51. package/dist/src/store/index.d.ts +3 -1
  52. package/dist/src/store/index.js +2 -0
  53. package/dist/src/store/install.d.ts +34 -5
  54. package/dist/src/store/install.js +73 -11
  55. package/dist/src/store/pre-commit-verifier.js +42 -2
  56. package/dist/src/store/snapshot-guard.d.ts +18 -0
  57. package/dist/src/store/snapshot-guard.js +94 -0
  58. package/dist/src/store.d.ts +66 -4
  59. package/dist/src/store.js +333 -12
  60. package/dist/src/types.d.ts +97 -17
  61. package/dist/src/types.js +4 -0
  62. package/dist/src/util.js +4 -1
  63. package/docs/authoring.md +214 -9
  64. package/docs/bundles.md +19 -0
  65. package/docs/cli.md +270 -30
  66. package/docs/crypto.md +13 -7
  67. package/docs/design.md +107 -46
  68. package/docs/evals/mcp-charter-baseline.json +428 -0
  69. package/docs/mcp-charter-eval.md +124 -0
  70. package/docs/shift-logs.md +18 -0
  71. package/docs/wire-contracts.md +28 -7
  72. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  73. package/examples/workflows/ship.yaml +28 -2
  74. package/package.json +2 -1
  75. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  76. package/plugins/claude-code/plugin/.mcp.json +1 -1
  77. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  78. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  79. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  80. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  81. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  82. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  83. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  84. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  85. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  86. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/dist/src/cli.js CHANGED
@@ -27,10 +27,10 @@
27
27
  * owenloop retract <wf> <path> --by <author> --text <msg>
28
28
  * owenloop skip <wf> <path> --by <author> --text <msg>
29
29
  * owenloop retry <wf> <path> [--by <author>] [--text <guidance>] clear a stall
30
- * owenloop close <wf> <run> [--outcome ok|no_work|failed|skipped] [--summary s]
30
+ * owenloop close <wf> <run> [--outcome ok|no_work|released|failed|skipped] [--summary s]
31
31
  * owenloop delete <wf> [--recursive]
32
32
  *
33
- * Global: --db <path> (env OWENLOOP_DB), --defs <dir> (env OWENLOOP_DEFS).
33
+ * Global: --db <path> (env OWENLOOP_DB), --defs <dir> (env OWENLOOP_DEFS), --verbose.
34
34
  */
35
35
  import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
36
36
  import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from 'node:path';
@@ -42,8 +42,9 @@ import { fileURLToPath } from 'node:url';
42
42
  import { parse as parseYaml } from 'yaml';
43
43
  import { Engine } from "./engine.js";
44
44
  import { buildGraph, buildTrace, graphToDot, graphToMermaid, hasDefiniteCheckDefect, modelCheck } from "./model.js";
45
- import { openStore } from "./store.js";
46
- import { buildDef, DefError, finalizeDefs, lintDef, loadDefFile, loadDefs, loadDefsRaw, loadDefsUnfinalized, resolveCallsTarget, validateDef, } from "./defs.js";
45
+ import { openStore, readRuntimeSnapshotBundlePins } from "./store.js";
46
+ import { buildDef, DefError, digestScopedCallsTargetKey, finalizeDefs, lintDef, loadDefFile, loadDefs, loadDefsRaw, loadDefsUnfinalized, expandDefsRaw, reportCallsCycles, resolveCallsTarget, scanDefsRaw, validateCallsEdges, validateDef, } from "./defs.js";
47
+ import { implementsIssues } from "./implements.js";
47
48
  import { createDefInstructionSource } from "./order-resolver.js";
48
49
  import { CliError, dbPathRefusingSymlink, detId, mkdirRefusingSymlink, nowMs, parseDurationMs, randId } from "./util.js";
49
50
  import { packageVersion } from "./package-version.js";
@@ -60,8 +61,11 @@ import { runMcpCommand } from "./mcp/serve.js";
60
61
  import { DEFAULT_TAR_LIMITS, extractTarGz } from "./untar.js";
61
62
  import { BundleError, digestBundle, inspectBundle, packBundle, unpackBundle } from "./bundle/index.js";
62
63
  import { acquireInstallLock, ADD_JOURNAL_FILENAME, archivePathViolation, commitInstall, finalizeInstallCommit, githubShaUrl, githubTarballUrl, installFolder, parkOldNameDir, parseRepoSpec, readLockfile, recoverInterruptedInstall, releaseInstallLock, removeAddJournal, rmRecursiveForce, rollbackInstallCommit, RollbackFailedError, stageFiles, STAGING_DIRNAME, writeAddJournal, writeLockfile, } from "./add.js";
63
- import { BundleIngestorUnavailableError, globalStoreRoot, installWorkflowBundle, inspectCasDefs, loadCasDefs, PreCommitVerifierUnavailableError, projectStoreRoot, createBundleIngestor, createPreCommitVerifier, recoverWorkflowStore, storeIndexPath, workflowStoreReplacementRecovery, workflowStoreStatePaths, } from "./store/index.js";
64
- import { asAgentIdentities, asCreateWorkflowOk, asCapabilityRerouteAdded, asCapabilityRerouteRemoved, asCapabilityReroutes, asCapabilityRouteAdded, asCapabilityRouteRemoved, asCapabilityRoutes, asCrewCreated, asCrewDeleted, asCrewMemberAdded, asCrewMemberRemoved, asCrews, asRoutingAlerts, asRunRouting, asWhoami, computeServerDiff, credentialBackend, createWorkflowError, credentialFilePath, credentialSlot, DEFAULT_HUB, externalCredentialCommand, hashDefForHub, hubBindingPath, keychainServiceFor, listStoredHubOrigins, normalizeOrigin, parseWorkflowList, pkcePair, randomState, readCredentialFile, readHubBinding, readStoredCredential, resolveEndpoint, resolveKeychain, writeCredentialFile, writeHubBinding, } from "./hub.js";
64
+ import { BundleIngestorUnavailableError, collectWorkflowStoreGarbage, compareStoreText, globalStoreRoot, installWorkflowBundle, inspectCasDefs, loadCasDefs, PreCommitVerifierUnavailableError, parseWorkflowCoordinate, projectStoreRoot, createBundleIngestor, createPreCommitVerifier, recoverWorkflowStore, storeIndexPath, workflowStoreReplacementRecovery, workflowStoreStatePaths, } from "./store/index.js";
65
+ import { recoverInterruptedWorkflowStoreGc } from "./store/gc-recovery.js";
66
+ import { asAgentIdentities, asCreateWorkflowOk, capabilityPublishReportText, asCapabilityRerouteAdded, asCapabilityRerouteRemoved, asCapabilityReroutes, asCapabilityRouteAdded, asCapabilityRouteRemoved, asCapabilityRoutes, asCrewCreated, asCrewDeleted, asCrewMemberAdded, asCrewMemberRemoved, asCrews, asRoutingAlerts, asRunRouting, asWhoami, computeServerDiff, credentialBackend, createWorkflowError, credentialFilePath, credentialSlot, DEFAULT_HUB, externalCredentialCommand, hashDefForHub, hubBindingPath, keychainServiceFor, listStoredHubOrigins, normalizeOrigin, parseWorkflowList, pkcePair, randomState, readCredentialFile, readHubBinding, readStoredCredential, resolveEndpoint, resolveKeychain, writeCredentialFile, writeHubBinding, } from "./hub.js";
67
+ import { fetchCapabilityMappings, recordCapabilityMappings } from "./capability-mapping-client.js";
68
+ import { MODIFIER_SEPARATOR } from "./capabilities.js";
65
69
  import { loadSettings, settingsPath as executionSettingsPath } from "../packages/work/src/settings/settings.js";
66
70
  import { discoverCrewRosterFiles, crewRosterPath, effectiveRosterLayers, explainRosterShadows, mergeRosterLayers } from "../packages/work/src/settings/roster.js";
67
71
  import { readHubRosterCache, syncHubRosterCache } from "../packages/work/src/settings/hub-roster-cache.js";
@@ -162,6 +166,8 @@ const BOOLEAN_FLAGS = new Set([
162
166
  // bundle path/URL must stay a positional.
163
167
  'global',
164
168
  'unsigned',
169
+ 'verbose',
170
+ 'yes',
165
171
  ]);
166
172
  function parseArgs(argv) {
167
173
  const positionals = [];
@@ -223,6 +229,12 @@ function need(args, idx, label) {
223
229
  throw new CliError(`missing required argument: ${label}`);
224
230
  return v;
225
231
  }
232
+ const WORKFLOW_ID_RE = /^wf_[0-9a-f]{24}$/u;
233
+ function assertWorkflowIdShape(workflow) {
234
+ if (!WORKFLOW_ID_RE.test(workflow)) {
235
+ throw new CliError(`invalid workflow id '${workflow}': expected wf_ followed by 24 lowercase hexadecimal characters`);
236
+ }
237
+ }
226
238
  function needOpt(args, key) {
227
239
  const v = last(args, key);
228
240
  if (v === undefined)
@@ -321,19 +333,14 @@ function finalizeDiscoveredDefs(merged, tolerantCasInspection, definitionDiscove
321
333
  * fail-closed validation in add.ts is untouched — we consume `readLockfile`,
322
334
  * discovery merely refuses to act on a bad ledger rather than crashing.)
323
335
  */
324
- function loadDefsWithInstalled(io, defsDir, tolerantCasInspection = false) {
325
- const merged = existsSync(defsDir) ? loadDefsUnfinalized(defsDir) : new Map();
336
+ function foldInstalledDefs(io, defsDir, merged, scan) {
326
337
  let lf;
327
338
  try {
328
339
  lf = readLockfile(join(io.cwd, '.owenloop', 'installed.json'));
329
340
  }
330
341
  catch (e) {
331
342
  io.err(`warning: skipping installed workflow defs: ${e.message}`);
332
- const definitionDiscoveryComplete = foldCasDefs(io, defsDir, merged, tolerantCasInspection);
333
- return {
334
- defs: finalizeDiscoveredDefs(merged, tolerantCasInspection, definitionDiscoveryComplete),
335
- definitionDiscoveryComplete,
336
- };
343
+ return;
337
344
  }
338
345
  for (const source of Object.keys(lf.installed).sort()) {
339
346
  const entry = lf.installed[source];
@@ -346,7 +353,7 @@ function loadDefsWithInstalled(io, defsDir, tolerantCasInspection = false) {
346
353
  }
347
354
  let entryRaw;
348
355
  try {
349
- entryRaw = loadDefsUnfinalized(entryDir);
356
+ entryRaw = scan(entryDir);
350
357
  }
351
358
  catch (e) {
352
359
  io.err(`warning: failed to load installed defs for ${source} (${entry.path}): ${e.message}`);
@@ -361,7 +368,13 @@ function loadDefsWithInstalled(io, defsDir, tolerantCasInspection = false) {
361
368
  merged.set(name, def);
362
369
  }
363
370
  }
364
- const definitionDiscoveryComplete = foldCasDefs(io, defsDir, merged, tolerantCasInspection);
371
+ }
372
+ function loadDefsWithInstalled(io, defsDir, tolerantCasInspection = false, verbose = false) {
373
+ const merged = existsSync(defsDir) ? loadDefsUnfinalized(defsDir) : new Map();
374
+ // Preserve executable discovery's long-standing whole-folder policy: a bad
375
+ // installed folder is warned about and skipped rather than partially loaded.
376
+ foldInstalledDefs(io, defsDir, merged, loadDefsUnfinalized);
377
+ const definitionDiscoveryComplete = foldCasDefs(io, defsDir, merged, tolerantCasInspection, verbose);
365
378
  return {
366
379
  defs: finalizeDiscoveredDefs(merged, tolerantCasInspection, definitionDiscoveryComplete),
367
380
  definitionDiscoveryComplete,
@@ -391,7 +404,7 @@ function loadDefsWithInstalled(io, defsDir, tolerantCasInspection = false) {
391
404
  * When no store exists (no `index.json` at either root) this is a no-op and the
392
405
  * merged map is byte-identical to what it was before WS-6.
393
406
  */
394
- function foldCasDefs(io, defsDir, merged, tolerantInspection = false) {
407
+ function foldCasDefs(io, defsDir, merged, tolerantInspection = false, verbose = false) {
395
408
  // Without HOME/USERPROFILE, retain project discovery and consult a guaranteed
396
409
  // absent synthetic global root instead of silently dropping the project store.
397
410
  let globalRoot;
@@ -405,6 +418,7 @@ function foldCasDefs(io, defsDir, merged, tolerantInspection = false) {
405
418
  projectRoot: projectStoreRoot(defsDir),
406
419
  globalRoot,
407
420
  warn: (line) => io.err(line),
421
+ verbose,
408
422
  };
409
423
  const discovery = tolerantInspection
410
424
  ? inspectCasDefs(discoveryArgs)
@@ -421,6 +435,67 @@ function foldCasDefs(io, defsDir, merged, tolerantInspection = false) {
421
435
  }
422
436
  return discovery.complete;
423
437
  }
438
+ function loadDefsRawWithInstalled(io, defsDir, failures, verbose = false) {
439
+ const merged = existsSync(defsDir) ? scanDefsRaw(defsDir, failures) : new Map();
440
+ foldInstalledDefs(io, defsDir, merged, (dir) => {
441
+ try {
442
+ // Match executable discovery exactly: one malformed or duplicate member
443
+ // invalidates the installed folder. Retain the failed folder as a lint
444
+ // result while foldInstalledDefs emits the shared warning.
445
+ return loadDefsUnfinalized(dir);
446
+ }
447
+ catch (e) {
448
+ failures.push({ file: dir, error: e.message });
449
+ throw e;
450
+ }
451
+ });
452
+ foldCasDefs(io, defsDir, merged, false, verbose);
453
+ return { rawDefs: merged, defs: expandDefsRaw(merged) };
454
+ }
455
+ function loadDefsForAuthoring(io, args, failures) {
456
+ // This deliberately checks override *presence*, rather than whether its path
457
+ // happens to equal cwd/workflows, matching openCtx exactly.
458
+ const defsOverride = last(args, 'defs') ?? io.env.OWENLOOP_DEFS;
459
+ const defsDir = defsOverride ?? join(io.cwd, 'workflows');
460
+ let loaded;
461
+ if (defsOverride !== undefined) {
462
+ const rawDefs = existsSync(defsDir) ? scanDefsRaw(defsDir, failures) : new Map();
463
+ loaded = { rawDefs, defs: expandDefsRaw(rawDefs) };
464
+ }
465
+ else {
466
+ loaded = loadDefsRawWithInstalled(io, defsDir, failures, flag(args, 'verbose'));
467
+ }
468
+ return { defsDir, ...loaded };
469
+ }
470
+ function cycleErrorsByDefKey(defs) {
471
+ const errors = new Map();
472
+ const aliases = new Map();
473
+ for (const [key, def] of defs) {
474
+ // The CAS loader registers one physical def under coordinate, digest-scoped,
475
+ // and package/workflow aliases. Treat those aliases as one logical def so a
476
+ // cycle discovered through the resolver's first key is visible through every
477
+ // name an operator can select.
478
+ const identity = def.bundleDigest === undefined ? key : `${def.bundleDigest}\u0000${def.name}`;
479
+ const keys = aliases.get(identity) ?? [];
480
+ keys.push(key);
481
+ aliases.set(identity, keys);
482
+ }
483
+ for (const finding of reportCallsCycles(defs)) {
484
+ for (const key of finding.members) {
485
+ const def = defs.get(key);
486
+ if (def === undefined)
487
+ continue;
488
+ const identity = def.bundleDigest === undefined ? key : `${def.bundleDigest}\u0000${def.name}`;
489
+ for (const alias of aliases.get(identity) ?? []) {
490
+ const messages = errors.get(alias) ?? [];
491
+ if (!messages.includes(finding.message))
492
+ messages.push(finding.message);
493
+ errors.set(alias, messages);
494
+ }
495
+ }
496
+ }
497
+ return errors;
498
+ }
424
499
  function openCtx(io, args, tolerantCasInspection = false) {
425
500
  const dbOverride = last(args, 'db') ?? io.env.OWENLOOP_DB;
426
501
  const dbPath = dbOverride ?? join(io.cwd, '.owenloop', 'state.db');
@@ -439,7 +514,7 @@ function openCtx(io, args, tolerantCasInspection = false) {
439
514
  defs: existsSync(defsDir) ? loadDefs(defsDir) : new Map(),
440
515
  definitionDiscoveryComplete: true,
441
516
  }
442
- : loadDefsWithInstalled(io, defsDir, tolerantCasInspection);
517
+ : loadDefsWithInstalled(io, defsDir, tolerantCasInspection, flag(args, 'verbose'));
443
518
  const { defs, definitionDiscoveryComplete } = loaded;
444
519
  // Guard the built-in default (`cwd/.owenloop/state.db`) against a symlinked
445
520
  // `.owenloop` from a hostile checkout (SEC-3). Directory guard first, then the
@@ -465,8 +540,10 @@ function openCtx(io, args, tolerantCasInspection = false) {
465
540
  // `finalizeDefs` validated against at load time, so load-time and run-time
466
541
  // agree). With `from` absent — every other resolver caller — this is the plain
467
542
  // flat-map lookup it has always been.
468
- const engine = new Engine(store, (name, from) => {
469
- const d = from === undefined ? defs.get(name) : resolveCallsTarget(defs, name, from);
543
+ const engine = new Engine(store, (name, from, bundleDigest) => {
544
+ const d = bundleDigest !== undefined
545
+ ? defs.get(digestScopedCallsTargetKey(bundleDigest, name)) ?? defs.get(name)
546
+ : from === undefined ? defs.get(name) : resolveCallsTarget(defs, name, from);
470
547
  if (!d)
471
548
  throw new CliError(`unknown workflow definition '${name}' (looked in ${defsDir})`);
472
549
  return d;
@@ -525,10 +602,17 @@ function printBundleInspectResult(io, result) {
525
602
  * the stderr message so scripts can match on it.
526
603
  */
527
604
  function dispatchBundle(io, args) {
528
- const sub = need(args, 1, 'pack|unpack|inspect|digest');
605
+ const sub = need(args, 1, 'pack|unpack|inspect|digest|gc');
529
606
  if (sub !== 'pack' && args.options.has('output')) {
530
607
  throw new CliError(`owenloop bundle ${sub}: --output is only valid for pack`);
531
608
  }
609
+ if (sub !== 'gc') {
610
+ for (const option of ['keep', 'yes', 'global']) {
611
+ if (args.options.has(option)) {
612
+ throw new CliError(`owenloop bundle ${sub}: --${option} is only valid for bundle gc`);
613
+ }
614
+ }
615
+ }
532
616
  switch (sub) {
533
617
  case 'pack': {
534
618
  assertBundlePositionals(args, 3, 'owenloop bundle pack <source-dir> [--output <bundle.wnlp>]');
@@ -577,8 +661,10 @@ function dispatchBundle(io, args) {
577
661
  print(io, { digest: result.digest });
578
662
  return 0;
579
663
  }
664
+ case 'gc':
665
+ throw new CliError('owenloop bundle gc requires the async entry point');
580
666
  default:
581
- throw new CliError(`owenloop bundle: unknown subcommand '${sub}' (expected pack, unpack, inspect, or digest)`);
667
+ throw new CliError(`owenloop bundle: unknown subcommand '${sub}' (expected pack, unpack, inspect, digest, or gc)`);
582
668
  }
583
669
  }
584
670
  /** `--output` requires a following value; a bare flag is not a default path. */
@@ -1105,7 +1191,7 @@ function sleepMs(ms) {
1105
1191
  // ---- commands ----------------------------------------------------------------
1106
1192
  export const USAGE = `owenloop — a dataflow workflow engine
1107
1193
 
1108
- Usage: owenloop <command> [args] [--db <path>] [--defs <dir>]
1194
+ Usage: owenloop <command> [args] [--db <path>] [--defs <dir>] [--verbose]
1109
1195
 
1110
1196
  Commands:
1111
1197
  defs list available workflow definitions
@@ -1118,6 +1204,8 @@ Commands:
1118
1204
  bundle unpack <bundle.wnlp> <destination-dir> unpack a .wnlp bundle into a new directory
1119
1205
  bundle inspect <bundle.wnlp> strictly validate a .wnlp bundle and print its manifest/entries
1120
1206
  bundle digest <bundle.wnlp> print the bundle's def digest (SHA-256 of the canonical tar)
1207
+ bundle gc [--keep <n>] [--global] [--yes]
1208
+ ${' '.repeat(41)}dry-run or collect superseded content-addressed store objects
1121
1209
  publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <origin>]
1122
1210
  pack a bundle and sign its canonical digest (signed by default)
1123
1211
  trust init [--force] create the local Ed25519 enrollment root
@@ -1128,9 +1216,13 @@ Commands:
1128
1216
  login [--hub <url>] [--with-token] [--as <slot>] authenticate the CLI against a hub, verified via whoami (loopback OAuth, or --with-token from stdin)
1129
1217
  logout [--hub <url>] [--as <slot>] delete the stored credential for a hub in one slot
1130
1218
  connect [--hub <url>] [--as <slot>] bind this project to a hub and verify the stored credential (whoami)
1131
- push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <origin>] [--as <slot>]
1219
+ push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <origin>] [--as <slot>] [--map <authored>=<org>]
1132
1220
  publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (server-diffed, idempotent)
1133
1221
  --as names the credential slot: human (default), agent, or agent:<account>
1222
+ --map records one authored=org capability mapping (repeatable); without it push records none
1223
+ install <owner>/<repo>[@ref] [<defName>...] [--map <authored>=<org>] [--accept-defaults] [--dry-run] [--hub <origin>] [--as <slot>]
1224
+ publish an OUTSIDE repo's defs to your hub under SCOPED capabilities (<defName>.<capability> by default)
1225
+ records the capability mapping BEFORE it publishes; it never writes into local workflows/ (that is \`add\`)
1134
1226
  start <defName> [--provide name=json ...] [--crew <name>] [--title <text>] [--modifier <name>] [--scope <label>] [--priority <low|normal|high>] [--hub <url>]
1135
1227
  ${' '.repeat(41)}start a published workflow on the bound hub (human credential)
1136
1228
  ${' '.repeat(41)}--modifier names one value from the def's declared \`modifiers:\` set; every
@@ -1139,6 +1231,7 @@ ${' '.repeat(41)}the run carries no modifier and its steps are offered on BARE c
1139
1231
  ${' '.repeat(41)}--scope is a free routing label recorded on the run — no registry, no fixed set.
1140
1232
  ${' '.repeat(41)}Omit it and the run is routed by the org's routes alone.
1141
1233
  ${' '.repeat(41)}--priority is one of low, normal, high. Omit it and the hub applies normal.
1234
+ pending-gates --hub <url> list human-input gates currently blocking hub-hosted workflows (no local-engine form)
1142
1235
  cancel <workflow> [--reason <text>] [--hub <url>]
1143
1236
  ${' '.repeat(41)}cancel a running instance on the bound hub (human credential; agents cannot cancel).
1144
1237
  ${' '.repeat(41)}Closes every open lease so the run stops being re-offered, and records the
@@ -1158,7 +1251,7 @@ ${' '.repeat(41)}one run and flips to oldest first. A \`binding-gap\` alert mean
1158
1251
  ${' '.repeat(41)}offer because its compound capability had no live crew binding.
1159
1252
  routing show <workflow> [--hub <url>]
1160
1253
  ${' '.repeat(41)}print one HUB run's routing: modifier, wait policy, alerts, resolution reports
1161
- ${' '.repeat(41)}and escalations. Unrelated to the local \`show\`, which reads a def from sqlite.
1254
+ ${' '.repeat(41)}and escalations. Unrelated to the local \`show\`, which reads raw artifacts from sqlite.
1162
1255
  routing rule list [--hub <url>] list the org's capability reroute rules in the order the hub tries them
1163
1256
  routing rule add <capability> <target> [--position <n>] [--hub <url>] add one reroute rule — offer <capability> as <target> when it has no live crew binding (admin; idempotent per pair; no --position appends)
1164
1257
  routing rule rm <capability> <target> [--hub <url>] remove one reroute rule (admin; a rule that was never there is a no-op)
@@ -1188,7 +1281,7 @@ ${' '.repeat(41)}refresh the local hub-rosters cache with an agent credential
1188
1281
  check <def> [--format text|json] [--max-depth N] [--max-states N] [--max-collection N] [--assume-provided] [--strict-inputs]
1189
1282
  bounded reachability check (stall states, true deadlocks, stuck, dead steps, declared invariants)
1190
1283
  create <def> [--title t] [--provide name=json ...] [--param k=v ...]
1191
- provide <wf> <name> [--value json] supply an owed (seedOwed) input
1284
+ provide <wf> <name> [--value json] [--hub <url>] supply an owed (seedOwed) input
1192
1285
  adopt <wf> re-pin an instance to the current def (§28); settles new debts
1193
1286
  tick <wf> [--now <ms>] [--shallow] [--capability <c>]... pull eligible orders (deep: also from calls: children; --shallow for this instance only; --capability filters to matching-capability steps)
1194
1287
  reap <wf> [--now] run the reaper; --now forces every claim stale (TTL 0)
@@ -1204,16 +1297,17 @@ ${' '.repeat(41)}refresh the local hub-rosters cache with an agent credential
1204
1297
  green <wf> <run> <path> [--value json] [--terminal]
1205
1298
  emit <wf> <run> --items '[{...}]' accrete collection elements
1206
1299
  seal <wf> <run> [--value json] signal a collection is complete
1207
- reject <wf> <path> --by <author> --text <msg>
1300
+ reject <wf> <path> --by <author> --text <msg> [--requested <modifier>] [--hub <url>]
1208
1301
  retract <wf> <path> --by <author> --text <msg>
1209
1302
  skip <wf> <path> --by <author> --text <msg>
1210
1303
  retry <wf> <path> [--by <author>] [--text <guidance>] [--hub <url>] clear a §6 stall, or ANSWER an ask
1211
1304
  ask <wf> <path> <question> [--by <author>] hold an owed artifact on a question for a human
1212
1305
  inbox every held question across all instances, with its answer command
1213
1306
  heartbeat <wf> <run> [--now <ms>] touch liveness timestamp on an open run
1214
- close <wf> <run> [--outcome ok|no_work|failed|skipped] [--summary s]
1307
+ close <wf> <run> [--outcome ok|no_work|released|failed|skipped] [--summary s]
1215
1308
  delete <wf> [--recursive] refuse if children exist unless --recursive (cascades)
1216
1309
 
1310
+ Global: --verbose lists detailed superseded bundle-version notices.
1217
1311
  Environment: OWENLOOP_DB, OWENLOOP_DEFS`;
1218
1312
  /** Append parse failures to a "definition not found" error — the def the user asked for may be in one of the broken files. */
1219
1313
  function failureNote(failures) {
@@ -1232,7 +1326,7 @@ export { hasDefiniteCheckDefect };
1232
1326
  * even on commands that ignore them — to avoid rejecting a documented
1233
1327
  * invocation.
1234
1328
  */
1235
- const GLOBAL_OPTIONS = ['db', 'defs'];
1329
+ const GLOBAL_OPTIONS = ['db', 'defs', 'verbose'];
1236
1330
  /** Build a command's option allowlist: the two globals plus its own long-form flags. */
1237
1331
  const cmdOpts = (...extra) => new Set([...GLOBAL_OPTIONS, ...extra]);
1238
1332
  /**
@@ -1252,14 +1346,16 @@ export const COMMAND_OPTIONS = new Map([
1252
1346
  ['help', cmdOpts()],
1253
1347
  ['defs', cmdOpts()],
1254
1348
  ['add', cmdOpts('recover', 'global')],
1255
- ['bundle', cmdOpts('output')],
1349
+ ['bundle', cmdOpts('output', 'keep', 'yes', 'global')],
1256
1350
  ['login', cmdOpts('hub', 'with-token', 'as')],
1257
1351
  ['logout', cmdOpts('hub', 'as')],
1258
1352
  ['connect', cmdOpts('hub', 'as')],
1259
1353
  ['publish', cmdOpts('unsigned', 'output', 'source', 'hub')],
1260
1354
  ['trust', cmdOpts('force', 'key', 'principal', 'pools', 'labels', 'namespaces', 'delegate', 'signing-key', 'output', 'reason', 'effective-from')],
1261
- ['push', cmdOpts('dry-run', 'force', 'hub', 'as', 'bundle')],
1355
+ ['push', cmdOpts('dry-run', 'force', 'hub', 'as', 'bundle', 'map')],
1356
+ ['install', cmdOpts('hub', 'as', 'map', 'accept-defaults', 'dry-run')],
1262
1357
  ['start', cmdOpts('hub', 'crew', 'title', 'provide', 'modifier', 'scope', 'priority')],
1358
+ ['pending-gates', cmdOpts('hub')],
1263
1359
  ['cancel', cmdOpts('hub', 'reason')],
1264
1360
  ['instance', cmdOpts('hub')],
1265
1361
  ['agent', cmdOpts('crews', 'hub', 'scopes', 'shift')],
@@ -1280,7 +1376,7 @@ export const COMMAND_OPTIONS = new Map([
1280
1376
  ['lint', cmdOpts()],
1281
1377
  ['check', cmdOpts('format', 'max-depth', 'max-states', 'max-collection', 'assume-provided', 'strict-inputs')],
1282
1378
  ['create', cmdOpts('title', 'provide', 'param')],
1283
- ['provide', cmdOpts('value')],
1379
+ ['provide', cmdOpts('value', 'hub')],
1284
1380
  ['adopt', cmdOpts()],
1285
1381
  ['tick', cmdOpts('now', 'shallow', 'capability')],
1286
1382
  ['reap', cmdOpts('now')],
@@ -1294,7 +1390,7 @@ export const COMMAND_OPTIONS = new Map([
1294
1390
  ['green', cmdOpts('value', 'terminal')],
1295
1391
  ['emit', cmdOpts('items')],
1296
1392
  ['seal', cmdOpts('value')],
1297
- ['reject', cmdOpts('by', 'text', 'requested')],
1393
+ ['reject', cmdOpts('by', 'text', 'requested', 'hub')],
1298
1394
  ['retract', cmdOpts('by', 'text')],
1299
1395
  ['skip', cmdOpts('by', 'text')],
1300
1396
  ['retry', cmdOpts('by', 'text', 'hub')],
@@ -1830,6 +1926,17 @@ async function dispatchRoster(io, args) {
1830
1926
  print(io, { ok: true, hub: origin, result });
1831
1927
  return 0;
1832
1928
  }
1929
+ /**
1930
+ * Authoring-only lint additions belong here rather than in defs.ts: the
1931
+ * engine's vendored surface keeps extension contents opaque. Base hard errors
1932
+ * deliberately suppress advisory extension warnings just like lintDef does.
1933
+ */
1934
+ function lintForAuthoring(def) {
1935
+ const result = lintDef(def);
1936
+ return result.errors.length === 0
1937
+ ? { ...result, warnings: [...result.warnings, ...implementsIssues(def)] }
1938
+ : result;
1939
+ }
1833
1940
  function dispatch(command, io, args) {
1834
1941
  // help and lint need no store
1835
1942
  if (command === 'help' || command === '--help' || command === '-h') {
@@ -1837,26 +1944,28 @@ function dispatch(command, io, args) {
1837
1944
  return 0;
1838
1945
  }
1839
1946
  if (command === 'lint') {
1840
- const defsDir = last(args, 'defs') ?? io.env.OWENLOOP_DEFS ?? join(io.cwd, 'workflows');
1841
1947
  const failures = [];
1842
- const defs = existsSync(defsDir) ? loadDefsRaw(defsDir, failures) : new Map();
1948
+ const { defsDir, rawDefs, defs } = loadDefsForAuthoring(io, args, failures);
1949
+ const cycleErrors = cycleErrorsByDefKey(defs);
1843
1950
  const defName = args.positionals[1];
1844
1951
  let hasErrors = false;
1845
1952
  if (defName !== undefined) {
1846
1953
  const def = defs.get(defName);
1847
1954
  if (!def)
1848
1955
  throw new CliError(`unknown workflow definition '${defName}' (looked in ${defsDir})${failureNote(failures)}`);
1849
- const result = lintDef(def);
1850
- if (result.errors.length)
1956
+ const result = lintForAuthoring(def);
1957
+ const errors = [...validateCallsEdges(def, rawDefs), ...result.errors, ...(cycleErrors.get(defName) ?? [])];
1958
+ if (errors.length)
1851
1959
  hasErrors = true;
1852
- print(io, { def: def.name, errors: result.errors, warnings: result.warnings });
1960
+ print(io, { def: def.name, errors, warnings: errors.length ? [] : result.warnings });
1853
1961
  }
1854
1962
  else {
1855
- const results = [...defs.values()].map((def) => {
1856
- const result = lintDef(def);
1857
- if (result.errors.length)
1963
+ const results = [...defs].map(([key, def]) => {
1964
+ const result = lintForAuthoring(def);
1965
+ const errors = [...validateCallsEdges(def, rawDefs), ...result.errors, ...(cycleErrors.get(key) ?? [])];
1966
+ if (errors.length)
1858
1967
  hasErrors = true;
1859
- return { def: def.name, errors: result.errors, warnings: result.warnings };
1968
+ return { def: def.name, errors, warnings: errors.length ? [] : result.warnings };
1860
1969
  });
1861
1970
  // Files that never became defs (malformed YAML / bad shape) are lint errors
1862
1971
  // too — omitting them makes `lint` claim a dir is clean when `create` would die.
@@ -1871,18 +1980,23 @@ function dispatch(command, io, args) {
1871
1980
  return 0;
1872
1981
  }
1873
1982
  if (command === 'check') {
1874
- const defsDir = last(args, 'defs') ?? io.env.OWENLOOP_DEFS ?? join(io.cwd, 'workflows');
1875
1983
  const failures = [];
1876
- const defs = existsSync(defsDir) ? loadDefsRaw(defsDir, failures) : new Map();
1984
+ const { defsDir, rawDefs, defs } = loadDefsForAuthoring(io, args, failures);
1985
+ const cycleErrors = cycleErrorsByDefKey(defs);
1877
1986
  const defName = need(args, 1, 'def');
1878
1987
  const def = defs.get(defName);
1879
1988
  if (!def) {
1880
1989
  throw new CliError(`unknown workflow definition '${defName}' (looked in ${defsDir}).\n` +
1881
1990
  `Known definitions: ${[...defs.keys()].sort().join(', ') || '(none)'}${failureNote(failures)}`);
1882
1991
  }
1883
- // loadDefsRaw uses buildDef (no semantic validation); run validateDef here so
1884
- // invariant stem-reference / duplicate-name errors surface to the author.
1885
- const defErrors = validateDef(def);
1992
+ // Authoring discovery uses buildDef (no semantic validation); run
1993
+ // validateDef here so invariant stem-reference / duplicate-name errors
1994
+ // surface to the author.
1995
+ const defErrors = [
1996
+ ...validateCallsEdges(def, rawDefs),
1997
+ ...validateDef(def),
1998
+ ...(cycleErrors.get(defName) ?? []),
1999
+ ];
1886
2000
  if (defErrors.length > 0) {
1887
2001
  throw new CliError(`workflow '${def.name}' has validation errors:\n - ${defErrors.join('\n - ')}`);
1888
2002
  }
@@ -1918,9 +2032,13 @@ function dispatch(command, io, args) {
1918
2032
  io.out(`SEARCH INCOMPLETE — bounds hit: ${report.boundsHit.join(', ')}`);
1919
2033
  io.out('Verdicts apply only within the explored region.');
1920
2034
  }
2035
+ if (report.collectionCapApplied) {
2036
+ io.out('');
2037
+ io.out(`COLLECTION CAP APPLIED — --max-collection ${report.maxCollectionSize} limited each emit/seal fork to 0..${report.maxCollectionSize} members.`);
2038
+ }
1921
2039
  if (report.stallStates.length > 0) {
1922
2040
  io.out('');
1923
- io.out(`Stall states (expected — maxAttempts / human-escalation brakes) (${report.stallStates.length}):`);
2041
+ io.out(`Stall states (expected — retryable brakes / future idle waits) (${report.stallStates.length}):`);
1924
2042
  for (const s of report.stallStates) {
1925
2043
  io.out(` path: ${s.path.map((p) => `${p.step}/${p.outcome}`).join(' -> ') || '(initial state)'}`);
1926
2044
  }
@@ -1999,9 +2117,10 @@ function dispatch(command, io, args) {
1999
2117
  // - definite (true) deadlock only when EXHAUSTIVE (!bounded) → nonzero
2000
2118
  // - stall states and stuck states are by-design brakes and NEVER affect the
2001
2119
  // exit code — a stall state (report.stallStates) is EXPECTED (a human-
2002
- // escalation brake whose freeze, once lifted, re-arms a producer), and a
2003
- // stuck state (report.stuck) is purely informational (a brake tripped on
2004
- // one branch while the line still moves on another). Neither is a defect.
2120
+ // escalation brake whose freeze, once lifted, re-arms a producer, or an
2121
+ // idle wait that becomes eligible after time passes), and a stuck state
2122
+ // (report.stuck) is purely informational (a brake tripped on one branch
2123
+ // while the line still moves on another). Neither is a defect.
2005
2124
  // - truncated with no invariant violations / structurally-dead steps / true
2006
2125
  // deadlocks → 0
2007
2126
  const hasDefiniteDefect = hasDefiniteCheckDefect(report);
@@ -2012,13 +2131,17 @@ function dispatch(command, io, args) {
2012
2131
  }
2013
2132
  return 0;
2014
2133
  }
2015
- // The bundle namespace is pure filesystem work on the bytes the user
2016
- // points at — dispatched BEFORE openCtx so pack/inspect/digest neither
2017
- // open/create `.owenloop/state.db` nor touch a remote (same reasoning as
2018
- // lint/check above; see docs/cli.md).
2134
+ // Package-format bundle commands are pure filesystem work on bytes the user
2135
+ // points at. GC also dispatches before openCtx, but its async branch performs
2136
+ // its own read-only snapshot scan and targeted store collection.
2019
2137
  if (command === 'bundle') {
2020
2138
  return dispatchBundle(io, args);
2021
2139
  }
2140
+ // Pending gates exist only on the hub. Reject the local spelling before
2141
+ // openCtx() so this cannot create or inspect a local SQLite state database.
2142
+ if (command === 'pending-gates') {
2143
+ throw new CliError('owenloop pending-gates has no local-engine equivalent; pass --hub <url>');
2144
+ }
2022
2145
  const ctx = openCtx(io, args, command === 'status');
2023
2146
  const { engine, store } = ctx;
2024
2147
  if (command === 'status' && !ctx.definitionDiscoveryComplete) {
@@ -2032,6 +2155,11 @@ function dispatch(command, io, args) {
2032
2155
  title: d.title ?? null,
2033
2156
  inputs: d.inputs.map((i) => i.name),
2034
2157
  steps: d.steps.map((l) => l.name),
2158
+ inputSchemas: d.inputs.map((i) => ({
2159
+ name: i.name,
2160
+ ...(i.schema === undefined ? {} : { schema: i.schema }),
2161
+ })),
2162
+ ...(d.x === undefined ? {} : { x: d.x }),
2035
2163
  })));
2036
2164
  return 0;
2037
2165
  }
@@ -2174,6 +2302,9 @@ function dispatch(command, io, args) {
2174
2302
  }
2175
2303
  case 'show': {
2176
2304
  const wf = need(args, 1, 'workflow');
2305
+ if (store.getWorkflow(wf) === undefined) {
2306
+ throw new CliError(`no such workflow instance: ${wf}`);
2307
+ }
2177
2308
  print(io, store.listArtifacts(wf));
2178
2309
  return 0;
2179
2310
  }
@@ -2701,6 +2832,152 @@ function optionalWorkflowRecoveryMarkerDir(io) {
2701
2832
  const home = [io.env.HOME, io.env.USERPROFILE].find((value) => value !== undefined && value.trim() !== '');
2702
2833
  return home === undefined ? undefined : defaultRecoveryMarkerDir(home);
2703
2834
  }
2835
+ const DEFAULT_BUNDLE_GC_KEEP = 2;
2836
+ function bundleGcKeep(args) {
2837
+ if (args.missingOptionValues.has('keep')) {
2838
+ throw new CliError('owenloop bundle gc: --keep requires a positive integer value');
2839
+ }
2840
+ const raw = last(args, 'keep');
2841
+ if (raw === undefined)
2842
+ return DEFAULT_BUNDLE_GC_KEEP;
2843
+ if (!/^[1-9][0-9]*$/u.test(raw)) {
2844
+ throw new CliError(`owenloop bundle gc: invalid --keep '${raw}' (expected a positive integer)`);
2845
+ }
2846
+ const keep = Number(raw);
2847
+ if (!Number.isSafeInteger(keep)) {
2848
+ throw new CliError(`owenloop bundle gc: invalid --keep '${raw}' (expected a finite positive integer)`);
2849
+ }
2850
+ return keep;
2851
+ }
2852
+ function bundleGcPathOverride(args, key, environmentValue) {
2853
+ if (args.missingOptionValues.has(key)) {
2854
+ throw new CliError(`owenloop bundle gc: --${key} requires a non-empty path value`);
2855
+ }
2856
+ const optionValue = last(args, key);
2857
+ if (optionValue !== undefined) {
2858
+ if (optionValue.trim() === '') {
2859
+ throw new CliError(`owenloop bundle gc: --${key} requires a non-empty path value`);
2860
+ }
2861
+ return optionValue;
2862
+ }
2863
+ if (environmentValue !== undefined && environmentValue.trim() === '') {
2864
+ throw new CliError(`owenloop bundle gc: OWENLOOP_${key.toUpperCase()} must be a non-empty path`);
2865
+ }
2866
+ return environmentValue;
2867
+ }
2868
+ /** Collect exact CAS coordinates called by the currently executable non-CAS definitions. */
2869
+ function bundleGcExactCallsFromCurrentDefs(io, defsDir, defsOverride, verbose) {
2870
+ const defs = defsOverride === undefined
2871
+ ? loadDefsWithInstalled(io, defsDir, false, verbose).defs
2872
+ : (existsSync(defsDir) ? loadDefs(defsDir) : new Map());
2873
+ const exactCalls = new Set();
2874
+ for (const def of defs.values()) {
2875
+ // CAS definitions already root their own exact edges through bundleLock.
2876
+ // This scan supplies the missing roots for project, GitHub-add, and legacy
2877
+ // definitions whose snapshots intentionally carry no bundle provenance.
2878
+ if (def.bundleDigest !== undefined)
2879
+ continue;
2880
+ for (const step of def.steps) {
2881
+ if (step.calls === undefined || !step.calls.includes('@'))
2882
+ continue;
2883
+ try {
2884
+ parseWorkflowCoordinate(step.calls);
2885
+ }
2886
+ catch (error) {
2887
+ throw new CliError(`owenloop bundle gc: malformed exact calls target ${JSON.stringify(step.calls)} ` +
2888
+ `in workflow '${def.name}': ${error.message}`);
2889
+ }
2890
+ exactCalls.add(step.calls);
2891
+ }
2892
+ }
2893
+ return [...exactCalls].sort(compareStoreText);
2894
+ }
2895
+ /** Store-aware async branch of the otherwise filesystem-only bundle namespace. */
2896
+ async function dispatchBundleGc(io, args) {
2897
+ assertBundlePositionals(args, 2, 'owenloop bundle gc [--keep <n>] [--global] [--yes]');
2898
+ if (args.options.has('output')) {
2899
+ throw new CliError('owenloop bundle gc: --output is only valid for bundle pack');
2900
+ }
2901
+ const keep = bundleGcKeep(args);
2902
+ // Path selection determines both the destructive target and the snapshot pin
2903
+ // source. Validate every CLI/env override before deriving a root, probing a
2904
+ // DB, or acquiring a writer lock; parseArgs represents a missing value as the
2905
+ // literal string "true", which must never become a filesystem path here.
2906
+ const defsOverride = bundleGcPathOverride(args, 'defs', io.env.OWENLOOP_DEFS);
2907
+ const dbOverride = bundleGcPathOverride(args, 'db', io.env.OWENLOOP_DB);
2908
+ const globalFlag = flag(args, 'global');
2909
+ if (globalFlag && defsOverride !== undefined)
2910
+ throw new CliError(GLOBAL_DEFS_CONFLICT_MSG);
2911
+ const projectRoot = projectStoreRoot(defsOverride ?? join(io.cwd, 'workflows'));
2912
+ let globalRoot;
2913
+ if (globalFlag) {
2914
+ globalRoot = globalStoreRoot(workflowHome(io));
2915
+ }
2916
+ else {
2917
+ try {
2918
+ globalRoot = globalStoreRoot(workflowHome(io));
2919
+ }
2920
+ catch {
2921
+ // Match normal definition discovery: project-only operation remains
2922
+ // available when HOME is absent. No global install can derive a root
2923
+ // either, so model this as a single-root plan and avoid inventing a
2924
+ // coordination path inside the project store.
2925
+ globalRoot = projectRoot;
2926
+ }
2927
+ }
2928
+ const dbPath = dbOverride ?? join(io.cwd, '.owenloop', 'state.db');
2929
+ if (dbOverride === undefined) {
2930
+ const parent = dirname(dbPath);
2931
+ const parentState = lstatSync(parent, { throwIfNoEntry: false });
2932
+ if (parentState?.isSymbolicLink()) {
2933
+ throw new CliError(`refusing runtime database parent '${parent}': it is a symbolic link`);
2934
+ }
2935
+ if (parentState !== undefined && !parentState.isDirectory()) {
2936
+ throw new CliError(`refusing runtime database parent '${parent}': it is not a directory`);
2937
+ }
2938
+ dbPathRefusingSymlink(dbPath);
2939
+ }
2940
+ const readLedger = globalFlag
2941
+ ? undefined
2942
+ : () => {
2943
+ const lf = readLockfile(join(io.cwd, '.owenloop', 'installed.json'));
2944
+ return (source) => {
2945
+ const entry = lf.installed[source];
2946
+ return entry === undefined ? undefined : { sha: entry.sha, path: entry.path };
2947
+ };
2948
+ };
2949
+ const legacyRecovery = globalFlag
2950
+ ? undefined
2951
+ : {
2952
+ lockPath: join(io.cwd, '.owenloop', 'add.lock'),
2953
+ journalPath: join(io.cwd, '.owenloop', ADD_JOURNAL_FILENAME),
2954
+ lockfilePath: join(io.cwd, '.owenloop', 'installed.json'),
2955
+ readLedger: readLedger,
2956
+ };
2957
+ const legacyReadBarrier = globalFlag
2958
+ ? {
2959
+ lockPath: join(io.cwd, '.owenloop', 'add.lock'),
2960
+ journalPath: join(io.cwd, '.owenloop', ADD_JOURNAL_FILENAME),
2961
+ }
2962
+ : undefined;
2963
+ const result = await collectWorkflowStoreGarbage({
2964
+ projectRoot,
2965
+ globalRoot,
2966
+ level: globalFlag ? 'global' : 'project',
2967
+ keep,
2968
+ yes: flag(args, 'yes'),
2969
+ readSnapshotPins: () => readRuntimeSnapshotBundlePins(dbPath),
2970
+ readExactCalls: () => bundleGcExactCallsFromCurrentDefs(io, projectRoot, defsOverride, flag(args, 'verbose')),
2971
+ ...(readLedger === undefined ? {} : { readLedger }),
2972
+ ...(legacyRecovery === undefined ? {} : { legacyRecovery }),
2973
+ ...(legacyReadBarrier === undefined ? {} : { legacyReadBarrier }),
2974
+ ...(optionalWorkflowRecoveryMarkerDir(io) === undefined
2975
+ ? {}
2976
+ : { recoveryMarkerDir: optionalWorkflowRecoveryMarkerDir(io) }),
2977
+ });
2978
+ print(io, result);
2979
+ return 0;
2980
+ }
2704
2981
  /**
2705
2982
  * The `.wnlp` bundle route of `owenloop add` — the content-addressed store
2706
2983
  * counterpart of the GitHub route. `dispatchAdd` classifies the positional
@@ -2729,9 +3006,9 @@ async function dispatchAddBundle(io, args, source) {
2729
3006
  // A fresh bundle install also needs an external marker directory, so derive
2730
3007
  // that path from the same injected home and never from process state.
2731
3008
  const recoveryMarkerDir = workflowRecoveryMarkerDir(io);
2732
- const root = globalFlag
2733
- ? globalStoreRoot(workflowHome(io))
2734
- : projectStoreRoot(defsOverride ?? join(io.cwd, 'workflows'));
3009
+ const projectRoot = projectStoreRoot(defsOverride ?? join(io.cwd, 'workflows'));
3010
+ const globalRoot = globalStoreRoot(workflowHome(io));
3011
+ const root = globalFlag ? globalRoot : projectRoot;
2735
3012
  const statePaths = workflowStoreStatePaths(root);
2736
3013
  const lockPath = statePaths.lockPath;
2737
3014
  const journalPath = statePaths.journalPath;
@@ -2779,6 +3056,8 @@ async function dispatchAddBundle(io, args, source) {
2779
3056
  source: bundleSource,
2780
3057
  root,
2781
3058
  level: globalFlag ? 'global' : 'project',
3059
+ projectRoot,
3060
+ globalRoot,
2782
3061
  lockPath,
2783
3062
  journalPath,
2784
3063
  recoveryMarkerDir,
@@ -3013,7 +3292,7 @@ async function dispatchAdd(io, args) {
3013
3292
  mkdirRefusingSymlink(canonicalState.stateDir);
3014
3293
  guardStateFile(canonicalState.lockPath, 'canonical install lock');
3015
3294
  guardStateFile(canonicalState.journalPath, 'canonical crash-recovery journal');
3016
- const lockPaths = [...new Set([installLockPath, canonicalState.lockPath])].sort();
3295
+ const lockPaths = [...new Set([installLockPath, canonicalState.lockPath])].sort(compareStoreText);
3017
3296
  const locks = [];
3018
3297
  try {
3019
3298
  for (const path of lockPaths)
@@ -3029,13 +3308,10 @@ async function dispatchAdd(io, args) {
3029
3308
  // must NOT delete it (the error message tells the user to recover it).
3030
3309
  let preserveStagingRoot = false;
3031
3310
  try {
3032
- // Recover a crash-interrupted prior install FIRST — before the stale-staging
3033
- // clear, since the backups/parked dirs a rollback needs live UNDER the
3034
- // staging root, so clearing it first would destroy them. Any refusal (bad or
3035
- // mismatched or contradictory journal) must preserve the staging root and the
3036
- // journal as evidence: without this, the `finally` below would rmSync the
3037
- // staging root and take the backups a later recovery needs with it.
3311
+ // Recover crash-interrupted GC parking and installs FIRST — before the
3312
+ // stale-staging clear, since either can own evidence below that shared root.
3038
3313
  try {
3314
+ recoverInterruptedWorkflowStoreGc({ root: defsDir, stateDir: canonicalState.stateDir });
3039
3315
  recoverInterruptedInstall({
3040
3316
  defsDir,
3041
3317
  journalPath: canonicalState.journalPath,
@@ -3342,7 +3618,9 @@ async function dispatchAddRecover(io, args) {
3342
3618
  guardStateFile(canonicalState.lockPath, 'canonical install lock');
3343
3619
  guardStateFile(canonicalState.journalPath, 'canonical crash-recovery journal');
3344
3620
  }
3345
- const lockPaths = [...new Set([installLockPath, ...(canonicalStateExists ? [canonicalState.lockPath] : [])])].sort();
3621
+ const lockPaths = [
3622
+ ...new Set([installLockPath, ...(canonicalStateExists ? [canonicalState.lockPath] : [])]),
3623
+ ].sort(compareStoreText);
3346
3624
  const locks = [];
3347
3625
  try {
3348
3626
  for (const path of lockPaths)
@@ -3355,6 +3633,9 @@ async function dispatchAddRecover(io, args) {
3355
3633
  }
3356
3634
  let outcome = 'no-journal';
3357
3635
  try {
3636
+ if (canonicalStateExists) {
3637
+ recoverInterruptedWorkflowStoreGc({ root: defsDir, stateDir: canonicalState.stateDir });
3638
+ }
3358
3639
  const canonicalOutcome = recoverInterruptedInstall({
3359
3640
  defsDir,
3360
3641
  journalPath: canonicalState.journalPath,
@@ -3602,7 +3883,8 @@ async function authedPost(io, origin, slot, cred, path, body, persist = true) {
3602
3883
  /**
3603
3884
  * A 401 on an agent token is a hard "revoked/invalid" error; a 401 on any
3604
3885
  * other credential kind (after `authedGet`'s one refresh-and-retry) is a hard
3605
- * "credential rejected" error; any other non-2xx is a generic hub-rejected
3886
+ * "credential rejected" error; a 429 is a rate-limit error (including
3887
+ * `Retry-After` when present); any other non-2xx is a generic hub-rejected
3606
3888
  * error naming the status. Shared by `verifyCredential` and `dispatchPush`'s
3607
3889
  * server-list fetch so both surfaces the same wording for the same failure.
3608
3890
  */
@@ -3613,6 +3895,10 @@ function assertAuthOk(res, cred, origin) {
3613
3895
  }
3614
3896
  throw new CliError('credential rejected by the hub — run `owenloop login`');
3615
3897
  }
3898
+ if (res.status === 429) {
3899
+ const retryAfter = res.headers.get('retry-after');
3900
+ throw new CliError(`rate limited by the hub${retryAfter ? ` (retry after ${retryAfter})` : ''}`);
3901
+ }
3616
3902
  if (!res.ok) {
3617
3903
  throw new CliError(`hub ${origin} rejected the credential (HTTP ${res.status})`);
3618
3904
  }
@@ -4165,6 +4451,116 @@ function orderSelectedDefsByCalls(selected, currentPackage) {
4165
4451
  visit(def);
4166
4452
  return { ordered, dependencies };
4167
4453
  }
4454
+ /**
4455
+ * Publish an already-diffed, already-validated batch of defs — the shared
4456
+ * publish ladder behind BOTH `push` and `install`, so the two can never drift
4457
+ * apart in how they treat a 401, a 413, a 429, a `{ok:false}` 200, or a def
4458
+ * whose selected dependency failed.
4459
+ *
4460
+ * Behavior, unchanged from when this lived inline in `dispatchPush`:
4461
+ * - A def whose selected `calls:` dependency failed or was skipped is SKIPPED,
4462
+ * never published against a half-updated hub.
4463
+ * - A 401 refreshes an oauth credential once and retries once; a 401 that
4464
+ * survives that (or any 401 on an agent token) aborts the whole run by
4465
+ * re-throwing — already-published defs stand.
4466
+ * - A 429 halts the batch immediately (REL-10): this def is `failed`, the
4467
+ * not-yet-attempted remainder is `skipped`, and nothing else is sent.
4468
+ * - Any other per-def failure is recorded and the batch continues.
4469
+ *
4470
+ * `holder.cred` is read before every request and written back after a refresh,
4471
+ * so a mid-batch token rotation is not lost by the caller.
4472
+ */
4473
+ async function publishCandidates(io, origin, slot, holder, toPush, dependencies, bundleDigest) {
4474
+ const pushed = [];
4475
+ const noop = [];
4476
+ const failed = [];
4477
+ const skipped = [];
4478
+ const capabilities = {};
4479
+ const unsuccessful = new Set();
4480
+ for (let i = 0; i < toPush.length; i++) {
4481
+ const c = toPush[i];
4482
+ const label = c.status === 'new' ? '+' : '~';
4483
+ const blockedBy = [...(dependencies.get(c.name) ?? [])]
4484
+ .filter((dependency) => unsuccessful.has(dependency))
4485
+ .sort();
4486
+ if (blockedBy.length > 0) {
4487
+ skipped.push(c.name);
4488
+ unsuccessful.add(c.name);
4489
+ io.err(`- ${c.name} (skipped: selected dependency ${blockedBy.map((name) => `'${name}'`).join(', ')} failed or was skipped)`);
4490
+ continue;
4491
+ }
4492
+ try {
4493
+ let res = await createWorkflowRequest(io, origin, holder.cred, c.yaml, bundleDigest);
4494
+ if (res.status === 401 && holder.cred.kind === 'oauth') {
4495
+ holder.cred = await refreshOAuth(io, origin, slot, holder.cred);
4496
+ res = await createWorkflowRequest(io, origin, holder.cred, c.yaml, bundleDigest);
4497
+ }
4498
+ if (res.status === 401) {
4499
+ if (holder.cred.kind === 'agent') {
4500
+ throw new CliError('token revoked or invalid — re-mint it in the console or run `owenloop login`');
4501
+ }
4502
+ throw new CliError('credential rejected by the hub — run `owenloop login`');
4503
+ }
4504
+ if (res.status === 413)
4505
+ throw new CliError('workflow yaml exceeds the hub 32MB request cap');
4506
+ if (res.status === 429) {
4507
+ const retryAfter = res.headers.get('retry-after');
4508
+ throw new RateLimitError(`rate limited by the hub${retryAfter ? ` (retry after ${retryAfter})` : ''}`);
4509
+ }
4510
+ if (!res.ok)
4511
+ throw new CliError(`hub returned HTTP ${res.status}`);
4512
+ const bodyJson = await res.json();
4513
+ const errText = createWorkflowError(bodyJson);
4514
+ if (errText !== null)
4515
+ throw new CliError(`hub rejected the def: ${errText}`);
4516
+ const okBody = asCreateWorkflowOk(bodyJson, c.name);
4517
+ if (okBody.unchanged) {
4518
+ noop.push(c.name);
4519
+ io.err(`= ${c.name} (server: unchanged, v${okBody.version})`);
4520
+ }
4521
+ else {
4522
+ pushed.push(c.name);
4523
+ io.err(`${label} ${c.name} (→ v${okBody.version})`);
4524
+ }
4525
+ // The hub sends the report on BOTH branches, `unchanged:true` included, so
4526
+ // an idempotent re-push still tells the pusher what the org vocabulary is.
4527
+ if (okBody.capabilityReport !== undefined) {
4528
+ capabilities[c.name] = okBody.capabilityReport;
4529
+ printCapabilityReport(io, c.name, okBody.capabilityReport);
4530
+ }
4531
+ }
4532
+ catch (e) {
4533
+ // A 429 halts the whole batch immediately (REL-10): record this def as
4534
+ // failed, then stop — the not-yet-attempted remainder is reported as
4535
+ // `skipped`, not silently hammered against a rate-limited server.
4536
+ // Handled before the generic path because RateLimitError extends CliError.
4537
+ if (e instanceof RateLimitError) {
4538
+ const msg = e.message;
4539
+ failed.push({ name: c.name, error: msg });
4540
+ unsuccessful.add(c.name);
4541
+ io.err(`! ${c.name} (failed: ${msg})`);
4542
+ const remainder = toPush.slice(i + 1).map((r) => r.name);
4543
+ skipped.push(...remainder);
4544
+ for (const name of remainder)
4545
+ unsuccessful.add(name);
4546
+ if (remainder.length > 0) {
4547
+ io.err(`stopping — rate limited by the hub; ${remainder.length} def(s) not attempted`);
4548
+ }
4549
+ break;
4550
+ }
4551
+ // A hard auth error aborts the whole run (re-throw); a per-def server
4552
+ // failure is recorded and the batch continues (already-pushed defs stand).
4553
+ if (e instanceof CliError && /run `owenloop login`|re-mint it/.test(e.message)) {
4554
+ throw e;
4555
+ }
4556
+ const msg = e.message;
4557
+ failed.push({ name: c.name, error: msg });
4558
+ unsuccessful.add(c.name);
4559
+ io.err(`! ${c.name} (failed: ${msg})`);
4560
+ }
4561
+ }
4562
+ return { pushed, noop, skipped, failed, capabilities };
4563
+ }
4168
4564
  /**
4169
4565
  * `owenloop push [<defName>...] [--bundle <bundle.wnlp>] [--force]
4170
4566
  * [--dry-run] [--hub <origin>]` — publish local workflow defs, or exact
@@ -4185,6 +4581,11 @@ async function dispatchPush(io, args) {
4185
4581
  }
4186
4582
  const dryRun = flag(args, 'dry-run');
4187
4583
  const force = flag(args, 'force');
4584
+ // `push` publishes defs the ORG authored, so their capabilities join the org's
4585
+ // SHARED vocabulary by default and NOTHING is recorded. `--map` is the only
4586
+ // way `push` writes a mapping at all — the deliberate asymmetry with
4587
+ // `install`, which scopes by default. See `dispatchInstall`.
4588
+ const requestedMap = parseCapabilityMapFlag(args);
4188
4589
  const slot = resolveSlot(args);
4189
4590
  const resolved = resolvePublishingHub(io, args, slot);
4190
4591
  const { origin } = resolved;
@@ -4244,6 +4645,18 @@ async function dispatchPush(io, args) {
4244
4645
  const selectedOrder = orderSelectedDefsByCalls(selected, bundle?.manifest.package.name);
4245
4646
  selected = selectedOrder.ordered;
4246
4647
  const selectedDependencies = selectedOrder.dependencies;
4648
+ assertMapCoversSelection(requestedMap, selected);
4649
+ // Per def, only the entries that def actually authors, and only the
4650
+ // non-identity ones — the hub's resolver drops an identity row anyway, so
4651
+ // posting one would be a write that changes nothing.
4652
+ const mappingWrites = selected
4653
+ .map((def) => ({
4654
+ name: def.name,
4655
+ entries: Object.fromEntries(authoredCapabilitiesOf(def)
4656
+ .filter((cap) => requestedMap[cap] !== undefined && requestedMap[cap] !== cap)
4657
+ .map((cap) => [cap, requestedMap[cap]])),
4658
+ }))
4659
+ .filter((w) => Object.keys(w.entries).length > 0);
4247
4660
  // Client-side validation gate — all-or-nothing, mirroring dispatchAdd exactly.
4248
4661
  // Any failure aborts the entire push; nothing is sent.
4249
4662
  const reasons = failures.map((f) => `${f.file}: ${f.error}`);
@@ -4337,110 +4750,600 @@ async function dispatchPush(io, args) {
4337
4750
  changed: toPush.filter((c) => c.status === 'changed').map((c) => c.name),
4338
4751
  unchanged: unchanged.map((c) => c.name),
4339
4752
  wouldPush: toPush.map((c) => c.name),
4753
+ wouldRecord: Object.fromEntries(mappingWrites.map((w) => [w.name, w.entries])),
4340
4754
  });
4341
4755
  return 0;
4342
4756
  }
4757
+ // `--map` records BEFORE anything is published, the same ordering `install`
4758
+ // uses and for the same reason: a hub that cannot record the mapping must
4759
+ // fail the command with nothing published, never leave the two halves apart.
4760
+ if (mappingWrites.length > 0) {
4761
+ const holder = { cred };
4762
+ const transport = capabilityMappingTransport(io, origin, slot, holder);
4763
+ for (const write of mappingWrites) {
4764
+ await recordCapabilityMappings(transport, write.name, write.entries, origin);
4765
+ for (const [authored, org] of Object.entries(write.entries)) {
4766
+ io.err(` recorded ${write.name}: ${authored} → ${org}`);
4767
+ }
4768
+ }
4769
+ cred = holder.cred;
4770
+ }
4343
4771
  // Refresh an expiring oauth token once up front (per-request 401 refresh below covers mid-batch expiry).
4344
4772
  cred = await ensureFreshOAuth(io, origin, slot, cred);
4345
4773
  if (bundle !== undefined) {
4346
4774
  cred = await uploadPushBundle(io, origin, slot, cred, bundle);
4347
4775
  }
4348
- const pushedNames = [];
4349
- const noopNames = [];
4350
- const failed = [];
4351
- const skipped = [];
4352
- const unsuccessful = new Set();
4353
- for (let i = 0; i < toPush.length; i++) {
4354
- const c = toPush[i];
4355
- const label = c.status === 'new' ? '+' : '~';
4356
- const blockedBy = [...(selectedDependencies.get(c.name) ?? [])]
4357
- .filter((dependency) => unsuccessful.has(dependency))
4358
- .sort();
4359
- if (blockedBy.length > 0) {
4360
- skipped.push(c.name);
4361
- unsuccessful.add(c.name);
4362
- io.err(`- ${c.name} (skipped: selected dependency ${blockedBy.map((name) => `'${name}'`).join(', ')} failed or was skipped)`);
4776
+ const holder = { cred };
4777
+ const published = await publishCandidates(io, origin, slot, holder, toPush, selectedDependencies, bundle?.digest);
4778
+ print(io, {
4779
+ ok: published.failed.length === 0,
4780
+ hub: origin,
4781
+ ...(bundle === undefined ? {} : { bundleDigest: bundle.digest, publication: bundle.publicationState }),
4782
+ pushed: published.pushed,
4783
+ noop: published.noop,
4784
+ unchanged: unchanged.map((c) => c.name),
4785
+ skipped: published.skipped,
4786
+ failed: published.failed,
4787
+ capabilities: published.capabilities,
4788
+ });
4789
+ return published.failed.length === 0 ? 0 : 1;
4790
+ }
4791
+ finally {
4792
+ if (bundle !== undefined)
4793
+ rmSync(bundle.cleanupRoot, { recursive: true, force: true });
4794
+ }
4795
+ }
4796
+ // ---- capability mapping (shared by `push --map` and `install`) ---------------
4797
+ /**
4798
+ * Every authored capability one def declares, deduped, in first-authored order.
4799
+ *
4800
+ * Judge steps are synthesized into `def.steps` by the def parser, so iterating
4801
+ * `steps` covers them — there is no second place capabilities can be written.
4802
+ * Order is the order an operator reads the YAML top-down, which is the order
4803
+ * the install prompt asks in.
4804
+ */
4805
+ function authoredCapabilitiesOf(def) {
4806
+ const names = [];
4807
+ for (const step of def.steps) {
4808
+ for (const cap of step.capabilities ?? []) {
4809
+ if (!names.includes(cap))
4810
+ names.push(cap);
4811
+ }
4812
+ }
4813
+ return names;
4814
+ }
4815
+ /**
4816
+ * The org capability name an OUTSIDE def's capability takes by default:
4817
+ * `<defName>.<authored>`.
4818
+ *
4819
+ * This needs no new separator and invents no escaping. A def name matches
4820
+ * `/^[a-z0-9][a-z0-9_-]*$/i`, so it can never contain a dot, while the def
4821
+ * parser's capability rule reserves only `:` — dots are already legal inside a
4822
+ * capability. So the dot splits the two halves unambiguously in one direction
4823
+ * (the first dot ends the def name) and collides with nothing.
4824
+ */
4825
+ function scopedCapabilityName(defName, authored) {
4826
+ return `${defName}.${authored}`;
4827
+ }
4828
+ /**
4829
+ * The same rule the def parser's `assertAuthoredCapability` applies, restated
4830
+ * for an ORG-side name supplied on the command line or at the prompt:
4831
+ * non-empty, not whitespace, and no `MODIFIER_SEPARATOR`.
4832
+ *
4833
+ * The separator ban is the load-bearing half. `:` is the suffix position the
4834
+ * engine composes the run modifier into at offer time (`wise` + `deep` →
4835
+ * `wise:deep`), so an authored-side value carrying one would be a capability
4836
+ * that can never be composed. The def parser refuses it in YAML; this refuses
4837
+ * it on the mapping's target, which reaches exactly the same position.
4838
+ */
4839
+ function assertMappingTarget(target, where) {
4840
+ if (target.trim().length === 0) {
4841
+ throw new CliError(`${where}: an org capability name must not be empty or whitespace`);
4842
+ }
4843
+ if (target.includes(MODIFIER_SEPARATOR)) {
4844
+ throw new CliError(`${where}: capability '${target}' must not contain '${MODIFIER_SEPARATOR}' — ` +
4845
+ 'the suffix position is reserved for the modifier the engine composes at offer time ' +
4846
+ "(a run carrying 'deep' turns the authored capability 'wise' into 'wise:deep')");
4847
+ }
4848
+ }
4849
+ /**
4850
+ * Parse the repeatable `--map <authored>=<org>` flag shared by `push` and
4851
+ * `install`. `parsePairs` supplies the `expected name=value, got: …` refusal;
4852
+ * every target is then validated by `assertMappingTarget`.
4853
+ */
4854
+ function parseCapabilityMapFlag(args) {
4855
+ const out = {};
4856
+ for (const [authored, target] of Object.entries(parsePairs(all(args, 'map'), false))) {
4857
+ if (authored.trim().length === 0) {
4858
+ throw new CliError('--map: the authored capability name must not be empty or whitespace');
4859
+ }
4860
+ assertMappingTarget(target, `--map ${authored}`);
4861
+ out[authored] = target;
4862
+ }
4863
+ return out;
4864
+ }
4865
+ /**
4866
+ * Refuse a `--map` naming a capability none of the selected defs authors — it
4867
+ * would otherwise be a silent no-op, and a typo in an authored name is exactly
4868
+ * the case where silence is worst (the operator believes a link was made).
4869
+ */
4870
+ function assertMapCoversSelection(map, selected) {
4871
+ const authored = new Set(selected.flatMap((def) => authoredCapabilitiesOf(def)));
4872
+ const unknown = Object.keys(map)
4873
+ .filter((name) => !authored.has(name))
4874
+ .sort();
4875
+ if (unknown.length === 0)
4876
+ return;
4877
+ const known = [...authored].sort();
4878
+ throw new CliError(`--map names ${unknown.length} capability(ies) no selected def authors: ${unknown.join(', ')} — ` +
4879
+ (known.length === 0 ? 'the selected defs author no capabilities' : `authored: ${known.join(', ')}`));
4880
+ }
4881
+ /**
4882
+ * Adapt `authedGet`/`authedPost` into the transport
4883
+ * `src/capability-mapping-client.ts` takes, threading the possibly-refreshed
4884
+ * credential back into `holder` so a mid-command oauth refresh is not lost.
4885
+ *
4886
+ * The client module cannot import these helpers directly — they are private to
4887
+ * `cli.ts`, and `cli.ts` imports the client, so a direct import would be a
4888
+ * cycle. Injecting the transport keeps the 30s deadline, the bounded body,
4889
+ * `redirect: 'error'` and the single 401-refresh-and-retry on the mapping calls
4890
+ * without one.
4891
+ */
4892
+ function capabilityMappingTransport(io, origin, slot, holder) {
4893
+ return {
4894
+ async get(path) {
4895
+ const { res, cred } = await authedGet(io, origin, slot, holder.cred, path);
4896
+ holder.cred = cred;
4897
+ return res;
4898
+ },
4899
+ async post(path, body) {
4900
+ const { res, cred } = await authedPost(io, origin, slot, holder.cred, path, body);
4901
+ holder.cred = cred;
4902
+ return res;
4903
+ },
4904
+ };
4905
+ }
4906
+ /**
4907
+ * The hub's capability publish report for one def, on STDERR — stdout stays
4908
+ * machine JSON. Silent for a hub that sent no report (older than the report) and
4909
+ * for a def that authors no capabilities, so neither case prints a dangling
4910
+ * header.
4911
+ */
4912
+ function printCapabilityReport(io, defName, report) {
4913
+ if (report === undefined)
4914
+ return;
4915
+ const text = capabilityPublishReportText(report);
4916
+ if (text !== '')
4917
+ io.err(`${defName}: ${text}`);
4918
+ }
4919
+ /**
4920
+ * Render the org's live capability vocabulary from `GET /api/capability_routes`
4921
+ * as one line — `review (reviewers), builder (builders), triage (unbound)`.
4922
+ *
4923
+ * The endpoint returns ONE ROW PER `(capability, crew)` pair, so rows are
4924
+ * grouped by capability here. A row whose `crewName` is `null` is a DANGLING
4925
+ * route (the crew is gone) and shows as `unbound`, because that is what it means
4926
+ * for routing: the capability exists in the vocabulary but nothing serves it.
4927
+ */
4928
+ function formatOrgVocabulary(routes) {
4929
+ const crewsByCapability = new Map();
4930
+ for (const route of routes) {
4931
+ const crews = crewsByCapability.get(route.capability);
4932
+ const name = route.crewName;
4933
+ if (crews === undefined)
4934
+ crewsByCapability.set(route.capability, new Set(name === null ? [] : [name]));
4935
+ else if (name !== null)
4936
+ crews.add(name);
4937
+ }
4938
+ return [...crewsByCapability.entries()]
4939
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
4940
+ .map(([capability, crews]) => `${capability} (${crews.size === 0 ? 'unbound' : [...crews].sort().join(', ')})`)
4941
+ .join(', ');
4942
+ }
4943
+ /**
4944
+ * Fetch a public GitHub repo's `workflows/**` at a pinned commit sha, into an
4945
+ * in-memory file map.
4946
+ *
4947
+ * Deliberately its own sequence rather than a refactor of `dispatchAdd`'s: `add`
4948
+ * interleaves this with a project install lock, a crash journal and an atomic
4949
+ * swap that `install` has no business acquiring, and its refusal wording names
4950
+ * `add`'s local install. Only the PRIMITIVES are shared (`parseRepoSpec`,
4951
+ * `githubShaUrl`, `githubTarballUrl`, `readBodyBounded`, `extractTarGz`,
4952
+ * `archivePathViolation`), which is where the security-relevant behavior lives:
4953
+ * the ref is pinned to a 40-char sha before the tarball is fetched, the body is
4954
+ * capped DURING the stream, and every archive path is checked for escape before
4955
+ * it is ever joined (SEC-1).
4956
+ */
4957
+ async function fetchGithubWorkflowFiles(io, spec) {
4958
+ const { owner, repo, ref } = parseRepoSpec(spec);
4959
+ const source = `${owner}/${repo}`;
4960
+ const fetchFn = io.fetch ?? globalThis.fetch;
4961
+ let shaRes;
4962
+ try {
4963
+ shaRes = await fetchFn(githubShaUrl(owner, repo, ref), {
4964
+ headers: { Accept: 'application/vnd.github.sha', 'User-Agent': 'owenloop' },
4965
+ signal: AbortSignal.timeout(ADD_SHA_TIMEOUT_MS),
4966
+ });
4967
+ }
4968
+ catch (e) {
4969
+ const err = e;
4970
+ if (err.name === 'TimeoutError' || err.name === 'AbortError') {
4971
+ throw new CliError(`timed out after ${ADD_SHA_TIMEOUT_MS / 1000}s resolving ${source}@${ref}`);
4972
+ }
4973
+ throw e;
4974
+ }
4975
+ if (!shaRes.ok) {
4976
+ const notFoundNote = shaRes.status === 404 ? ' (repo or ref not found)' : '';
4977
+ throw new CliError(`could not resolve ${source}@${ref}: GitHub returned ${shaRes.status}${notFoundNote}`);
4978
+ }
4979
+ const shaBytes = await readBodyBounded(shaRes, hubMaxResponseBytes(io), `sha resolution for ${source}@${ref}`);
4980
+ const sha = new TextDecoder().decode(shaBytes).trim();
4981
+ if (!/^[0-9a-f]{40}$/i.test(sha)) {
4982
+ throw new CliError(`unexpected response resolving ${source}@${ref}: expected a 40-char commit sha, got "${sha}"`);
4983
+ }
4984
+ let bytes;
4985
+ try {
4986
+ const tarRes = await fetchFn(githubTarballUrl(owner, repo, sha), {
4987
+ headers: { 'User-Agent': 'owenloop' },
4988
+ signal: AbortSignal.timeout(ADD_TARBALL_TIMEOUT_MS),
4989
+ });
4990
+ if (!tarRes.ok) {
4991
+ throw new CliError(`could not fetch tarball for ${source}@${sha}: GitHub returned ${tarRes.status}`);
4992
+ }
4993
+ bytes = await readBodyBounded(tarRes, tarballMaxBytes(io), `tarball for ${source}@${sha}`);
4994
+ }
4995
+ catch (e) {
4996
+ const err = e;
4997
+ if (err.name === 'TimeoutError' || err.name === 'AbortError') {
4998
+ throw new CliError(`timed out after ${ADD_TARBALL_TIMEOUT_MS / 1000}s downloading tarball for ${source}@${sha}`);
4999
+ }
5000
+ throw e;
5001
+ }
5002
+ let rawFiles;
5003
+ try {
5004
+ rawFiles = extractTarGz(bytes);
5005
+ }
5006
+ catch (e) {
5007
+ throw new CliError(`could not extract tarball for ${source}@${sha}: ${e.message}`);
5008
+ }
5009
+ const files = new Map();
5010
+ const pathViolations = [];
5011
+ for (const [rawPath, data] of rawFiles) {
5012
+ const firstSlash = rawPath.indexOf('/');
5013
+ const rest = firstSlash >= 0 ? rawPath.slice(firstSlash + 1) : '';
5014
+ if (!rest.startsWith('workflows/'))
5015
+ continue;
5016
+ const relPath = rest.slice('workflows/'.length);
5017
+ if (!relPath)
5018
+ continue;
5019
+ const violation = archivePathViolation(relPath);
5020
+ if (violation) {
5021
+ pathViolations.push(`${rawPath}: ${violation}`);
5022
+ continue;
5023
+ }
5024
+ files.set(relPath, data);
5025
+ }
5026
+ if (pathViolations.length > 0) {
5027
+ throw new CliError(`refusing to install ${source}@${sha} — ${pathViolations.length} unsafe archive path(s) found; nothing published:\n - ${pathViolations.join('\n - ')}`);
5028
+ }
5029
+ if (files.size === 0) {
5030
+ throw new CliError(`no workflows/ directory found in ${source}@${ref}`);
5031
+ }
5032
+ return { source, ref, sha, files };
5033
+ }
5034
+ /**
5035
+ * Ask the operator, one authored capability at a time, what the org should call
5036
+ * it. Enter accepts the prefilled SCOPED default; typing a name links the
5037
+ * capability into the org's existing vocabulary instead.
5038
+ *
5039
+ * Prompt style matches `promptAgentName` / `promptSuccession`: prefilled
5040
+ * default, empty answer accepts it, one re-prompt on an invalid answer, then a
5041
+ * `CliError`. All prompt I/O is stderr, so `| jq` on stdout is unaffected.
5042
+ *
5043
+ * `prompt` is passed in ALREADY RESOLVED by `requirePrompt`, which the caller
5044
+ * ran before any hub I/O — a piped run must fail with the flag names, never
5045
+ * block here after half the work is done.
5046
+ */
5047
+ async function promptCapabilityMapping(io, prompt, defName, authored) {
5048
+ const fallback = scopedCapabilityName(defName, authored);
5049
+ const question = ` ${authored} [${fallback}]: `;
5050
+ for (let attempt = 0; attempt < 2; attempt++) {
5051
+ const raw = (await prompt(question)).trim();
5052
+ if (raw === '')
5053
+ return fallback;
5054
+ try {
5055
+ assertMappingTarget(raw, `capability '${authored}'`);
5056
+ return raw;
5057
+ }
5058
+ catch (e) {
5059
+ io.err(e.message);
5060
+ }
5061
+ }
5062
+ throw new CliError(`no valid org capability name provided for '${authored}'`);
5063
+ }
5064
+ /**
5065
+ * `owenloop install <owner>/<repo>[@ref] [<defName>...] [--map <authored>=<org>]
5066
+ * [--accept-defaults] [--dry-run] [--hub <origin>] [--as <slot>]` — publish defs
5067
+ * authored OUTSIDE your org to your hub, under capability names your org
5068
+ * chooses.
5069
+ *
5070
+ * **This is a PUBLISH verb, a sibling of `push` — not of `add`.** It never
5071
+ * writes into the local `workflows/` directory: `add` already owns local
5072
+ * installation, with its install lock, crash journal and atomic swap, and
5073
+ * duplicating that here would be a second implementation of the same
5074
+ * transaction. `install` fetches the outside def, decides the org-side
5075
+ * capability vocabulary for it, records that mapping, and publishes.
5076
+ *
5077
+ * **Why the mapping is scoped by default.** `push` publishes defs YOU authored,
5078
+ * so their capabilities join the org's SHARED vocabulary — two of your own defs
5079
+ * both authoring `review` deliberately mean the same `review`, served by the
5080
+ * same crews. A def from an unrelated author making the same claim is not the
5081
+ * same claim. So every capability an installed def authors becomes
5082
+ * `<defName>.<capability>` unless the installer says otherwise, once, at install
5083
+ * time. The def content itself is never edited: the mapping is org-side data.
5084
+ *
5085
+ * **Order of operations, and it is the point: record, THEN publish.** Publishing
5086
+ * first would put an unscoped third-party def into the org's vocabulary for the
5087
+ * window between the two calls — exactly the trust-boundary breach this verb
5088
+ * exists to prevent. So a hub that cannot record the mapping fails the command
5089
+ * BEFORE anything is published, and nothing is left half-applied.
5090
+ *
5091
+ * **A hub that cannot record mappings.** The hub's mapping READ is live, but no
5092
+ * shipped `owenloop-service` build has the BATCH write this command needs — it
5093
+ * ships a singular one-row-per-call verb instead, which cannot give the
5094
+ * record-then-publish order its all-or-nothing guarantee (see
5095
+ * `src/capability-mapping-client.ts` for why the plural is not sugar over N
5096
+ * singular calls). Until the batch verb ships, only the IDENTITY case completes
5097
+ * end to end: when every capability keeps its authored name there is nothing to
5098
+ * record — the hub's resolver drops identity rows anyway — so the write is
5099
+ * skipped and the publish proceeds. Every other case stops at the missing verb
5100
+ * with exit 2.
5101
+ *
5102
+ * Exit codes: 0 ok; 1 runtime/hub error (a validation-gate refusal, a per-def
5103
+ * hub rejection, a refused source kind, an invalid `--map`); 2 the hub is
5104
+ * unresolvable, or it does not implement the mapping write; 3 the credential for
5105
+ * the slot is absent or irrecoverable.
5106
+ */
5107
+ async function dispatchInstall(io, args) {
5108
+ // 0. Argument-only work, before anything is fetched or resolved.
5109
+ const spec = need(args, 1, '<source>');
5110
+ const classified = classifyAddSource(spec);
5111
+ if (classified.kind !== 'github') {
5112
+ const what = classified.kind === 'file' ? 'a local .wnlp bundle' : 'an http(s) URL';
5113
+ throw new CliError(`owenloop install: ${what} is not an install source yet — only owner/repo[@ref] (GitHub) is. ` +
5114
+ `Run \`owenloop add ${spec}\` to install it into the local store, then ` +
5115
+ '`owenloop push --bundle <bundle.wnlp>` to publish it.');
5116
+ }
5117
+ const dryRun = flag(args, 'dry-run');
5118
+ const acceptDefaults = flag(args, 'accept-defaults');
5119
+ const requestedMap = parseCapabilityMapFlag(args);
5120
+ const slot = resolveSlot(args);
5121
+ const resolvedHub = resolvePublishingHub(io, args, slot);
5122
+ const { origin } = resolvedHub;
5123
+ const startingCredential = resolvedHub.credential ?? readCredential(io, origin, slot);
5124
+ if (!startingCredential) {
5125
+ throw new CliError(`${emptySlotMessage(origin, slot)} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
5126
+ }
5127
+ // Threaded through every hub call so a mid-command oauth refresh is not lost.
5128
+ const holder = { cred: startingCredential };
5129
+ // 1. Fetch the outside repo and materialize its workflows/ into a temp dir.
5130
+ // Nothing under the user's cwd is touched, at any point.
5131
+ const fetched = await fetchGithubWorkflowFiles(io, spec);
5132
+ const sourceRef = `${fetched.source}@${fetched.sha}`;
5133
+ const workRoot = mkdtempSync(join(tmpdir(), 'owenloop-install-'));
5134
+ try {
5135
+ for (const [relPath, data] of fetched.files) {
5136
+ const dest = join(workRoot, relPath);
5137
+ mkdirSync(dirname(dest), { recursive: true });
5138
+ writeFileSync(dest, data);
5139
+ }
5140
+ // 2. Load, narrow to positionals, and order by `calls:` — same machinery push uses.
5141
+ const failures = [];
5142
+ const allDefs = loadDefsRaw(workRoot, failures);
5143
+ const requested = args.positionals.slice(2);
5144
+ let selected;
5145
+ if (requested.length > 0) {
5146
+ selected = [];
5147
+ for (const name of requested) {
5148
+ const def = allDefs.get(name);
5149
+ if (!def) {
5150
+ throw new CliError(`unknown workflow definition '${name}' in ${sourceRef} (found: ${[...allDefs.keys()].sort().join(', ') || 'none'})${failureNote(failures)}`);
5151
+ }
5152
+ selected.push(def);
5153
+ }
5154
+ }
5155
+ else {
5156
+ selected = [...allDefs.values()];
5157
+ }
5158
+ if (selected.length === 0) {
5159
+ throw new CliError(`nothing to install — no workflow definitions found in ${sourceRef}${failureNote(failures)}`);
5160
+ }
5161
+ const selectedOrder = orderSelectedDefsByCalls(selected);
5162
+ selected = selectedOrder.ordered;
5163
+ const selectedDependencies = selectedOrder.dependencies;
5164
+ assertMapCoversSelection(requestedMap, selected);
5165
+ // 3. Client-side validation gate — all-or-nothing, byte-for-byte push's.
5166
+ // Any failure aborts everything: nothing is mapped and nothing is sent.
5167
+ const reasons = failures.map((f) => `${f.file}: ${f.error}`);
5168
+ for (const def of selected) {
5169
+ reasons.push(...lintDef(def).errors.map((e) => `${def.name}: ${e}`));
5170
+ reasons.push(...validateDef(def).map((e) => `${def.name}: ${e}`));
5171
+ const report = modelCheck(def, { assumeProvided: true });
5172
+ if (hasDefiniteCheckDefect(report)) {
5173
+ reasons.push(`${def.name}: definite defects found (${report.invariantViolations.length} invariant violation(s), ` +
5174
+ `${report.structurallyDeadSteps.length} structurally dead step(s), ` +
5175
+ `${report.deadlocks.length} true deadlock(s))`);
5176
+ }
5177
+ }
5178
+ // 4. Push candidates: verbatim source yaml + the server-canonical hash.
5179
+ // include:/bodyFile: defs are not hub-pushable, exactly as in `push`.
5180
+ const candidates = [];
5181
+ for (const def of selected) {
5182
+ if (!def.dir) {
5183
+ reasons.push(`${def.name}: has no source file on disk to push`);
4363
5184
  continue;
4364
5185
  }
5186
+ const yaml = readFileSync(def.dir, 'utf8');
5187
+ let usesInclude = false;
4365
5188
  try {
4366
- let res = await createWorkflowRequest(io, origin, cred, c.yaml, bundle?.digest);
4367
- if (res.status === 401 && cred.kind === 'oauth') {
4368
- cred = await refreshOAuth(io, origin, slot, cred);
4369
- res = await createWorkflowRequest(io, origin, cred, c.yaml, bundle?.digest);
4370
- }
4371
- if (res.status === 401) {
4372
- if (cred.kind === 'agent') {
4373
- throw new CliError('token revoked or invalid — re-mint it in the console or run `owenloop login`');
4374
- }
4375
- throw new CliError('credential rejected by the hub — run `owenloop login`');
4376
- }
4377
- if (res.status === 413)
4378
- throw new CliError('workflow yaml exceeds the hub 32MB request cap');
4379
- if (res.status === 429) {
4380
- const retryAfter = res.headers.get('retry-after');
4381
- throw new RateLimitError(`rate limited by the hub${retryAfter ? ` (retry after ${retryAfter})` : ''}`);
4382
- }
4383
- if (!res.ok)
4384
- throw new CliError(`hub returned HTTP ${res.status}`);
4385
- const bodyJson = await res.json();
4386
- const errText = createWorkflowError(bodyJson);
4387
- if (errText !== null)
4388
- throw new CliError(`hub rejected the def: ${errText}`);
4389
- const okBody = asCreateWorkflowOk(bodyJson, c.name);
4390
- if (okBody.unchanged) {
4391
- noopNames.push(c.name);
4392
- io.err(`= ${c.name} (server: unchanged, v${okBody.version})`);
4393
- }
4394
- else {
4395
- pushedNames.push(c.name);
4396
- io.err(`${label} ${c.name} (→ v${okBody.version})`);
4397
- }
5189
+ usesInclude = (buildDef(parseYaml(yaml), basename(def.dir), dirname(def.dir))._includes?.length ?? 0) > 0;
5190
+ }
5191
+ catch {
5192
+ // A shape error would already have surfaced via the gate above.
5193
+ }
5194
+ if (usesInclude) {
5195
+ reasons.push(`${def.name}: uses include:, not hub-pushable yet`);
5196
+ continue;
5197
+ }
5198
+ try {
5199
+ candidates.push({ name: def.name, hash: hashDefForHub(yaml), yaml });
4398
5200
  }
4399
5201
  catch (e) {
4400
- // A 429 halts the whole batch immediately (REL-10): record this def as
4401
- // failed, then stop — the not-yet-attempted remainder is reported as
4402
- // `skipped`, not silently hammered against a rate-limited server.
4403
- // Handled before the generic path because RateLimitError extends CliError.
4404
- if (e instanceof RateLimitError) {
4405
- const msg = e.message;
4406
- failed.push({ name: c.name, error: msg });
4407
- unsuccessful.add(c.name);
4408
- io.err(`! ${c.name} (failed: ${msg})`);
4409
- const remainder = toPush.slice(i + 1).map((r) => r.name);
4410
- skipped.push(...remainder);
4411
- for (const name of remainder)
4412
- unsuccessful.add(name);
4413
- if (remainder.length > 0) {
4414
- io.err(`stopping — rate limited by the hub; ${remainder.length} def(s) not attempted`);
4415
- }
4416
- break;
5202
+ if (e instanceof DefError && /bodyFile/.test(e.message)) {
5203
+ reasons.push(`${def.name}: uses bodyFile:, not hub-pushable`);
5204
+ continue;
4417
5205
  }
4418
- // A hard auth error aborts the whole run (re-throw); a per-def server
4419
- // failure is recorded and the batch continues (already-pushed defs stand).
4420
- if (e instanceof CliError && /run `owenloop login`|re-mint it/.test(e.message)) {
4421
- throw e;
5206
+ throw e;
5207
+ }
5208
+ }
5209
+ if (reasons.length > 0) {
5210
+ throw new CliError(`refusing to install ${sourceRef} — ${reasons.length} problem(s) found; nothing mapped, nothing published:\n - ${reasons.join('\n - ')}`);
5211
+ }
5212
+ // 5. THE NON-INTERACTIVE GUARD, before a single hub request.
5213
+ // Resolved here rather than at the first question so a piped run fails
5214
+ // with the flag names while the request log is still empty — never after
5215
+ // a mapping read has already happened. If carry-forward later covers
5216
+ // every capability, this prompt is simply never called.
5217
+ const uncovered = selected.some((def) => authoredCapabilitiesOf(def).some((cap) => requestedMap[cap] === undefined));
5218
+ const prompt = !uncovered || acceptDefaults
5219
+ ? undefined
5220
+ : requirePrompt(io, 'owenloop install needs to ask what your org should call each capability this def authors, ' +
5221
+ 'but stdin is not interactive — pass --map <authored>=<org> for each one, ' +
5222
+ 'or --accept-defaults to take the scoped <defName>.<capability> name for all of them');
5223
+ // 6. The org's existing vocabulary, so an operator choosing to LINK is
5224
+ // choosing informed. Read-only; publishes nothing.
5225
+ const { res: routesRes, cred: routesCred } = await authedGet(io, origin, slot, holder.cred, '/api/capability_routes');
5226
+ assertAuthOk(routesRes, routesCred, origin);
5227
+ holder.cred = routesCred;
5228
+ let vocabulary;
5229
+ try {
5230
+ vocabulary = asCapabilityRoutes(await routesRes.json());
5231
+ }
5232
+ catch (e) {
5233
+ throw new CliError(e.message);
5234
+ }
5235
+ // 7. Decide the vocabulary for each def: --map wins, then carry-forward,
5236
+ // then --accept-defaults, then the prompt.
5237
+ const transport = capabilityMappingTransport(io, origin, slot, holder);
5238
+ const plans = [];
5239
+ for (const def of selected) {
5240
+ const authored = authoredCapabilitiesOf(def);
5241
+ const resolved = {};
5242
+ const toRecord = {};
5243
+ if (authored.length === 0) {
5244
+ plans.push({ def, resolved, toRecord });
5245
+ continue;
5246
+ }
5247
+ const existingOrUnsupported = await fetchCapabilityMappings(transport, def.name, origin);
5248
+ const existing = existingOrUnsupported === 'unsupported' ? {} : existingOrUnsupported;
5249
+ const unsupported = existingOrUnsupported === 'unsupported';
5250
+ const needsAsking = authored.filter((cap) => requestedMap[cap] === undefined && (unsupported || existing[cap] === undefined));
5251
+ if (needsAsking.length > 0 && !acceptDefaults) {
5252
+ if (unsupported) {
5253
+ // The risk the operator must see BEFORE the first question: pressing
5254
+ // Enter through the prompts overwrites a deliberate link this hub
5255
+ // cannot report.
5256
+ io.err(`${origin} cannot report capability mappings already recorded for ${def.name} — ` +
5257
+ 'every capability will be asked about again, and the answers overwrite whatever is recorded.');
4422
5258
  }
4423
- const msg = e.message;
4424
- failed.push({ name: c.name, error: msg });
4425
- unsuccessful.add(c.name);
4426
- io.err(`! ${c.name} (failed: ${msg})`);
5259
+ io.err(`\n${def.name} authors ${authored.length} capability(ies). Enter = keep the scoped name; ` +
5260
+ 'type an org capability to link it into your existing vocabulary.');
5261
+ const vocab = formatOrgVocabulary(vocabulary);
5262
+ io.err(vocab === '' ? 'Your org routes no capabilities yet.' : `Your org already routes: ${vocab}`);
5263
+ io.err('');
5264
+ }
5265
+ for (const cap of authored) {
5266
+ const chosen = requestedMap[cap] ??
5267
+ (unsupported ? undefined : existing[cap]) ??
5268
+ (acceptDefaults || prompt === undefined
5269
+ ? scopedCapabilityName(def.name, cap)
5270
+ : await promptCapabilityMapping(io, prompt, def.name, cap));
5271
+ resolved[cap] = chosen;
5272
+ // Identity rows are dropped hub-side, and a carried-forward row the hub
5273
+ // already holds needs no rewrite — so neither is worth a write.
5274
+ if (chosen !== cap && existing[cap] !== chosen)
5275
+ toRecord[cap] = chosen;
4427
5276
  }
5277
+ plans.push({ def, resolved, toRecord });
5278
+ }
5279
+ const mapped = Object.fromEntries(plans.map((p) => [p.def.name, p.resolved]));
5280
+ const wouldRecord = plans.filter((p) => Object.keys(p.toRecord).length > 0);
5281
+ // 8. The server diff, the same source of truth `push` uses.
5282
+ const { res: listRes, cred: listCred } = await authedGet(io, origin, slot, holder.cred, '/api/workflows');
5283
+ assertAuthOk(listRes, listCred, origin);
5284
+ holder.cred = listCred;
5285
+ let serverMap;
5286
+ try {
5287
+ serverMap = parseWorkflowList(await listRes.json());
5288
+ }
5289
+ catch (e) {
5290
+ throw new CliError(e.message);
4428
5291
  }
5292
+ const { toPush, unchanged } = computeServerDiff(candidates, serverMap, false);
5293
+ for (const c of unchanged)
5294
+ io.err(`= ${c.name} (unchanged)`);
5295
+ if (dryRun) {
5296
+ for (const c of toPush)
5297
+ io.err(c.status === 'new' ? `+ ${c.name} (new)` : `~ ${c.name} (changed)`);
5298
+ for (const plan of wouldRecord) {
5299
+ for (const [authored, org] of Object.entries(plan.toRecord)) {
5300
+ io.err(` would record ${plan.def.name}: ${authored} → ${org}`);
5301
+ }
5302
+ }
5303
+ print(io, {
5304
+ ok: true,
5305
+ dryRun: true,
5306
+ hub: origin,
5307
+ source: sourceRef,
5308
+ mapped,
5309
+ wouldRecord: Object.fromEntries(wouldRecord.map((p) => [p.def.name, p.toRecord])),
5310
+ new: toPush.filter((c) => c.status === 'new').map((c) => c.name),
5311
+ changed: toPush.filter((c) => c.status === 'changed').map((c) => c.name),
5312
+ unchanged: unchanged.map((c) => c.name),
5313
+ wouldPush: toPush.map((c) => c.name),
5314
+ });
5315
+ return 0;
5316
+ }
5317
+ // 9. RECORD, THEN PUBLISH. A hub with no mapping writer throws here — with
5318
+ // zero create_workflow calls behind it.
5319
+ const recorded = [];
5320
+ for (const plan of wouldRecord) {
5321
+ await recordCapabilityMappings(transport, plan.def.name, plan.toRecord, origin);
5322
+ recorded.push(plan.def.name);
5323
+ for (const [authored, org] of Object.entries(plan.toRecord)) {
5324
+ io.err(` recorded ${plan.def.name}: ${authored} → ${org}`);
5325
+ }
5326
+ }
5327
+ // 10. Publish, on push's ladder.
5328
+ holder.cred = await ensureFreshOAuth(io, origin, slot, holder.cred);
5329
+ const published = await publishCandidates(io, origin, slot, holder, toPush, selectedDependencies);
4429
5330
  print(io, {
4430
- ok: failed.length === 0,
5331
+ ok: published.failed.length === 0,
4431
5332
  hub: origin,
4432
- ...(bundle === undefined ? {} : { bundleDigest: bundle.digest, publication: bundle.publicationState }),
4433
- pushed: pushedNames,
4434
- noop: noopNames,
5333
+ source: sourceRef,
5334
+ mapped,
5335
+ recorded,
5336
+ pushed: published.pushed,
5337
+ noop: published.noop,
4435
5338
  unchanged: unchanged.map((c) => c.name),
4436
- skipped,
4437
- failed,
5339
+ skipped: published.skipped,
5340
+ failed: published.failed,
5341
+ capabilities: published.capabilities,
4438
5342
  });
4439
- return failed.length === 0 ? 0 : 1;
5343
+ return published.failed.length === 0 ? 0 : 1;
4440
5344
  }
4441
5345
  finally {
4442
- if (bundle !== undefined)
4443
- rmSync(bundle.cleanupRoot, { recursive: true, force: true });
5346
+ rmSync(workRoot, { recursive: true, force: true });
4444
5347
  }
4445
5348
  }
4446
5349
  /**
@@ -4626,6 +5529,7 @@ async function dispatchStart(io, args) {
4626
5529
  */
4627
5530
  async function dispatchCancel(io, args) {
4628
5531
  const workflow = need(args, 1, 'workflow');
5532
+ assertWorkflowIdShape(workflow);
4629
5533
  if (args.missingOptionValues.has('reason')) {
4630
5534
  throw new CliError('missing value for --reason: expected --reason <text>');
4631
5535
  }
@@ -4688,6 +5592,7 @@ async function dispatchCancel(io, args) {
4688
5592
  async function dispatchRetry(io, args) {
4689
5593
  const workflow = need(args, 1, 'workflow');
4690
5594
  const path = need(args, 2, 'path');
5595
+ assertWorkflowIdShape(workflow);
4691
5596
  if (args.options.has('by')) {
4692
5597
  throw new CliError('owenloop retry: --by cannot be combined with --hub — the hub attributes the retry to the authenticated human principal');
4693
5598
  }
@@ -4718,6 +5623,116 @@ async function dispatchRetry(io, args) {
4718
5623
  print(io, { ok: true, action: 'retry', path, workflow, hub: origin });
4719
5624
  return 0;
4720
5625
  }
5626
+ /** List the hub's human-input gates without reshaping its response contract. */
5627
+ async function dispatchPendingGates(io, args) {
5628
+ if (args.positionals.length !== 1) {
5629
+ throw new CliError('invalid pending-gates arguments; usage: owenloop pending-gates --hub <url>');
5630
+ }
5631
+ if (args.missingOptionValues.has('hub') || last(args, 'hub') === undefined) {
5632
+ throw new CliError('missing value for --hub: expected --hub <url>');
5633
+ }
5634
+ const origin = resolveStartHub(io, args);
5635
+ const slot = { principal: 'human' };
5636
+ const cred = readCredential(io, origin, slot);
5637
+ if (cred === null) {
5638
+ throw new CliError(`no human credential for ${origin} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
5639
+ }
5640
+ const { res, cred: used } = await authedPost(io, origin, slot, cred, '/api/pending_gates', {});
5641
+ if (res.status === 401)
5642
+ assertAuthOk(res, used, origin);
5643
+ if (!res.ok) {
5644
+ const message = await hubRequestMessage(res);
5645
+ throw new CliError(message ?? `hub ${origin} rejected the request (HTTP ${res.status})`);
5646
+ }
5647
+ let body;
5648
+ try {
5649
+ body = (await res.json());
5650
+ }
5651
+ catch {
5652
+ throw new CliError('pending_gates: malformed success response — body is not valid JSON');
5653
+ }
5654
+ print(io, body);
5655
+ return 0;
5656
+ }
5657
+ /**
5658
+ * `owenloop reject --hub` — the human control-plane counterpart to local
5659
+ * `engine.reject()`. The hub owns attribution, so a remote request cannot
5660
+ * carry the local-only `--by` authority input.
5661
+ */
5662
+ async function dispatchReject(io, args) {
5663
+ const workflow = need(args, 1, 'workflow');
5664
+ const path = need(args, 2, 'path');
5665
+ assertWorkflowIdShape(workflow);
5666
+ if (args.options.has('by')) {
5667
+ throw new CliError('owenloop reject: --by cannot be combined with --hub — the hub attributes the rejection to the authenticated human principal');
5668
+ }
5669
+ const text = last(args, 'text');
5670
+ if (args.missingOptionValues.has('text') || text === undefined) {
5671
+ throw new CliError('missing value for --text: expected --text <reason>');
5672
+ }
5673
+ if (text.trim() === '') {
5674
+ throw new CliError('invalid empty value for --text: expected --text <reason>');
5675
+ }
5676
+ if (args.missingOptionValues.has('requested')) {
5677
+ throw new CliError('missing value for --requested: expected --requested <modifier>');
5678
+ }
5679
+ const requested = last(args, 'requested');
5680
+ const origin = resolveStartHub(io, args);
5681
+ const slot = { principal: 'human' };
5682
+ const cred = readCredential(io, origin, slot);
5683
+ if (cred === null) {
5684
+ throw new CliError(`no human credential for ${origin} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
5685
+ }
5686
+ const request = {
5687
+ workflow,
5688
+ path,
5689
+ reason: text,
5690
+ ...(requested !== undefined ? { requested } : {}),
5691
+ };
5692
+ const { res, cred: used } = await authedPost(io, origin, slot, cred, '/api/reject_artifact', request);
5693
+ if (res.status === 401)
5694
+ assertAuthOk(res, used, origin);
5695
+ if (!res.ok) {
5696
+ const message = await hubRequestMessage(res);
5697
+ throw new CliError(message ?? `hub ${origin} rejected the request (HTTP ${res.status})`);
5698
+ }
5699
+ print(io, {
5700
+ ok: true,
5701
+ action: 'reject',
5702
+ path,
5703
+ workflow,
5704
+ hub: origin,
5705
+ ...(requested !== undefined ? { requested } : {}),
5706
+ });
5707
+ return 0;
5708
+ }
5709
+ /**
5710
+ * `owenloop provide --hub` — supply a hosted workflow input using the human
5711
+ * control plane. Local input provisioning remains in `main()`.
5712
+ */
5713
+ async function dispatchProvide(io, args) {
5714
+ const workflow = need(args, 1, 'workflow');
5715
+ const name = need(args, 2, 'name');
5716
+ assertWorkflowIdShape(workflow);
5717
+ // Keep this ahead of binding, credentials, and fetch: malformed input has no
5718
+ // external effects, matching the local provide command's JSON contract.
5719
+ const value = parseJson(last(args, 'value'));
5720
+ const origin = resolveStartHub(io, args);
5721
+ const slot = { principal: 'human' };
5722
+ const cred = readCredential(io, origin, slot);
5723
+ if (cred === null) {
5724
+ throw new CliError(`no human credential for ${origin} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
5725
+ }
5726
+ const { res, cred: used } = await authedPost(io, origin, slot, cred, '/api/provide_input', { workflow, name, value });
5727
+ if (res.status === 401)
5728
+ assertAuthOk(res, used, origin);
5729
+ if (!res.ok) {
5730
+ const message = await hubRequestMessage(res);
5731
+ throw new CliError(message ?? `hub ${origin} rejected the request (HTTP ${res.status})`);
5732
+ }
5733
+ print(io, { ok: true, provided: name, workflow, hub: origin });
5734
+ return 0;
5735
+ }
4721
5736
  /**
4722
5737
  * `owenloop instance` — read a HUB instance's live state from the terminal.
4723
5738
  *
@@ -4761,14 +5776,15 @@ async function dispatchInstance(io, args) {
4761
5776
  if (workflow === undefined || workflow === '') {
4762
5777
  throw new CliError(`missing required argument: workflow (${USAGE_FORMS})`);
4763
5778
  }
5779
+ assertWorkflowIdShape(workflow);
4764
5780
  const origin = resolveStartHub(io, args);
4765
5781
  const slot = { principal: 'human' };
4766
5782
  const cred = readCredential(io, origin, slot);
4767
5783
  if (cred === null) {
4768
5784
  throw new CliError(`no human credential for ${origin} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
4769
5785
  }
4770
- // The workflow id is a path segment, so it must be encoded — an id carrying a
4771
- // slash would otherwise silently address a different route.
5786
+ // Retain path-segment encoding as defense in depth: the validator currently
5787
+ // excludes slashes, but the hub remains a separate service boundary.
4772
5788
  const path = `/api/status/${encodeURIComponent(workflow)}`;
4773
5789
  const { res, cred: used } = await authedGet(io, origin, slot, cred, path);
4774
5790
  if (res.status === 401)
@@ -5177,8 +6193,8 @@ async function dispatchCapability(io, args) {
5177
6193
  if (sub === 'list') {
5178
6194
  const { res, cred: used } = await authedGet(io, origin, slot, cred, '/api/capability_routes');
5179
6195
  // The GET deliberately uses `assertAuthOk` unchanged (frozen contract), so
5180
- // a non-401 non-2xx surfaces its generic wording rather than the hub's
5181
- // `message`. Message passthrough is a POST-path behavior below.
6196
+ // a non-401/non-429 non-2xx surfaces its generic wording while a 429 uses
6197
+ // the helper's rate-limit wording. Message passthrough is a POST-path behavior below.
5182
6198
  assertAuthOk(res, used, origin);
5183
6199
  let body;
5184
6200
  try {
@@ -5338,7 +6354,7 @@ async function dispatchCapability(io, args) {
5338
6354
  * finds out it happened.
5339
6355
  *
5340
6356
  * **`routing show <workflow>` is NOT the local `show` command.** `owenloop show`
5341
- * reads a workflow DEFINITION out of the local sqlite store and takes no `--hub`;
6357
+ * reads raw workflow artifacts out of the local sqlite store and takes no `--hub`;
5342
6358
  * `routing show` reads one STARTED RUN's routing state off the hub. They share no
5343
6359
  * code path, and this deliberately did not arrive as a `--hub` flag on the local
5344
6360
  * command — the same separation `instance show` keeps.
@@ -5396,6 +6412,7 @@ async function dispatchRouting(io, args) {
5396
6412
  if (rawWorkflow === undefined || rawWorkflow === '') {
5397
6413
  throw new CliError(`missing required argument: <workflow> (${USAGE_FORMS})`);
5398
6414
  }
6415
+ assertWorkflowIdShape(rawWorkflow);
5399
6416
  workflow = rawWorkflow;
5400
6417
  }
5401
6418
  else if (sub === 'alerts') {
@@ -5514,9 +6531,8 @@ async function dispatchRouting(io, args) {
5514
6531
  return 0;
5515
6532
  }
5516
6533
  if (sub === 'show') {
5517
- // The workflow id is a path segment, so it must be encoded — an id carrying
5518
- // a slash would otherwise silently address a different route
5519
- // (`dispatchInstance`'s precedent).
6534
+ // Retain path-segment encoding as defense in depth: the validator currently
6535
+ // excludes slashes, but the hub remains a separate service boundary.
5520
6536
  const body = await readJson(`/api/run_routing/${encodeURIComponent(workflow)}`, 'run_routing: malformed success response');
5521
6537
  let wire;
5522
6538
  try {
@@ -5787,8 +6803,9 @@ async function dispatchCrew(io, args) {
5787
6803
  try {
5788
6804
  if (sub === 'list') {
5789
6805
  const { res, cred: used } = await authedGet(io, origin, slot, cred, '/api/crews');
5790
- // `assertAuthOk`'s generic wording (frozen contract, mirrors `binding
5791
- // list`); message passthrough is a POST-path behavior below.
6806
+ // `assertAuthOk`'s generic wording for non-401/non-429 errors (frozen
6807
+ // contract, mirrors `binding list`); a 429 uses its rate-limit wording.
6808
+ // Message passthrough is a POST-path behavior below.
5792
6809
  assertAuthOk(res, used, origin);
5793
6810
  let body;
5794
6811
  try {
@@ -6200,18 +7217,24 @@ async function probeAgentSlots(io, origin, names, identities) {
6200
7217
  return { verified, sawSlot, sawRevoked };
6201
7218
  }
6202
7219
  /**
6203
- * The interactive prompt for setup, or the non-interactive guard. Returns
6204
- * `io.prompt` when injected; else, when stdin is a real TTY, the default
6205
- * readline prompt; else a `CliError` naming the two bypass flags — thrown BEFORE
6206
- * any mutation so a scripted/piped run never blocks or half-applies.
7220
+ * The interactive prompt for a verb that must ask, or the non-interactive
7221
+ * guard. Returns `io.prompt` when injected; else, when stdin is a real TTY, the
7222
+ * default readline prompt; else a `CliError` naming that verb's bypass flags —
7223
+ * thrown BEFORE any mutation (and, for `install`, before any hub I/O at all) so
7224
+ * a scripted/piped run never blocks and never half-applies.
7225
+ *
7226
+ * `unavailable` is the refusal wording. It defaults to `setup`'s, so `setup`'s
7227
+ * callers keep their message byte-for-byte; `install` passes its own, which
7228
+ * must name `--map` and `--accept-defaults`.
6207
7229
  */
6208
- function requirePrompt(io) {
7230
+ function requirePrompt(io, unavailable) {
6209
7231
  if (io.prompt)
6210
7232
  return io.prompt;
6211
7233
  if (process.stdin.isTTY)
6212
7234
  return defaultPrompt;
6213
- throw new CliError('setup needs to ask which Scoped Identity to use, but stdin is not interactive — pass ' +
6214
- '--new-agent <name> to create a new Scoped Identity, or --replace-agent <name> to replace an existing one');
7235
+ throw new CliError(unavailable ??
7236
+ 'setup needs to ask which Scoped Identity to use, but stdin is not interactive — pass ' +
7237
+ '--new-agent <name> to create a new Scoped Identity, or --replace-agent <name> to replace an existing one');
6215
7238
  }
6216
7239
  /**
6217
7240
  * Prompt for an agent name (Flow A). Offers `sanitizeAgentName(hostname())` as a
@@ -7188,7 +8211,7 @@ async function runDoctor(io, origin) {
7188
8211
  * the async path, so every existing command and test keeps working exactly as
7189
8212
  * before.
7190
8213
  */
7191
- export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'publish', 'trust', 'push', 'start', 'cancel', 'retry', 'instance', 'agent', 'capability', 'routing', 'crew', 'roster', 'setup', 'doctor', 'enrollments', 'mcp', 'shift']);
8214
+ export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'publish', 'trust', 'push', 'install', 'start', 'pending-gates', 'cancel', 'provide', 'reject', 'retry', 'instance', 'agent', 'capability', 'routing', 'crew', 'roster', 'setup', 'doctor', 'enrollments', 'mcp', 'shift']);
7192
8215
  export async function mainAsync(argv, io = defaultIO()) {
7193
8216
  // Delegate execution-side and shift argv tails before root parsing. Their
7194
8217
  // roles own their option grammars, including repeated/value forms that the
@@ -7214,13 +8237,16 @@ export async function mainAsync(argv, io = defaultIO()) {
7214
8237
  }
7215
8238
  const args = parseArgs(argv);
7216
8239
  const command = args.positionals[0];
7217
- if (command === undefined || !ASYNC_COMMANDS.has(command)) {
8240
+ const asyncBundleGc = command === 'bundle' && args.positionals[1] === 'gc';
8241
+ if (command === undefined || (!ASYNC_COMMANDS.has(command) && !asyncBundleGc)) {
7218
8242
  return main(argv, io);
7219
8243
  }
7220
8244
  try {
7221
8245
  const short = preflight(command, args, io);
7222
8246
  if (short !== undefined)
7223
8247
  return short;
8248
+ if (asyncBundleGc)
8249
+ return await dispatchBundleGc(io, args);
7224
8250
  switch (command) {
7225
8251
  case 'add':
7226
8252
  return await dispatchAdd(io, args);
@@ -7236,10 +8262,18 @@ export async function mainAsync(argv, io = defaultIO()) {
7236
8262
  return await dispatchTrust(io, args);
7237
8263
  case 'push':
7238
8264
  return await dispatchPush(io, args);
8265
+ case 'install':
8266
+ return await dispatchInstall(io, args);
7239
8267
  case 'start':
7240
8268
  return await dispatchStart(io, args);
8269
+ case 'pending-gates':
8270
+ return args.options.has('hub') ? await dispatchPendingGates(io, args) : main(argv, io);
7241
8271
  case 'cancel':
7242
8272
  return await dispatchCancel(io, args);
8273
+ case 'provide':
8274
+ return args.options.has('hub') ? await dispatchProvide(io, args) : main(argv, io);
8275
+ case 'reject':
8276
+ return args.options.has('hub') ? await dispatchReject(io, args) : main(argv, io);
7243
8277
  case 'retry':
7244
8278
  // Local engine store unless --hub; only the hub half is async, and
7245
8279
  // main()'s own `case 'retry'` stays the local implementation so the