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/CHANGELOG.md CHANGED
@@ -4,6 +4,57 @@ All notable changes to this project are documented here. The format is based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.5.11](https://github.com/typicalday/owenloop/compare/v0.5.10...v0.5.11) (2026-08-21)
8
+
9
+
10
+ ### Features
11
+
12
+ * **engine:** bind interface calls at instance start ([#263](https://github.com/typicalday/owenloop/issues/263)) ([84dde86](https://github.com/typicalday/owenloop/commit/84dde86be15d0d82a4a8a98137eb257f8a1868e7))
13
+
14
+ ## [0.5.10](https://github.com/typicalday/owenloop/compare/v0.5.9...v0.5.10) (2026-08-21)
15
+
16
+
17
+ ### Features
18
+
19
+ * add graduate skill for ephemeral plan promotion ([#254](https://github.com/typicalday/owenloop/issues/254)) ([3dd4e81](https://github.com/typicalday/owenloop/commit/3dd4e81c7e2a557fd3e61ab29ec71f154cff8590))
20
+ * add hub ephemeral workflow skill ([#230](https://github.com/typicalday/owenloop/issues/230)) ([64b069b](https://github.com/typicalday/owenloop/commit/64b069bc1868f121c302a1f4380446bdd9c683c9))
21
+ * add plan compiler skill ([#251](https://github.com/typicalday/owenloop/issues/251)) ([8a1fb9a](https://github.com/typicalday/owenloop/commit/8a1fb9ac5c658f25eac28647c5f8b7d8ea282575))
22
+ * add safe workflow bundle garbage collection ([#221](https://github.com/typicalday/owenloop/issues/221)) ([2c2ca81](https://github.com/typicalday/owenloop/commit/2c2ca8149fa07c8ca0b6ad647903d43e62af6f12))
23
+ * add x.discovery lint convention ([#218](https://github.com/typicalday/owenloop/issues/218)) ([06ee581](https://github.com/typicalday/owenloop/commit/06ee5810c0ca4bed4c8bb9e61bb367300d071d76))
24
+ * declare and check workflow interface claims ([#252](https://github.com/typicalday/owenloop/issues/252)) ([fae1d83](https://github.com/typicalday/owenloop/commit/fae1d83b527ea41581cb5c6edad98c77929dd79e))
25
+ * **engine:** map authored capabilities to org names before composition ([#213](https://github.com/typicalday/owenloop/issues/213)) ([775813e](https://github.com/typicalday/owenloop/commit/775813e6a8caa874f48dd78beb2311d26bd0239a))
26
+ * expose pending gates to MCP and CLI clients ([#223](https://github.com/typicalday/owenloop/issues/223)) ([38ba485](https://github.com/typicalday/owenloop/commit/38ba4851ba29f1afcb0b02064a47725d63ae1eea))
27
+ * expose search_workflows over MCP ([#231](https://github.com/typicalday/owenloop/issues/231)) ([7223021](https://github.com/typicalday/owenloop/commit/7223021746cc2e7702319d5e3206972556ae5555))
28
+ * expose workflow discovery metadata in defs ([#222](https://github.com/typicalday/owenloop/issues/222)) ([ad8ca3b](https://github.com/typicalday/owenloop/commit/ad8ca3b15cfd2d21a2233a2d2bf4dcb4bae3e786))
29
+ * install outside defs under scoped capabilities ([#214](https://github.com/typicalday/owenloop/issues/214)) ([ae375cd](https://github.com/typicalday/owenloop/commit/ae375cd2d442336ddd254bff5899fc50216a55dc))
30
+ * **mcp:** add chief-of-staff charter ([#219](https://github.com/typicalday/owenloop/issues/219)) ([cc3f02f](https://github.com/typicalday/owenloop/commit/cc3f02f6747ed08cc0a36d9dcd32d503574d2f15))
31
+ * support oneOf, anyOf, and uniqueItems in interface compatibility ([#256](https://github.com/typicalday/owenloop/issues/256)) ([fb6710b](https://github.com/typicalday/owenloop/commit/fb6710bc2f65e0ca8078716247a3c58d48386d8b))
32
+
33
+
34
+ ### Bug Fixes
35
+
36
+ * a claim released for capacity re-arms the next sweep ([#217](https://github.com/typicalday/owenloop/issues/217)) ([f09e93b](https://github.com/typicalday/owenloop/commit/f09e93b57eab64bbbc93fa4e9be4714fede86552))
37
+ * a returned lease is not a run for budget or cadence ([#215](https://github.com/typicalday/owenloop/issues/215)) ([e79fcc5](https://github.com/typicalday/owenloop/commit/e79fcc5ca325ce62a18f0558125dc0cf8edf5083))
38
+ * calls joins wait for whole-child completion ([#239](https://github.com/typicalday/owenloop/issues/239)) ([934215d](https://github.com/typicalday/owenloop/commit/934215d69381bb1fc189be1c424fb73d09070b3d))
39
+ * classify future idle waits as stalls, not deadlocks ([#250](https://github.com/typicalday/owenloop/issues/250)) ([1efec61](https://github.com/typicalday/owenloop/commit/1efec617ca27d24e8ceaab45c879f8677480e3cd))
40
+ * **cli:** report auth rate limits accurately ([#228](https://github.com/typicalday/owenloop/issues/228)) ([44da220](https://github.com/typicalday/owenloop/commit/44da2202b026deb49b69a2cc17bba5812180f12e))
41
+ * **cli:** route reject and provide to hub ([#220](https://github.com/typicalday/owenloop/issues/220)) ([1697b8d](https://github.com/typicalday/owenloop/commit/1697b8d17ea549516fb0f326de55aab94966d594))
42
+ * damp repeated capacity reclaims in Shift ([#243](https://github.com/typicalday/owenloop/issues/243)) ([c20003a](https://github.com/typicalday/owenloop/commit/c20003a179c71763043961d1c583da3cbe0865a0))
43
+ * drain CLI output before exit ([#235](https://github.com/typicalday/owenloop/issues/235)) ([eecf853](https://github.com/typicalday/owenloop/commit/eecf85327b631eca5512bc87d522db060b603ba7))
44
+ * **engine:** re-stamp owed version target when a reject re-arms a claim ([#211](https://github.com/typicalday/owenloop/issues/211)) ([ccf956c](https://github.com/typicalday/owenloop/commit/ccf956c02ed2cdec2659861724c3a235be99a6b8))
45
+ * keep a source schema's own constraints when checking its union branches ([#260](https://github.com/typicalday/owenloop/issues/260)) ([4803906](https://github.com/typicalday/owenloop/commit/4803906d7f41b61b8f617b3a40da3e6f6d6227e4))
46
+ * **mcp:** expose hub passthrough fields ([#227](https://github.com/typicalday/owenloop/issues/227)) ([32548f1](https://github.com/typicalday/owenloop/commit/32548f1cf2747f6599fd1e00a2cc859a8da64b53))
47
+ * **mcp:** put the catalog rule first in the chief-of-staff charter ([#233](https://github.com/typicalday/owenloop/issues/233)) ([e5ff766](https://github.com/typicalday/owenloop/commit/e5ff76656041bfe4c66785e5d1ce0d573114a020))
48
+ * model all collection member retractions ([#234](https://github.com/typicalday/owenloop/issues/234)) ([9b87542](https://github.com/typicalday/owenloop/commit/9b875423dd56f4153c386b75e3eda0861933ab15))
49
+ * read the capability mappings the hub actually returns ([#216](https://github.com/typicalday/owenloop/issues/216)) ([f416396](https://github.com/typicalday/owenloop/commit/f416396039baefeb6ca86a1c063ae53b28a6c2fa))
50
+ * report collection search cap usage ([#245](https://github.com/typicalday/owenloop/issues/245)) ([de4925c](https://github.com/typicalday/owenloop/commit/de4925cd0c72c8a4193bd3c8eee2a4507ba9f6f4))
51
+ * retry rate-limited exec receipt submissions ([#225](https://github.com/typicalday/owenloop/issues/225)) ([c5ce4bb](https://github.com/typicalday/owenloop/commit/c5ce4bb505c83ea420b3549f928ea51891d76eac))
52
+ * revive exclusive-group siblings when the winner is un-greened ([#253](https://github.com/typicalday/owenloop/issues/253)) ([66eab0a](https://github.com/typicalday/owenloop/commit/66eab0ad2805f09d0196673d968a54203a637222))
53
+ * settle a calls output when its gate input is skipped ([#257](https://github.com/typicalday/owenloop/issues/257)) ([c773a4e](https://github.com/typicalday/owenloop/commit/c773a4ef8cd6b012b007d8134a80ca282ba9bf9e))
54
+ * validate calls edges in lint and check ([#240](https://github.com/typicalday/owenloop/issues/240)) ([5741261](https://github.com/typicalday/owenloop/commit/5741261c19c7f694c2f25a919abd2acf2af13038))
55
+ * validate hub workflow IDs locally ([#244](https://github.com/typicalday/owenloop/issues/244)) ([da5e91f](https://github.com/typicalday/owenloop/commit/da5e91f8072f500d26f752aa4060beea70b6b0fb))
56
+ * **work:** surface and resolve command-step orders whose bundle is missing from the store ([#261](https://github.com/typicalday/owenloop/issues/261)) ([9dbd4f0](https://github.com/typicalday/owenloop/commit/9dbd4f03b1411b18c4f38e36a7da00cd1fc38b90))
57
+
7
58
  ## [0.5.9](https://github.com/typicalday/owenloop/compare/v0.5.8...v0.5.9) (2026-08-19)
8
59
 
9
60
 
package/README.md CHANGED
@@ -307,6 +307,38 @@ The bundle route derives `<home>` from the first non-blank caller-injected
307
307
  recovery-marker directory. A bundle install refuses when neither variable is
308
308
  supplied rather than falling back to the process user's ambient home.
309
309
 
310
+ Normal definition discovery no longer floods stderr for expected bundle
311
+ history. It emits at most one `note: N superseded bundle versions hidden;
312
+ --verbose to list them`; the global `--verbose` flag restores every detailed
313
+ superseded-version notice. The actionable `has no selectable version` warning
314
+ for competing non-SemVer versions is never hidden.
315
+
316
+ Store history can be bounded safely with a dry run first:
317
+
318
+ ```sh
319
+ owenloop bundle gc --keep 2 # project store, report only
320
+ owenloop bundle gc --keep 2 --yes # recompute under lock and apply
321
+ owenloop bundle gc --global # global store, report only
322
+ ```
323
+
324
+ The default keep count is 2 (current plus one rollback version). GC preserves
325
+ selected versions, explicit pins, retained local instance snapshots, transitive
326
+ bundle locks from every retained coordinate in either root, exact versioned
327
+ calls from retained legacy snapshots and current project/add definitions, and
328
+ project-index fallback into the global store. Reachability is coordinate- and
329
+ root-aware, so
330
+ an intact non-target copy does not keep a redundant target history beyond
331
+ `--keep`. It never contacts the hub; `--yes` is the only destructive switch
332
+ and only the target bundle index/object tree is changed. Applied GC takes both
333
+ roots' writer locks (creating only coordination state at a known missing
334
+ counterpart root when necessary). Project GC also takes the legacy GitHub-add
335
+ lock and recovers its journal before clearing their shared staging tree; global
336
+ GC uses that lock as a read barrier without recovering or otherwise mutating the
337
+ project tree.
338
+ CAS-backed snapshot writers share the store locks, and bundle installs
339
+ revalidate exact manifest locks before commit, so stale definitions or callers
340
+ cannot be pinned during or immediately after collection.
341
+
310
342
  Bundle installs fail closed without their two required adapters (bundle
311
343
  ingestion and pre-commit verification). The default CLI binds the real
312
344
  bundle ingestor, so a `.wnlp` produced by `packBundle` reaches the normal
@@ -356,42 +388,41 @@ looks like:
356
388
  as scratch discipline rather than standing infrastructure.
357
389
 
358
390
  The engine doesn't know or care which of these is ticking it — an order is an
359
- order. For Claude Code specifically, three shipped skills implement these
360
- patterns ready-made:
361
-
362
- - [`owenloop-conduct`](skills/owenloop-conduct/SKILL.md) — drive an existing
363
- workflow instance to done: tick, dispatch each order to a fresh subagent,
364
- report honestly.
365
- - [`owenloop-author`](skills/owenloop-author/SKILL.md) — turn a plain-English
366
- goal into a validated workflow def, interactively, then drive it.
367
- - [`owenloop-ephemeral`](skills/owenloop-ephemeral/SKILL.md) — author and
368
- drive a throwaway workflow to structure an agent's own mid-task work, then
369
- delete it.
391
+ order. The Owenloop Claude Code and Codex plugins provide six hub-native skills:
392
+
393
+ - [`conduct`](plugins/_skills/conduct/SKILL.md) — supervise one existing workflow
394
+ through a scoped Shift, check its status, and relay human gates.
395
+ - [`author`](plugins/_skills/author/SKILL.md) — interview a human, draft a workflow,
396
+ validate it through `create_workflow`, present it for approval, and offer
397
+ `start_run`. Use `conduct` or `shift` to supervise the resulting run.
398
+ - [`ephemeral`](plugins/_skills/ephemeral/SKILL.md) — structure the caller's own
399
+ one-off work with an ephemeral workflow.
400
+ - [`graduate`](plugins/_skills/graduate/SKILL.md) — turn evidence from a
401
+ completed ephemeral composite into a reusable, policy-conformant library candidate.
402
+ - [`plan`](plugins/_skills/plan/SKILL.md) — compile novel multi-domain work into
403
+ a checked, approval-gated ephemeral composite that delegates library playbooks.
404
+ - [`shift`](plugins/_skills/shift/SKILL.md) — attend a crew's ongoing workflow
405
+ workload through the blocking Shift loop and relay human gates.
406
+
407
+ Put the `owenloop` CLI on `PATH` and run `owenloop setup`; the setup flow converges
408
+ the bundled Claude Code and Codex plugins on that same CLI and hub connection.
370
409
 
371
410
  ---
372
411
 
373
412
  ## Quick start
374
413
 
375
- Install the owenloop skills for whatever Prime Agent you use — Claude Code, Codex,
376
- Cursor, and most others:
377
-
378
- ```sh
379
- npx skills add typicalday/owenloop
380
- ```
381
-
382
- Then ask your Prime Agent for what you want:
414
+ Put the `owenloop` CLI (Node ≥ 22.13) on `PATH` and run `owenloop setup` once. Then
415
+ ask your Prime Agent for what you want:
383
416
 
384
- > Use owenloop-author to build me a workflow that researches a topic, writes
417
+ > Use author to build me a workflow that researches a topic, writes
385
418
  > a report, and doesn't accept it until an independent reviewer signs off —
386
419
  > then run it on "tidepools".
387
420
 
388
- The skill interviews you for anything missing, writes and validates the YAML
389
- definition, then conducts the instance to done — dispatching each order to a
390
- fresh subagent, relaying knock-backs, and escalating stalls to you. Already
391
- have a def? *"Conduct the report workflow"* hands it to
392
- [`owenloop-conduct`](skills/owenloop-conduct/SKILL.md). The engine itself is the
393
- `owenloop` CLI (Node ≥ 22.13 required). Install the package so `owenloop` is on
394
- `PATH`; the shipped Claude Code and Codex plugins launch that same command as
421
+ The `author` skill interviews you for anything missing, writes and validates the
422
+ YAML definition, and presents the process for approval before offering to start it.
423
+ Already have a def? *"Conduct the report workflow"* hands it to
424
+ [`conduct`](plugins/_skills/conduct/SKILL.md). The shipped Claude Code and Codex
425
+ plugins launch the same `owenloop` command as
395
426
  `owenloop mcp`, rather than using a separate npx-pinned server. The plugins
396
427
  check the installed CLI/plugin version pair at session start when their hooks
397
428
  are enabled, and the MCP server reports a readable mismatch error on tool calls; run `owenloop setup` when the versions differ. For one-off shell
@@ -417,8 +448,10 @@ owenloop bundle digest ./report-1.2.0.wnlp
417
448
  owenloop bundle unpack ./report-1.2.0.wnlp ./unpacked-report
418
449
  ```
419
450
 
420
- Bundle commands are filesystem-only: they do not open or create the local
421
- `.owenloop/state.db` and do not contact a remote service. Packing never edits
451
+ The bundle format commands (`pack`, `inspect`, `digest`, and `unpack`) are
452
+ filesystem-only: they do not open or create the local `.owenloop/state.db` and
453
+ do not contact a remote service. `bundle gc` is intentionally store- and
454
+ local-snapshot-aware, but likewise never contacts the hub. Packing never edits
422
455
  the source manifest. Inspection and unpacking reject unsafe paths, symlinks,
423
456
  unsupported archive entry types, malformed canonical headers, duplicate files,
424
457
  invalid manifests, workflow/manifest name mismatches, missing lock entries, and
@@ -481,7 +514,11 @@ against the hub before it's ever stored), `owenloop connect` binds the project
481
514
  to a hub, and `owenloop push` publishes your defs. Use `owenloop push --bundle
482
515
  <bundle.wnlp>` after `owenloop publish` when execution must be pinned to the
483
516
  exact signed bundle digest; plain YAML pushes remain idempotent against the
484
- hub's own def hashes. `owenloop agent new
517
+ hub's own def hashes. To publish an *outside* repo's defs, `owenloop install
518
+ <owner>/<repo>` scopes every capability they author to `<defName>.<capability>`
519
+ unless you deliberately map it onto a name your crews already serve — see
520
+ [`install`](docs/cli.md#install--publish-an-outside-repos-defs-under-scoped-capabilities).
521
+ `owenloop agent new
485
522
  <name>` mints a Scoped Identity on the hub and stores its token in slot
486
523
  `agent:<name>` without ever printing it. See the
487
524
  [Hub](docs/cli.md#hub-login--connect--push--logout) section in `docs/cli.md`.
@@ -719,13 +756,16 @@ can NEVER fire regardless of search bounds are **structurally dead** — a real
719
756
  defect, reported nonzero exit — while steps that CAN fire but the bounded search
720
757
  just didn't reach are **unreached within bounds** — informational only, exit 0.
721
758
  It also splits every reachable non-done, no-moves state into exactly one of two
722
- buckets: a **stall state** — the state's only blocker is a frozen/stalled debt
723
- (maxAttempts / maxSchemaFailures / held); recomputing eligibility with the freeze
724
- lifted (a human `retry` = unlimited attempts) shows a producer would re-arm and the
725
- line could move — this is an EXPECTED, by-design human-escalation brake and never
726
- fails the check — versus a **true deadlock** — the same recompute STILL yields no
727
- moves, a genuine structural dead-end, which fails the check nonzero when the search
728
- is exhaustive. See [`docs/design.md` §25](docs/design.md#25-the-model-checker-owenloop-check--scope)
759
+ buckets: a **stall state** — the state is blocked only by a frozen/stalled debt
760
+ (maxAttempts / maxSchemaFailures / held) *or* an idle trigger waiting for its
761
+ threshold; recomputing eligibility with the freeze lifted (a human `retry` =
762
+ unlimited attempts) and with eventual idle time shows a move would become
763
+ available. This is an EXPECTED, by-design human-escalation brake or future wait
764
+ and never fails the check. The classifier does not add future idle transitions to
765
+ the timeless reachability search, so an idle-only completion path can still report
766
+ `completable: false`. A **true deadlock** is a state where the same recompute STILL
767
+ yields no moves, a genuine structural dead-end which fails the check nonzero when
768
+ the search is exhaustive. See [`docs/design.md` §25](docs/design.md#25-the-model-checker-owenloop-check--scope)
729
769
  for the full breakdown.
730
770
 
731
771
  By default, `seedOwed` inputs are assumed provided (modeling the operator's `provide`
package/bin/owenloop.mjs CHANGED
@@ -51,5 +51,20 @@ if (gatePath !== undefined && gatePath !== '') {
51
51
  delete process.env.OWENLOOP_START_GATE;
52
52
  }
53
53
 
54
+ function handleStreamError(error) {
55
+ if (error?.code === 'EPIPE') return;
56
+ throw error;
57
+ }
58
+
59
+ function drain(stream) {
60
+ return new Promise((resolve) => stream.write('', resolve));
61
+ }
62
+
63
+ process.stdout.on('error', handleStreamError);
64
+ process.stderr.on('error', handleStreamError);
65
+
54
66
  const { mainAsync } = await import('../dist/src/cli.js');
55
- mainAsync(process.argv.slice(2)).then((code) => process.exit(code));
67
+ mainAsync(process.argv.slice(2)).then(async (code) => {
68
+ await Promise.all([drain(process.stdout), drain(process.stderr)]);
69
+ process.exit(code);
70
+ });
@@ -395,6 +395,13 @@ export function createAgentRunLoop(opts) {
395
395
  case 'progress':
396
396
  opts.err(`owenloop work agent-run: ${e.text}`);
397
397
  return;
398
+ case 'assistant_response':
399
+ // The eval uses this typed event as report evidence. Regular work must
400
+ // not persist this additional unbounded copy merely because an adapter
401
+ // surfaced it. Existing adapter-owned, capped progress telemetry remains
402
+ // unchanged and is still logged by the `progress` case above.
403
+ opts.err('owenloop work agent-run: final response evidence received (redacted)');
404
+ return;
398
405
  case 'needs_input':
399
406
  opts.err(`owenloop work agent-run: WARNING the step agent asked for input and this contract has no reply channel — ${e.question}`);
400
407
  return;
@@ -0,0 +1,21 @@
1
+ import type { MissingObjectHandler } from '../../../../src/store/index.ts';
2
+ export interface HubBundleRecoveryOptions {
3
+ /** Authenticated hub origin; a trailing slash is accepted. */
4
+ origin: string;
5
+ /** Scoped worker/shift bearer. It is sent only in the Authorization header. */
6
+ token: string;
7
+ /** Injected home, used for the global store and its recovery marker directory. */
8
+ home: string;
9
+ /** Current project root, used by install's exact-lock validation. */
10
+ projectRoot: string;
11
+ /** Environment used by the pre-commit trust policy. */
12
+ env: Record<string, string | undefined>;
13
+ /** Diagnostic sink for warn policy decisions. */
14
+ warn?: (line: string) => void;
15
+ /** Injectable transport for hermetic recovery tests. */
16
+ fetchImpl?: typeof fetch;
17
+ /** Per-request deadline; production uses the fixed 30-second default. */
18
+ timeoutMs?: number;
19
+ }
20
+ /** Build the existing store's one-shot `onMissing` hook for a scoped worker. */
21
+ export declare function createHubBundleRecoveryHandler(args: HubBundleRecoveryOptions): MissingObjectHandler;
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Authenticated, one-shot recovery of a workflow bundle missing from both
3
+ * local stores. This is deliberately an internal store-miss adapter, not a
4
+ * user-facing pull command: it obtains raw canonical bundle bytes and the
5
+ * evidence that the normal install trust boundary must validate.
6
+ */
7
+ import { defaultRecoveryMarkerDir } from "../../../../src/install.js";
8
+ import { readBodyBounded } from "../../../../src/credentials.js";
9
+ import { createBundleIngestor, createPreCommitVerifier, defDigest, globalStoreRoot, installWorkflowBundle, workflowStoreStatePaths, } from "../../../../src/store/index.js";
10
+ const BUNDLE_MAX_BYTES = 25_000_000;
11
+ const EVIDENCE_MAX_BYTES = 64 * 1024;
12
+ const RECOVERY_TIMEOUT_MS = 30_000;
13
+ function originBase(origin) {
14
+ const trimmed = origin.replace(/\/+$/, '');
15
+ if (trimmed === '')
16
+ throw new Error('cannot recover workflow bundle: hub origin is empty');
17
+ return trimmed;
18
+ }
19
+ function routeFor(origin, resource, digest) {
20
+ return `${originBase(origin)}/api/${resource}/${encodeURIComponent(digest)}`;
21
+ }
22
+ function failure(route, detail) {
23
+ // This deliberately names only a route and status/classification. Never pass
24
+ // through fetch request options or headers: the bearer must not become error
25
+ // text or a shift log record.
26
+ return new Error(`workflow bundle recovery failed for ${route}: ${detail}`);
27
+ }
28
+ async function request(args, route) {
29
+ const timeoutMs = args.timeoutMs ?? RECOVERY_TIMEOUT_MS;
30
+ try {
31
+ return await (args.fetchImpl ?? globalThis.fetch)(route, {
32
+ method: 'GET',
33
+ headers: { Authorization: `Bearer ${args.token}` },
34
+ signal: AbortSignal.timeout(timeoutMs),
35
+ redirect: 'error',
36
+ });
37
+ }
38
+ catch (error) {
39
+ const name = error instanceof Error ? error.name : 'request error';
40
+ const detail = name === 'TimeoutError' || name === 'AbortError'
41
+ ? `timed out after ${timeoutMs / 1_000}s`
42
+ : 'request failed';
43
+ throw failure(route, detail);
44
+ }
45
+ }
46
+ async function bytesFrom(response, route, cap) {
47
+ try {
48
+ return await readBodyBounded(response, cap, route);
49
+ }
50
+ catch (error) {
51
+ const detail = error instanceof Error && /cap/u.test(error.message)
52
+ ? `response exceeds the ${cap}-byte cap`
53
+ : 'could not read response body';
54
+ throw failure(route, detail);
55
+ }
56
+ }
57
+ /** Build the existing store's one-shot `onMissing` hook for a scoped worker. */
58
+ export function createHubBundleRecoveryHandler(args) {
59
+ return {
60
+ async onMissing(requestedDigest) {
61
+ const digest = defDigest(requestedDigest);
62
+ const bundleRoute = routeFor(args.origin, 'bundles', digest);
63
+ const bundleResponse = await request(args, bundleRoute);
64
+ if (!bundleResponse.ok)
65
+ throw failure(bundleRoute, `hub returned HTTP ${bundleResponse.status}`);
66
+ const bytes = await bytesFrom(bundleResponse, bundleRoute, BUNDLE_MAX_BYTES);
67
+ const publicationRoute = routeFor(args.origin, 'publications', digest);
68
+ const publicationResponse = await request(args, publicationRoute);
69
+ if (!publicationResponse.ok) {
70
+ throw failure(publicationRoute, `hub returned HTTP ${publicationResponse.status}`);
71
+ }
72
+ const state = publicationResponse.headers.get('x-owenloop-publication-state');
73
+ if (state !== 'signed' && state !== 'unsigned') {
74
+ throw failure(publicationRoute, 'missing or invalid X-Owenloop-Publication-State header');
75
+ }
76
+ const publicationBytes = await bytesFrom(publicationResponse, publicationRoute, EVIDENCE_MAX_BYTES);
77
+ if (state === 'signed' && publicationBytes.byteLength === 0) {
78
+ throw failure(publicationRoute, 'signed publication evidence is empty');
79
+ }
80
+ const originRoute = routeFor(args.origin, 'origins', digest);
81
+ const originResponse = await request(args, originRoute);
82
+ let originDsseBytes;
83
+ if (originResponse.status === 404) {
84
+ await originResponse.body?.cancel().catch(() => { });
85
+ }
86
+ else {
87
+ if (!originResponse.ok)
88
+ throw failure(originRoute, `hub returned HTTP ${originResponse.status}`);
89
+ originDsseBytes = await bytesFrom(originResponse, originRoute, EVIDENCE_MAX_BYTES);
90
+ if (originDsseBytes.byteLength === 0)
91
+ throw failure(originRoute, 'origin evidence is empty');
92
+ }
93
+ const globalRoot = globalStoreRoot(args.home);
94
+ const statePaths = workflowStoreStatePaths(globalRoot);
95
+ await installWorkflowBundle({
96
+ bytes,
97
+ source: { kind: 'url', url: bundleRoute },
98
+ root: globalRoot,
99
+ level: 'global',
100
+ projectRoot: args.projectRoot,
101
+ globalRoot,
102
+ lockPath: statePaths.lockPath,
103
+ journalPath: statePaths.journalPath,
104
+ recoveryMarkerDir: defaultRecoveryMarkerDir(args.home),
105
+ ingestor: createBundleIngestor(),
106
+ verifier: createPreCommitVerifier({ env: args.env, ...(args.warn !== undefined ? { warn: args.warn } : {}) }),
107
+ expectedDigest: digest,
108
+ verificationEvidence: {
109
+ publication: state === 'signed'
110
+ ? { state, dsseBytes: publicationBytes }
111
+ : { state, markerBytes: publicationBytes },
112
+ ...(originDsseBytes !== undefined ? { originDsseBytes } : {}),
113
+ },
114
+ });
115
+ return 'retry';
116
+ },
117
+ };
118
+ }
@@ -7,7 +7,7 @@
7
7
  * authoritative. The command resolver returns the exact authored command and
8
8
  * does not perform placeholder substitution.
9
9
  */
10
- import type { BundleIngestor, StoreInstructionSource } from '../../../../src/store/index.ts';
10
+ import type { BundleIngestor, MissingObjectHandler, StoreInstructionSource } from '../../../../src/store/index.ts';
11
11
  import type { StepDef, WorkflowDef } from '../../../../src/types.ts';
12
12
  import type { DefPolicy, DefVerdict } from '../../../../src/crypto/verify-publication.ts';
13
13
  import type { OriginRules } from '../../../../src/crypto/origin-rules.ts';
@@ -63,6 +63,8 @@ export interface StoreInstructionResolverOptions {
63
63
  globalRoot: string;
64
64
  verifier: BundleIngestor;
65
65
  source?: StoreInstructionSource;
66
+ /** Optional one-shot authenticated recovery hook for a true store miss. */
67
+ onMissing?: MissingObjectHandler;
66
68
  /** Optional execution-time publication verifier. Omitted means publication trust is unverifiable and command orders refuse. */
67
69
  definitionVerifier?: DefinitionVerifier;
68
70
  /** Optional execution-time origin verifier. */
@@ -88,6 +90,7 @@ export declare function createDefaultStoreInstructionResolver(args: {
88
90
  cwd: string;
89
91
  env: Record<string, string | undefined>;
90
92
  verifier?: BundleIngestor;
93
+ onMissing?: MissingObjectHandler;
91
94
  definitionVerifier?: DefinitionVerifier;
92
95
  originVerifier?: OriginVerifier;
93
96
  consumedVerifier?: ConsumedVerifier;
@@ -44,6 +44,7 @@ export function createStoreInstructionResolver(options) {
44
44
  projectRoot: options.projectRoot,
45
45
  globalRoot: options.globalRoot,
46
46
  verifier: options.verifier,
47
+ ...(options.onMissing !== undefined ? { onMissing: options.onMissing } : {}),
47
48
  });
48
49
  const env = options.env ?? {};
49
50
  let mergedPolicies;
@@ -304,12 +305,14 @@ export function createDefaultStoreInstructionResolver(args) {
304
305
  projectRoot,
305
306
  globalRoot,
306
307
  verifier,
308
+ ...(args.onMissing !== undefined ? { onMissing: args.onMissing } : {}),
307
309
  });
308
310
  return createStoreInstructionResolver({
309
311
  projectRoot,
310
312
  globalRoot,
311
313
  verifier,
312
314
  source,
315
+ ...(args.onMissing !== undefined ? { onMissing: args.onMissing } : {}),
313
316
  definitionVerifier: args.definitionVerifier ?? createExecutionDefinitionVerifier({ env: args.env }),
314
317
  originVerifier: args.originVerifier ?? createExecutionOriginVerifier({ env: args.env }),
315
318
  ...(args.consumedVerifier !== undefined ? { consumedVerifier: args.consumedVerifier } : {}),
@@ -1,5 +1,5 @@
1
1
  import type { HubClient } from '../hub/client.ts';
2
- import type { ContactHolder } from '../hub/types.ts';
2
+ import { type ContactHolder } from '../hub/types.ts';
3
3
  import type { CommandRunner } from './runner.ts';
4
4
  import type { InstructionResolver } from './instructions.ts';
5
5
  import { type SubmissionKeyManager } from '../submit-proof.ts';
@@ -46,11 +46,17 @@ import { tmpdir } from 'node:os';
46
46
  import { join, resolve } from 'node:path';
47
47
  import { isWorkdirAllowed } from "../agent/workdir.js";
48
48
  import { createLeaseLoop } from "../lease/loop.js";
49
+ import { HubError } from "../hub/types.js";
49
50
  import { parsePayloadLine } from "./payload.js";
50
51
  import { buildReceipt } from "./receipt.js";
51
52
  import { buildSubmitProof } from "../submit-proof.js";
52
53
  /** sha256 of the empty byte string — the hash for a run with no captured output. */
53
54
  const EMPTY_HASH = createHash('sha256').digest('hex');
55
+ /** Submit retries are intentionally narrow: 429 is known not to reach the verb. */
56
+ const SUBMIT_MAX_ATTEMPTS = 3;
57
+ const SUBMIT_RETRY_WINDOW_MS = 30_000;
58
+ const SUBMIT_FALLBACK_DELAYS_MS = [5_000, 10_000];
59
+ const SUBMIT_ERROR_DETAIL_MAX_CHARS = 160;
54
60
  /**
55
61
  * The largest serialized `consumes` payload delivered inline in
56
62
  * `OWENLOOP_CONSUMES`; anything strictly larger goes to a file named by
@@ -71,6 +77,22 @@ export const CONSUMES_INLINE_MAX_BYTES = 65_536;
71
77
  function errMsg(e) {
72
78
  return e instanceof Error ? e.message : String(e);
73
79
  }
80
+ /**
81
+ * Keep edge response bodies out of the run log without changing HubError's
82
+ * transport contract for other callers. In particular, Cloudflare's HTML 1015
83
+ * page contributes no useful diagnosis beyond the 429 classification.
84
+ */
85
+ function formatSubmitError(e) {
86
+ if (!(e instanceof HubError))
87
+ return errMsg(e);
88
+ if (e.status === 429)
89
+ return 'HTTP 429 (rate limited)';
90
+ const detail = e.message.replace(/\s+/g, ' ').trim();
91
+ const boundedDetail = detail.length <= SUBMIT_ERROR_DETAIL_MAX_CHARS
92
+ ? detail
93
+ : `${detail.slice(0, SUBMIT_ERROR_DETAIL_MAX_CHARS - 1)}…`;
94
+ return `HTTP ${e.status}${e.code === undefined ? '' : ` (${e.code})`}${boundedDetail === '' ? '' : `: ${boundedDetail}`}`;
95
+ }
74
96
  /**
75
97
  * The one predicate that decides both how child output is logged and whether
76
98
  * its receipt may be submitted.
@@ -299,6 +321,24 @@ export function createExecLoop(opts) {
299
321
  return 'hub-unreachable';
300
322
  return 'lease-lost';
301
323
  }
324
+ /**
325
+ * Wait for a server-approved submit retry without continuing after the
326
+ * concurrent lease loop has made the claim terminal.
327
+ */
328
+ async function waitForSubmitRetry(ms) {
329
+ const settled = await Promise.race([
330
+ opts.sleep(ms).then(() => ({ kind: 'slept' })),
331
+ leasePromise.then((outcome) => ({ kind: 'lease', outcome })),
332
+ ]);
333
+ return settled.kind === 'lease' ? settled.outcome : undefined;
334
+ }
335
+ /** Stop a failed submit exactly as the pre-retry implementation did. */
336
+ async function failSubmit(path, error) {
337
+ opts.err(`owenloop work exec: submit to ${path} failed: ${formatSubmitError(error)}`);
338
+ lease.stop('submit-failed'); // targeted release (idempotent) — best effort
339
+ await leasePromise;
340
+ return 'submit-failed';
341
+ }
302
342
  /** Deliver one reject verb and settle the lease after the response arrives. */
303
343
  async function issueReject(path, text, successOutcome) {
304
344
  try {
@@ -599,9 +639,8 @@ export function createExecLoop(opts) {
599
639
  if (!commandSucceeded(result))
600
640
  return escalateCommandFailure(receipt, order, resolvedCommand);
601
641
  for (const owe of order.owes) {
602
- let res;
642
+ let proof;
603
643
  try {
604
- let proof;
605
644
  if (opts.origin !== undefined) {
606
645
  // The immutable order can authorize a judge proof only when the owed
607
646
  // path is the fingerprinted judged artifact. Producer command receipts
@@ -618,21 +657,60 @@ export function createExecLoop(opts) {
618
657
  ...(opts.sshProcess !== undefined ? { sshProcess: opts.sshProcess } : {}),
619
658
  });
620
659
  }
621
- res = await hub.submit({
622
- workflow,
623
- run: runId,
624
- path: owe.path,
625
- value: receipt,
626
- ...(proof !== undefined ? { proof } : {}),
627
- holder: opts.holder,
628
- });
629
660
  }
630
661
  catch (e) {
631
- opts.err(`owenloop work exec: submit to ${owe.path} failed: ${errMsg(e)}`);
632
- lease.stop('submit-failed'); // targeted release (idempotent) — best effort
633
- await leasePromise;
634
- return 'submit-failed';
662
+ return failSubmit(owe.path, e);
663
+ }
664
+ // One logical receipt gets one request object. A retry replays these same
665
+ // fields (including the proof) rather than producing a fresh signature.
666
+ const submitRequest = Object.freeze({
667
+ workflow,
668
+ run: runId,
669
+ path: owe.path,
670
+ value: receipt,
671
+ ...(proof !== undefined ? { proof } : {}),
672
+ holder: opts.holder,
673
+ });
674
+ const retryStartedAt = opts.now();
675
+ let res;
676
+ for (let attempt = 1; attempt <= SUBMIT_MAX_ATTEMPTS; attempt++) {
677
+ try {
678
+ res = await hub.submit(submitRequest);
679
+ break;
680
+ }
681
+ catch (e) {
682
+ const retryable = e instanceof HubError && e.status === 429;
683
+ if (!retryable || attempt === SUBMIT_MAX_ATTEMPTS)
684
+ return failSubmit(owe.path, e);
685
+ const delay = e.retryAfterMs ?? SUBMIT_FALLBACK_DELAYS_MS[attempt - 1];
686
+ const remaining = SUBMIT_RETRY_WINDOW_MS - (opts.now() - retryStartedAt);
687
+ // Never retry ahead of a server delay, nor hold this receipt beyond
688
+ // the bounded retry window just because a malformed/large header said to.
689
+ if (delay > remaining)
690
+ return failSubmit(owe.path, e);
691
+ opts.err(`owenloop work exec: submit to ${owe.path} failed: ${formatSubmitError(e)}; ` +
692
+ `retrying attempt ${attempt + 1}/${SUBMIT_MAX_ATTEMPTS} after ${delay}ms`);
693
+ const leaseOutcome = await waitForSubmitRetry(delay);
694
+ // stop() marks this worker as signalled before its best-effort release
695
+ // finishes. The retry sleep can therefore win this race while the
696
+ // release is still in flight; do not issue a new submit in that gap.
697
+ if (signalled) {
698
+ opts.err(`owenloop work exec: signalled while waiting to retry submit to ${owe.path} — no further receipt sent`);
699
+ // The role exits the process as soon as this loop resolves. Wait for
700
+ // lease finalBreath so that exit cannot abandon its targeted release.
701
+ await leasePromise;
702
+ return 'killed';
703
+ }
704
+ if (leaseOutcome !== undefined) {
705
+ opts.err(`owenloop work exec: lease ${leaseOutcome} while waiting to retry submit to ${owe.path} — no further receipt sent`);
706
+ return mapLeaseDuringRun(leaseOutcome);
707
+ }
708
+ }
635
709
  }
710
+ // Each non-success attempt returns from this function, so this only
711
+ // satisfies TypeScript's control-flow analysis after the bounded loop.
712
+ if (res === undefined)
713
+ return failSubmit(owe.path, new Error('submit retry ended without a response'));
636
714
  const outcome = res.outcome;
637
715
  if (outcome !== 'green' && outcome !== 'submitted') {
638
716
  opts.err(`owenloop work exec: submit to ${owe.path} rejected (${outcome ?? 'unknown'}): ${res.text}`);