owenloop 0.4.0 → 0.5.0

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 (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -391,8 +391,14 @@ function idleEligible(step, arts, time) {
391
391
  * output to discharge. This is the scheduling gate (§11.4): necessary, not
392
392
  * sufficient; the commit fingerprint (§12.2) is the correctness boundary.
393
393
  * Assumes `pendingOwed` has already been materialized into `arts`.
394
+ *
395
+ * `opts.ignoreFreeze` (used by `modelCheck`'s stall-vs-true-deadlock
396
+ * recompute): when true, treat every `frozen()` guard as false — i.e.
397
+ * "what would be eligible if every maxAttempts/maxSchemaFailures/held brake
398
+ * were lifted (a human `retry` = unlimited attempts)". It ONLY lifts the
399
+ * freeze; group-exclusivity, input-green gates, and `isDebt` are untouched.
394
400
  */
395
- export function eligibleFirings(def, arts, time) {
401
+ export function eligibleFirings(def, arts, time, opts) {
396
402
  const firings = [];
397
403
  for (const step of def.steps) {
398
404
  // M2: calls: steps are machine-handled (the engine spawns the child); never emit a worker firing.
@@ -436,7 +442,7 @@ export function eligibleFirings(def, arts, time) {
436
442
  if (plainSatisfied) {
437
443
  const outs = plainOutputs(step).filter((p) => {
438
444
  const a = arts.get(p);
439
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
445
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
440
446
  });
441
447
  if (outs.length) {
442
448
  firings.push({ step: step.name, key: '', inputs: plainPaths, outputs: outs });
@@ -463,7 +469,9 @@ export function eligibleFirings(def, arts, time) {
463
469
  // never be a group member today — this check is defensive, not reachable,
464
470
  // and exists so a future relaxation of the singleton-only restriction can't
465
471
  // silently reopen the eligibility/commit-check gap this file fixes.
466
- if (!isDebt(outArt) || frozen(outArt, step) || groupBlockingWinner(def, arts, outPath) !== undefined)
472
+ if (!isDebt(outArt) ||
473
+ (!opts?.ignoreFreeze && frozen(outArt, step)) ||
474
+ groupBlockingWinner(def, arts, outPath) !== undefined)
467
475
  continue;
468
476
  firings.push({
469
477
  step: step.name,
@@ -494,7 +502,7 @@ export function eligibleFirings(def, arts, time) {
494
502
  .map((p) => p.stem)
495
503
  .filter((p) => {
496
504
  const a = arts.get(p);
497
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
505
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
498
506
  });
499
507
  if (outs.length) {
500
508
  firings.push({
@@ -519,7 +527,7 @@ export function eligibleFirings(def, arts, time) {
519
527
  // Workflow IS all-green. Check if the evaluator still has a debt to discharge.
520
528
  const outs = plainOutputs(step).filter((p) => {
521
529
  const a = arts.get(p);
522
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
530
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
523
531
  });
524
532
  if (outs.length > 0) {
525
533
  firings.push({
@@ -536,7 +544,7 @@ export function eligibleFirings(def, arts, time) {
536
544
  if (idleEligible(step, arts, time)) {
537
545
  const outs = plainOutputs(step).filter((p) => {
538
546
  const a = arts.get(p);
539
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
547
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
540
548
  });
541
549
  if (outs.length > 0) {
542
550
  firings.push({
@@ -561,6 +569,77 @@ function plainOutputs(step) {
561
569
  out.push(sealPath(p.stem));
562
570
  return out;
563
571
  }
572
+ /**
573
+ * Forward stem-reachability fixpoint from the seeded workflow inputs: a step's
574
+ * produced stems become reachable once every one of its consumed stems is
575
+ * reachable. Intentionally duplicates defs.ts's `reachabilityErrors` fixpoint
576
+ * rather than importing it — defs.ts does not import model.ts and model.ts
577
+ * does not import defs.ts; canEverFire's discharge-set logic (below) depends
578
+ * on model.ts's own mode helpers, so importing across the boundary either way
579
+ * would create a cycle. This local copy keeps the import graph acyclic.
580
+ */
581
+ function reachableStems(def) {
582
+ const reachable = new Set(def.inputs.map((i) => i.name));
583
+ let changed = true;
584
+ while (changed) {
585
+ changed = false;
586
+ for (const step of def.steps) {
587
+ if (!step.consumes.every((c) => reachable.has(c.stem)))
588
+ continue;
589
+ for (const p of step.produces) {
590
+ if (!reachable.has(p.stem)) {
591
+ reachable.add(p.stem);
592
+ changed = true;
593
+ }
594
+ }
595
+ }
596
+ }
597
+ return reachable;
598
+ }
599
+ /**
600
+ * Pure static predicate: can `step` EVER fire, under ANY search bounds?
601
+ *
602
+ * A SOUND detector of deadness: returns false ONLY when we are CERTAIN no
603
+ * firing can ever be pushed for this step, mirroring the discharge-set logic
604
+ * `eligibleFirings` (above) actually uses. When uncertain, returns true (the
605
+ * safe, non-failing default) — a false "structurally dead" would wrongly make
606
+ * `check` exit nonzero, so soundness is biased toward under-reporting.
607
+ *
608
+ * - Reachability: if any consumed stem is not reachable from the workflow
609
+ * inputs (see `reachableStems`), the step can never fire. Belt-and-suspenders
610
+ * — `validateDef`'s `reachabilityErrors` already turns this into a hard error
611
+ * before `modelCheck` ever runs, so this arm is defensive, not the live path.
612
+ * - Judge step (`step.judges`): fires against the judged stem, not a produces
613
+ * set; can-fire iff the judged stem is reachable (already implied by the
614
+ * reachability arm above, since a judge step consumes the judged stem — kept
615
+ * explicit for clarity and to stay correct if judge-step synthesis changes).
616
+ * - reduce: the discharge set is `singletonProduces(step)` only (see the
617
+ * reduce branch of `eligibleFirings`) — zero singleton produces means no
618
+ * firing is ever pushed, regardless of bounds.
619
+ * - map: needs both a map-consume and a map-produce to bind an element.
620
+ * - plain (inputsGreen / allGreen / idle): the discharge set is `plainOutputs`
621
+ * (singleton produces + collection seals) — empty means no firing ever.
622
+ *
623
+ * `reachable` may be precomputed once by the caller and passed in (modelCheck
624
+ * calls this per dead step and must not recompute the fixpoint each time).
625
+ */
626
+ export function canEverFire(step, def, reachable) {
627
+ const reach = reachable ?? reachableStems(def);
628
+ if (!step.consumes.every((c) => reach.has(c.stem)))
629
+ return false;
630
+ if (step.judges)
631
+ return reach.has(step.judges);
632
+ switch (stepMode(step)) {
633
+ case 'reduce':
634
+ return singletonProduces(step).length > 0;
635
+ case 'map':
636
+ return !!mapProduce(step) && !!mapConsume(step);
637
+ case 'plain':
638
+ return plainOutputs(step).length > 0;
639
+ default:
640
+ return true; // not certain of deadness — default to can-fire (soundness bias)
641
+ }
642
+ }
564
643
  // ---- level-triggered maintenance (§11.8, §12.3) -----------------------------
565
644
  /**
566
645
  * The standing guard: re-derive the invariant "an artifact is green only while
@@ -1525,6 +1604,9 @@ function seedArts(def, assumeProvided = false) {
1525
1604
  // seedOwed=false → seed green (version 1); seedOwed=true → seed owed (version 0)
1526
1605
  // The checker has no runtime `provide` values, so seedOwed inputs start owed —
1527
1606
  // unless assumeProvided, which models "the operator ran `provide` at create".
1607
+ // This function's own default stays false; the `owenloop check` CLI command
1608
+ // now passes assumeProvided: true by default (its `--strict-inputs` flag
1609
+ // passes false to restore this owed-start behavior) — see CheckOptions.
1528
1610
  const seedGreen = !input.seedOwed || assumeProvided;
1529
1611
  arts.set(input.name, {
1530
1612
  workflow: '',
@@ -1546,7 +1628,7 @@ function eligibleOutcomes(def, arts, firing) {
1546
1628
  return ['green'];
1547
1629
  // §24: a judge firing's own verdict is against the judged stem, not against a
1548
1630
  // produce of its own (judge steps declare `produces: []`). Model the two verbs
1549
- // the judge agent can issue (green/reject, Q2) as their own outcomes, entirely
1631
+ // the judge Step Agent can issue (green/reject, Q2) as their own outcomes, entirely
1550
1632
  // separate from the producer-outcome branches below.
1551
1633
  if (step.judges) {
1552
1634
  // §26: if this is the last pending judge and approving would flip the
@@ -1857,10 +1939,29 @@ function canonicalKey(def, arts) {
1857
1939
  * Bounded reachability / liveness checker over a workflow definition.
1858
1940
  *
1859
1941
  * Explores the full (or depth/state-bounded) state space via BFS to find:
1860
- * - deadlocks: reachable states that are not done and have no eligible firings
1861
- * - stuck states: reachable states with a stalled debt
1942
+ * - a non-done, zero-eligible-firings state is split into exactly ONE of two
1943
+ * mutually exclusive buckets by recomputing eligibility with every freeze
1944
+ * lifted (unlimited attempts — see `eligibleFirings`'s `ignoreFreeze`):
1945
+ * - stall states: the recompute yields >= 1 firing — the state's only
1946
+ * blocker is a frozen/stalled debt (maxAttempts / maxSchemaFailures /
1947
+ * held). A by-design human-escalation brake. EXPECTED, never a defect.
1948
+ * - true deadlocks: the recompute STILL yields zero firings — a genuine
1949
+ * structural dead-end with no path to completion even at unlimited
1950
+ * attempts. A real defect.
1951
+ * - stuck states: reachable states that have a stalled debt but STILL have
1952
+ * >= 1 eligible firing elsewhere (a brake tripped on one branch while the
1953
+ * line moves on another). Informational only; a no-moves state is never
1954
+ * listed here — it lands in `stallStates` or `deadlocks` instead, so no
1955
+ * state is ever double-listed.
1862
1956
  * - completability: whether any reachable state is done (with an example path)
1863
- * - dead steps: steps whose name never appears as a firing in any explored transition
1957
+ * - dead steps: steps whose name never appears as a firing in any explored
1958
+ * transition. Split into two categories by the static `canEverFire` check
1959
+ * (independent of search bounds):
1960
+ * - structurally-dead: `canEverFire` is false — the step can NEVER fire
1961
+ * regardless of `--max-depth`/`--max-states`. A genuine wiring defect.
1962
+ * - unreached-within-bounds: `canEverFire` is true — the step CAN fire in
1963
+ * principle but the bounded search didn't reach it. A bounds artifact,
1964
+ * not a defect; raising `--max-states`/`--max-depth` may surface it.
1864
1965
  *
1865
1966
  * Pure — no store, no engine, no IO.
1866
1967
  */
@@ -1878,10 +1979,12 @@ export function modelCheck(def, opts = {}) {
1878
1979
  bounded: false,
1879
1980
  boundsHit: [],
1880
1981
  deadlocks: [],
1982
+ stallStates: [],
1881
1983
  stuck: [],
1882
1984
  completable: false,
1883
1985
  completePath: undefined,
1884
- deadSteps: [],
1986
+ structurallyDeadSteps: [],
1987
+ unreachedSteps: [],
1885
1988
  invariantViolations: [],
1886
1989
  stats: { statesExplored: 0, depthReached: 0 },
1887
1990
  };
@@ -1926,17 +2029,29 @@ export function modelCheck(def, opts = {}) {
1926
2029
  }
1927
2030
  continue; // done states have no successors
1928
2031
  }
1929
- // Check stuck (any debt.stalled)
1930
- if (status.debts.some((d) => d.stalled)) {
1931
- report.stuck.push({ path: node.path });
1932
- // continue exploring (there may be other paths)
1933
- }
1934
2032
  const firings = status.eligible;
1935
- // Check deadlock: non-done, no eligible firings
2033
+ // Non-done state with no eligible firings: classify by recomputing eligibility
2034
+ // as if every freeze/stall were lifted (unlimited attempts). If a producer
2035
+ // would re-arm → an EXPECTED stall state (a by-design brake). If not → a
2036
+ // TRUE deadlock (a structural dead-end with no path to completion even at
2037
+ // unlimited attempts).
1936
2038
  if (firings.length === 0 && !status.done) {
1937
- report.deadlocks.push({ path: node.path });
2039
+ const lifted = eligibleFirings(def, node.arts, undefined, { ignoreFreeze: true });
2040
+ if (lifted.length > 0) {
2041
+ report.stallStates.push({ path: node.path });
2042
+ }
2043
+ else {
2044
+ report.deadlocks.push({ path: node.path });
2045
+ }
1938
2046
  continue;
1939
2047
  }
2048
+ // The state HAS eligible firings (the line can still move). If a brake tripped
2049
+ // on some *other* branch, record it as an informational stuck state. A no-moves
2050
+ // stall state never reaches here (it `continue`d above), so no state is ever
2051
+ // listed in both `stuck` and `stallStates`/`deadlocks`.
2052
+ if (status.debts.some((d) => d.stalled)) {
2053
+ report.stuck.push({ path: node.path });
2054
+ }
1940
2055
  // Respect maxDepth
1941
2056
  if (node.depth >= maxDepth) {
1942
2057
  boundsHit.add('maxDepth');
@@ -1970,9 +2085,21 @@ export function modelCheck(def, opts = {}) {
1970
2085
  report.stats.depthReached = depthReached;
1971
2086
  report.boundsHit = [...boundsHit];
1972
2087
  report.bounded = boundsHit.size > 0;
1973
- // Dead steps: steps in the def that never appeared as a firing.step
1974
- report.deadSteps = def.steps
1975
- .filter((l) => !firedSteps.has(l.name))
1976
- .map((l) => l.name);
2088
+ // Dead steps: steps in the def that never appeared as a firing.step, split
2089
+ // by the static canEverFire check into structurally-dead (a real wiring
2090
+ // defect — can never fire regardless of bounds) vs unreached-within-bounds
2091
+ // (can fire in principle; the bounded search just didn't reach it).
2092
+ // Compute the reachability fixpoint once, not per dead step.
2093
+ const reachable = reachableStems(def);
2094
+ for (const l of def.steps) {
2095
+ if (firedSteps.has(l.name))
2096
+ continue;
2097
+ if (canEverFire(l, def, reachable)) {
2098
+ report.unreachedSteps.push(l.name);
2099
+ }
2100
+ else {
2101
+ report.structurallyDeadSteps.push(l.name);
2102
+ }
2103
+ }
1977
2104
  return report;
1978
2105
  }
@@ -137,11 +137,11 @@ export interface Order {
137
137
  /** Declares which kind of executor this order is for. Absent = 'agent'
138
138
  * (today's behavior). Opaque to the engine; carried through verbatim from
139
139
  * the step definition, same pass-through contract as `model`/`x`. */
140
- worker?: string;
141
- /** The command string for a `worker: command` order. Opaque to the engine
140
+ executor?: string;
141
+ /** The command string for a `executor: command` order. Opaque to the engine
142
142
  * — never parsed, never shelled out. */
143
143
  command?: string;
144
- /** Opaque config object for a non-agent/non-command worker type (or
144
+ /** Opaque config object for a non-agent/non-command executor type (or
145
145
  * alongside `command`). Carried through untouched, contents never read. */
146
146
  spec?: Record<string, unknown>;
147
147
  /** §27.3: the step's opaque `x:` extension map, carried through untouched
@@ -256,13 +256,13 @@ export interface ProducePattern {
256
256
  cadence?: string;
257
257
  maxRunsPerDay?: number;
258
258
  /** Declares which kind of executor this judge's synthesized order is for.
259
- * Same opaque-passthrough contract as StepDef.worker — default 'agent'
259
+ * Same opaque-passthrough contract as StepDef.executor — default 'agent'
260
260
  * when omitted. */
261
- worker?: string;
262
- /** Required when worker is 'command'; the command string for that worker
261
+ executor?: string;
262
+ /** Required when executor is 'command'; the command string for that executor
263
263
  * to run. Opaque to the engine — never parsed, never shelled out. */
264
264
  command?: string;
265
- /** Optional opaque config object for a non-agent/non-command worker type
265
+ /** Optional opaque config object for a non-agent/non-command executor type
266
266
  * (or additionally alongside `command`). Shape-checked as a plain map
267
267
  * only (mirrors `x:`'s asExtension contract) — contents never read. */
268
268
  spec?: Record<string, unknown>;
@@ -325,11 +325,11 @@ export interface StepDef {
325
325
  * unchanged). Opaque to the engine beyond the shape rules validateDef
326
326
  * enforces; carried through verbatim on the Order, same contract as
327
327
  * `model`. */
328
- worker?: string;
329
- /** Required when worker is 'command'; the command string for that worker
328
+ executor?: string;
329
+ /** Required when executor is 'command'; the command string for that executor
330
330
  * to run. Opaque to the engine — never parsed, never shelled out. */
331
331
  command?: string;
332
- /** Optional opaque config object for a non-agent/non-command worker type
332
+ /** Optional opaque config object for a non-agent/non-command executor type
333
333
  * (or additionally alongside `command`). Shape-checked as a plain map
334
334
  * only (mirrors `x:`'s asExtension contract) — contents never read. */
335
335
  spec?: Record<string, unknown>;
@@ -347,11 +347,11 @@ export interface StepDef {
347
347
  idleAfterMs?: number;
348
348
  /** Per-step reap TTL override in milliseconds. Falls back to the engine's DEFAULT_REAP_TTL_MS. */
349
349
  reapTtlMs?: number;
350
- /** A2: opaque routing labels for peer-orchestrator claim filtering. A tick
351
- * caller passing a label filter only claims steps whose labels intersect it;
350
+ /** A2: opaque routing capabilities for peer-orchestrator claim filtering. A tick
351
+ * caller passing a capability filter only claims steps whose capabilities intersect it;
352
352
  * absent (or empty, normalized to absent at parse) = claimable by any caller.
353
- * Distinct from `worker`/`workers` (executor-kind), which this never touches. */
354
- labels?: string[];
353
+ * Distinct from `executor`/`executors` (executor-kind), which this never touches. */
354
+ capabilities?: string[];
355
355
  /** A3 (REL-8): per-step OPT-IN max total lease lifetime override in
356
356
  * milliseconds — the cap on `claimedAt + maxLease` past which renewals can no
357
357
  * longer keep a lease fresh. Overrides the engine `maxLeaseMs`; when both are
@@ -399,10 +399,10 @@ export interface WorkflowDef {
399
399
  /** §27.3: opaque workflow-level extension map (`x:`). Validated as a plain
400
400
  * map at load time, never interpreted by the engine. */
401
401
  x?: Record<string, unknown>;
402
- /** Optional allow-list of worker values; when present, validateDef errors
403
- * on any step/judge whose `worker` is not in this list (typo guard).
404
- * Absent = any worker string accepted. */
405
- workers?: string[];
402
+ /** Optional allow-list of executor values; when present, validateDef errors
403
+ * on any step/judge whose `executor` is not in this list (typo guard).
404
+ * Absent = any executor string accepted. */
405
+ executors?: string[];
406
406
  }
407
407
  export interface InputDef {
408
408
  name: string;
@@ -556,7 +556,12 @@ export interface CheckOptions {
556
556
  * Seed `seedOwed: true` inputs green, as if `provide` already ran. The checker
557
557
  * has no runtime provide values, so without this every seedOwed input starts
558
558
  * owed with no transition that can green it — a def whose inputs the operator
559
- * supplies at create time reports a false depth-0 deadlock. Default false.
559
+ * supplies at create time reports a false depth-0 deadlock. Default (this
560
+ * field, when calling `modelCheck` directly) is false — that library default
561
+ * is unchanged. The `owenloop check` CLI command, however, now defaults this
562
+ * to true (seedOwed inputs are assumed provided by default, modeling the
563
+ * operator's `provide` at create); its `--strict-inputs` flag opts back out
564
+ * to false, restoring the seedOwed-starts-owed behavior described above.
560
565
  */
561
566
  assumeProvided?: boolean;
562
567
  }
@@ -567,18 +572,55 @@ export interface CheckReport {
567
572
  bounded: boolean;
568
573
  /** Which bounds were hit, for honest reporting. */
569
574
  boundsHit: ('maxDepth' | 'maxStates')[];
570
- /** Reachable states where done=false and eligibleFirings=[]: a genuine deadlock. */
575
+ /**
576
+ * Reachable non-done states with zero eligible firings that have NO path to
577
+ * completion even at unlimited attempts — i.e. recomputing eligibility with
578
+ * all freezes lifted (a human `retry` = unlimited attempts) STILL yields
579
+ * zero firings. A genuine structural dead-end (TRUE deadlock). A definite
580
+ * defect only when the search was exhaustive (`!bounded`) — the
581
+ * maxCollectionSize cap can otherwise manufacture a spurious no-moves
582
+ * state. Always present ([] when none).
583
+ */
571
584
  deadlocks: CheckFinding[];
572
- /** Reachable states that have a stalled debt (judgmentRejects >= cap). */
585
+ /**
586
+ * Reachable non-done states with zero eligible firings whose ONLY blocker
587
+ * is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held).
588
+ * Recomputing eligibility with all freezes lifted (a human `retry` =
589
+ * unlimited attempts) yields >= 1 firing, so a producer would re-arm and
590
+ * the line could move. These are the DESIGNED human-escalation brakes —
591
+ * EXPECTED, never a defect; they do not affect the exit code. Always
592
+ * present ([] when none).
593
+ */
594
+ stallStates: CheckFinding[];
595
+ /**
596
+ * Reachable states that have a stalled debt (maxAttempts/maxSchemaFailures/
597
+ * held) BUT still have >= 1 eligible firing — a brake tripped on one branch
598
+ * while the line can still move on another. Informational; NOT a defect on
599
+ * its own. A no-moves state whose only blocker is a frozen debt is recorded
600
+ * under `stallStates` instead, never here — so no state appears in both
601
+ * `stuck` and `stallStates`/`deadlocks`.
602
+ */
573
603
  stuck: CheckFinding[];
574
604
  /** Whether any explored state is done, and (when true) one example path to it. */
575
605
  completable: boolean;
576
606
  completePath?: CheckStep[];
577
607
  /**
578
- * Step names that never appear as the firing step in any explored transition
579
- * (dynamically dead within the bounded search).
608
+ * Step names that never appear as the firing step in any explored transition,
609
+ * AND a static "can this step ever fire?" check (independent of bounds) is
610
+ * CERTAIN no firing can ever be pushed for it (see model.ts `canEverFire`).
611
+ * A genuine wiring defect — always present ([] when none), and (unlike
612
+ * `unreachedSteps`) ALWAYS a definite finding regardless of `bounded`,
613
+ * because the check needs no search bounds to be certain.
614
+ */
615
+ structurallyDeadSteps: string[];
616
+ /**
617
+ * Step names that never appear as the firing step in any explored transition,
618
+ * but the static `canEverFire` check says they COULD fire in principle — the
619
+ * bounded search just didn't reach them before exhausting `--max-states`/
620
+ * `--max-depth`. Informational only, NOT a defect: a bounds artifact. Raising
621
+ * the search bounds may make the step fire. Always present ([] when none).
580
622
  */
581
- deadSteps: string[];
623
+ unreachedSteps: string[];
582
624
  /**
583
625
  * Invariants that are violated in some reachable state. Always present ([]
584
626
  * when no invariants declared or none violated). Each entry is deduplicated by
@@ -1,4 +1,29 @@
1
1
  /** Small dependency-light helpers. */
2
+ /**
3
+ * A user-facing CLI/library error whose `message` is printed as-is (no stack
4
+ * trace) — the "expected, explained" failure class, distinct from a programming
5
+ * bug. Homed here in `util.ts` (which has no project-internal imports) so it can
6
+ * be shared by `cli.ts` (where `RateLimitError extends CliError`) and
7
+ * `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
8
+ * cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
9
+ * NOT re-exported from the package barrel (`src/index.ts`): it was module-private
10
+ * before, and the credential-write PR does not widen the public API beyond the
11
+ * functions the proposal names.
12
+ *
13
+ * `exitCode` lets a specific failure map to a distinct process exit status
14
+ * (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
15
+ * every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
16
+ * which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
17
+ * non-default codes today are exit 2 (hub unresolvable) and exit 3 (human
18
+ * credential absent/irrecoverable), used by `agent new`, `binding
19
+ * new|rm|list`, and `crew`'s five subcommands.
20
+ */
21
+ export declare class CliError extends Error {
22
+ readonly exitCode: number;
23
+ constructor(message: string, opts?: {
24
+ exitCode?: number;
25
+ });
26
+ }
2
27
  /**
3
28
  * `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
4
29
  * create it through a symlinked component (SEC-3, parent-directory half).
@@ -1,6 +1,32 @@
1
1
  /** Small dependency-light helpers. */
2
2
  import { createHash, randomBytes } from 'node:crypto';
3
3
  import { lstatSync, mkdirSync } from 'node:fs';
4
+ /**
5
+ * A user-facing CLI/library error whose `message` is printed as-is (no stack
6
+ * trace) — the "expected, explained" failure class, distinct from a programming
7
+ * bug. Homed here in `util.ts` (which has no project-internal imports) so it can
8
+ * be shared by `cli.ts` (where `RateLimitError extends CliError`) and
9
+ * `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
10
+ * cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
11
+ * NOT re-exported from the package barrel (`src/index.ts`): it was module-private
12
+ * before, and the credential-write PR does not widen the public API beyond the
13
+ * functions the proposal names.
14
+ *
15
+ * `exitCode` lets a specific failure map to a distinct process exit status
16
+ * (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
17
+ * every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
18
+ * which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
19
+ * non-default codes today are exit 2 (hub unresolvable) and exit 3 (human
20
+ * credential absent/irrecoverable), used by `agent new`, `binding
21
+ * new|rm|list`, and `crew`'s five subcommands.
22
+ */
23
+ export class CliError extends Error {
24
+ exitCode;
25
+ constructor(message, opts) {
26
+ super(message);
27
+ this.exitCode = opts?.exitCode ?? 1;
28
+ }
29
+ }
4
30
  /**
5
31
  * `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
6
32
  * create it through a symlinked component (SEC-3, parent-directory half).
@@ -0,0 +1,57 @@
1
+ /**
2
+ * execution settings file writer — the ONE place the root `owenloop` CLI writes
3
+ * into the execution-side settings file.
4
+ *
5
+ * `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
6
+ * settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
7
+ * NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
8
+ * `owenloop setup` can point `owenloop work` at the hub it just authenticated
9
+ * against.
10
+ *
11
+ * This module writes exactly ONE key — `hubOrigin` — and preserves every other
12
+ * key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
13
+ * `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
14
+ * unknown key). It never writes a secret: nothing secret is in scope here by
15
+ * construction (the hub ORIGIN is public).
16
+ *
17
+ * Corrupt-file policy: a settings file that exists but does not parse as a JSON
18
+ * OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
19
+ * it cannot safely merge into. That mirrors the work settings validator's
20
+ * wording family ("not an object").
21
+ *
22
+ * Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
23
+ * util.ts — no CLI/engine closure.
24
+ */
25
+ /**
26
+ * The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
27
+ * set and non-blank) wins over `HOME`, matching owenloop's own resolution and
28
+ * the owenloop credential store's `configDir`. Throws when neither is set.
29
+ */
30
+ export declare function owenloopSettingsPath(env: Record<string, string | undefined>): string;
31
+ /**
32
+ * Read and parse the execution settings file at `path`.
33
+ *
34
+ * - Missing file → `null` (an absent settings file is not an error; the writer
35
+ * creates one).
36
+ * - Present and parses to a JSON OBJECT → that object (a `Record`).
37
+ * - Present but not valid JSON, or valid JSON that is NOT an object (an array,
38
+ * `null`, a number, a string) → a hard `CliError` naming the path. The writer
39
+ * must never clobber a file it cannot merge into.
40
+ */
41
+ export declare function readOwenloopSettingsRaw(path: string): Record<string, unknown> | null;
42
+ /** The outcome of a `writeOwenloopHubOrigin` call — the path written and the
43
+ * previous `hubOrigin` value (`undefined` when the key was absent or the file
44
+ * did not exist), so a caller can report an old→new transition. */
45
+ export interface OwenloopWriteResult {
46
+ path: string;
47
+ previous: string | undefined;
48
+ }
49
+ /**
50
+ * Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
51
+ * preserving every other key. Read the existing file (a parse failure is a hard
52
+ * `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
53
+ * directory, and write atomically (temp + rename via `writeFileAtomic`). The
54
+ * file is pretty-printed with a trailing newline. Returns the path and the
55
+ * previous `hubOrigin` (if any).
56
+ */
57
+ export declare function writeOwenloopHubOrigin(env: Record<string, string | undefined>, origin: string): OwenloopWriteResult;
@@ -0,0 +1,84 @@
1
+ /**
2
+ * execution settings file writer — the ONE place the root `owenloop` CLI writes
3
+ * into the execution-side settings file.
4
+ *
5
+ * `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
6
+ * settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
7
+ * NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
8
+ * `owenloop setup` can point `owenloop work` at the hub it just authenticated
9
+ * against.
10
+ *
11
+ * This module writes exactly ONE key — `hubOrigin` — and preserves every other
12
+ * key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
13
+ * `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
14
+ * unknown key). It never writes a secret: nothing secret is in scope here by
15
+ * construction (the hub ORIGIN is public).
16
+ *
17
+ * Corrupt-file policy: a settings file that exists but does not parse as a JSON
18
+ * OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
19
+ * it cannot safely merge into. That mirrors the work settings validator's
20
+ * wording family ("not an object").
21
+ *
22
+ * Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
23
+ * util.ts — no CLI/engine closure.
24
+ */
25
+ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
26
+ import { dirname, join } from 'node:path';
27
+ import { writeFileAtomic } from "./hub.js";
28
+ import { CliError } from "./util.js";
29
+ /**
30
+ * The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
31
+ * set and non-blank) wins over `HOME`, matching owenloop's own resolution and
32
+ * the owenloop credential store's `configDir`. Throws when neither is set.
33
+ */
34
+ export function owenloopSettingsPath(env) {
35
+ const xdg = env.XDG_CONFIG_HOME;
36
+ if (xdg && xdg.trim() !== '')
37
+ return join(xdg, 'owenloop', 'settings.json');
38
+ const home = env.HOME;
39
+ if (home && home.trim() !== '')
40
+ return join(home, '.config', 'owenloop', 'settings.json');
41
+ throw new CliError('cannot locate a config directory for execution settings: set HOME or XDG_CONFIG_HOME');
42
+ }
43
+ /**
44
+ * Read and parse the execution settings file at `path`.
45
+ *
46
+ * - Missing file → `null` (an absent settings file is not an error; the writer
47
+ * creates one).
48
+ * - Present and parses to a JSON OBJECT → that object (a `Record`).
49
+ * - Present but not valid JSON, or valid JSON that is NOT an object (an array,
50
+ * `null`, a number, a string) → a hard `CliError` naming the path. The writer
51
+ * must never clobber a file it cannot merge into.
52
+ */
53
+ export function readOwenloopSettingsRaw(path) {
54
+ if (!existsSync(path))
55
+ return null;
56
+ let parsed;
57
+ try {
58
+ parsed = JSON.parse(readFileSync(path, 'utf8'));
59
+ }
60
+ catch {
61
+ throw new CliError(`execution settings file at ${path} is not valid JSON — fix or remove it before running setup`);
62
+ }
63
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
64
+ throw new CliError(`execution settings file at ${path} is not a JSON object — fix or remove it before running setup`);
65
+ }
66
+ return parsed;
67
+ }
68
+ /**
69
+ * Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
70
+ * preserving every other key. Read the existing file (a parse failure is a hard
71
+ * `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
72
+ * directory, and write atomically (temp + rename via `writeFileAtomic`). The
73
+ * file is pretty-printed with a trailing newline. Returns the path and the
74
+ * previous `hubOrigin` (if any).
75
+ */
76
+ export function writeOwenloopHubOrigin(env, origin) {
77
+ const path = owenloopSettingsPath(env);
78
+ const existing = readOwenloopSettingsRaw(path);
79
+ const previous = existing !== undefined && existing !== null && typeof existing.hubOrigin === 'string' ? existing.hubOrigin : undefined;
80
+ const merged = { ...(existing ?? {}), hubOrigin: origin };
81
+ mkdirSync(dirname(path), { recursive: true });
82
+ writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}\n`);
83
+ return { path, previous };
84
+ }