owenloop 0.5.9 → 0.5.10

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 (83) hide show
  1. package/CHANGELOG.md +44 -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 +1196 -164
  28. package/dist/src/defs.d.ts +32 -1
  29. package/dist/src/defs.js +391 -79
  30. package/dist/src/engine.d.ts +62 -19
  31. package/dist/src/engine.js +180 -70
  32. package/dist/src/hub.d.ts +77 -0
  33. package/dist/src/hub.js +162 -0
  34. package/dist/src/implements.d.ts +56 -0
  35. package/dist/src/implements.js +790 -0
  36. package/dist/src/index.d.ts +8 -6
  37. package/dist/src/index.js +4 -3
  38. package/dist/src/mcp/serve.js +254 -45
  39. package/dist/src/mcp/server.d.ts +10 -7
  40. package/dist/src/mcp/server.js +53 -8
  41. package/dist/src/model.d.ts +46 -10
  42. package/dist/src/model.js +220 -74
  43. package/dist/src/store/def-source.d.ts +19 -0
  44. package/dist/src/store/def-source.js +87 -17
  45. package/dist/src/store/gc-recovery.d.ts +46 -0
  46. package/dist/src/store/gc-recovery.js +258 -0
  47. package/dist/src/store/gc.d.ts +94 -0
  48. package/dist/src/store/gc.js +562 -0
  49. package/dist/src/store/index.d.ts +3 -1
  50. package/dist/src/store/index.js +2 -0
  51. package/dist/src/store/install.d.ts +34 -5
  52. package/dist/src/store/install.js +73 -11
  53. package/dist/src/store/pre-commit-verifier.js +42 -2
  54. package/dist/src/store/snapshot-guard.d.ts +18 -0
  55. package/dist/src/store/snapshot-guard.js +94 -0
  56. package/dist/src/store.d.ts +64 -4
  57. package/dist/src/store.js +211 -8
  58. package/dist/src/types.d.ts +61 -17
  59. package/dist/src/util.js +4 -1
  60. package/docs/authoring.md +145 -8
  61. package/docs/bundles.md +19 -0
  62. package/docs/cli.md +270 -30
  63. package/docs/crypto.md +13 -7
  64. package/docs/design.md +107 -46
  65. package/docs/evals/mcp-charter-baseline.json +428 -0
  66. package/docs/mcp-charter-eval.md +124 -0
  67. package/docs/shift-logs.md +18 -0
  68. package/docs/wire-contracts.md +28 -7
  69. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  70. package/examples/workflows/ship.yaml +28 -2
  71. package/package.json +2 -1
  72. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  73. package/plugins/claude-code/plugin/.mcp.json +1 -1
  74. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  75. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  76. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  77. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  81. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  82. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  83. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/docs/cli.md CHANGED
@@ -4,9 +4,14 @@ The `owenloop` binary is a thin adapter over the engine: it maps `argv` to
4
4
  engine calls and prints JSON to stdout. Everything here has a typed,
5
5
  in-process equivalent — see [`docs/embedding.md`](embedding.md).
6
6
 
7
- Global flags: `--db <path>` (env `OWENLOOP_DB`, default `.owenloop/state.db`) and
8
- `--defs <dir>` (env `OWENLOOP_DEFS`, default `./workflows`). Nothing is
9
- remembered between invocations — pass both on every command. Opening the
7
+ Global flags: `--db <path>` (env `OWENLOOP_DB`, default `.owenloop/state.db`),
8
+ `--defs <dir>` (env `OWENLOOP_DEFS`, default `./workflows`), and `--verbose`.
9
+ Nothing is remembered between invocations — pass them on every command.
10
+ `--verbose` restores the detailed notice for every superseded bundle workflow;
11
+ without it, discovery emits at most one summary note such as
12
+ `note: 3 superseded bundle versions hidden; --verbose to list them`. The
13
+ actionable `has no selectable version` warning for competing non-SemVer bundle
14
+ versions remains unconditional. Opening the
10
15
  **default** db path refuses a symlinked `.owenloop` directory — and a symlinked
11
16
  `state.db` file (or any of its SQLite `-wal`/`-shm`/`-journal` sidecars) inside
12
17
  a real `.owenloop` — rather than following it (filesystem-isolation guard
@@ -22,7 +27,7 @@ prints this usage and exits 0 without doing any work.
22
27
 
23
28
  Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
24
29
  `--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
25
- `--strict-inputs`, `--unsigned`, and the bare `--now` on `reap`) never take a
30
+ `--strict-inputs`, `--unsigned`, `--verbose`, `--yes`, and the bare `--now` on `reap`) never take a
26
31
  following value — the next token is always a positional or the next `--flag`,
27
32
  never consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>`
28
33
  on `tick`) for flags that do take a value.
@@ -38,6 +43,19 @@ both flags are passed, `--strict-inputs` wins. See
38
43
  [`docs/design.md` §25](design.md#25-the-model-checker-owenloop-check--scope)
39
44
  for the full breakdown.
40
45
 
46
+ Before `check` runs the model, it and `lint` validate cross-definition
47
+ `calls:` edges: a missing child, an undeclared mapped child input, a child with
48
+ zero or multiple outputs, and every member of a calls cycle are hard errors.
49
+ The lint JSON keeps those errors on the calling definition (and on every cycle
50
+ member); `check` presents them in its existing validation-error message.
51
+
52
+ Collection searches use `--max-collection N` to limit each `emit`/`seal` fork to
53
+ 0 through N members (the default is 2). When the search actually expands a
54
+ reachable collection fork, text output prints a separate `COLLECTION CAP
55
+ APPLIED` caveat naming the flag and effective value. JSON output exposes the
56
+ same information as `collectionCapApplied` and `maxCollectionSize`; the marker
57
+ is independent of the `SEARCH INCOMPLETE` bounds notice.
58
+
41
59
  ## Commands
42
60
 
43
61
  | command | what it does |
@@ -50,10 +68,13 @@ for the full breakdown.
50
68
  | `bundle unpack <bundle.wnlp> <destination-dir>` | strictly validate and atomically extract a `.wnlp` package — see [Bundles](#bundles) |
51
69
  | `bundle inspect <bundle.wnlp>` | strictly validate a `.wnlp` package and print its manifest and file metadata — see [Bundles](#bundles) |
52
70
  | `bundle digest <bundle.wnlp>` | print the SHA-256 digest of the uncompressed canonical tar — see [Bundles](#bundles) |
71
+ | `bundle gc [--keep <n>] [--global] [--yes]` | dry-run or collect unreachable bundle-store objects — see [Bundles](#bundles) |
53
72
  | `login [--hub <url>] [--with-token] [--as <slot>]` | authenticate the CLI against a hub — loopback OAuth, or `--with-token` from stdin — see [Hub](#hub-login--connect--push--logout) |
54
73
  | `connect [--hub <url>] [--as <slot>]` | verify a resolved hub credential and record an optional per-project override in `.owenloop/hub.json` |
55
- | `push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <url>] [--as <slot>]` | publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (idempotent against the hub's own def hashes) |
74
+ | `push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--map <authored>=<org>] [--dry-run] [--hub <url>] [--as <slot>]` | publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (idempotent against the hub's own def hashes) |
75
+ | `install <owner>/<repo>[@ref] [<defName>...] [--map <authored>=<org>] [--accept-defaults] [--dry-run] [--hub <url>] [--as <slot>]` | publish an OUTSIDE repo's defs to your hub under SCOPED capabilities (`<defName>.<capability>` by default) — records the mapping BEFORE it publishes, and never writes into local `workflows/` — see below |
56
76
  | `start <defName> [--provide name=json …] [--crew <name>] [--title <text>] [--modifier <name>] [--scope <label>] [--priority <low\|normal\|high>] [--hub <url>]` | start a published workflow on the bound hub with the human credential |
77
+ | `pending-gates --hub <url>` | list human-input gates currently blocking hub-hosted workflows; there is no local-engine form |
57
78
  | `publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <url>]` | pack a canonical workflow bundle and publish a signed publication sidecar, with an optional signed origin sidecar, or an explicitly unsigned marker |
58
79
  | `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
59
80
  | `agent new <name> [--crews <a,b>] [--scopes <a,b>] [--shift] [--hub <url>]` | mint a new Scoped Identity on the hub and store its token in slot `agent:<name>` — the token is never printed; `--shift` = `--scopes work,run` — see [Hub](#hub-login--connect--push--logout) |
@@ -86,7 +107,7 @@ for the full breakdown.
86
107
  | `util modifier-init --default <value>` | choose a modifier from rejection feedback, the order hint, or a default; intended for command steps |
87
108
  | `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
88
109
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
89
- | `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
110
+ | `provide <wf> <name> [--value json] [--hub <url>]` | supply a seeded input after the fact; `--hub` targets a hosted workflow |
90
111
  | `tick <wf> [--now=<ms>] [--shallow] [--capability <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--capability` claims steps without capabilities plus matching-capability steps — see below |
91
112
  | `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
92
113
  | `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
@@ -97,7 +118,7 @@ for the full breakdown.
97
118
  | `green <wf> <run> <path> [--value json] [--terminal]` | accept an owed output |
98
119
  | `emit <wf> <run> --items '[{…},{…}]'` | add collection elements |
99
120
  | `seal <wf> <run> [--value json]` | mark a collection complete |
100
- | `reject <wf> <path> --by <author> --text <msg>` | reject an output (re-arms its producer) |
121
+ | `reject <wf> <path> --by <author> --text <msg> [--requested <modifier>] [--hub <url>]` | reject an output (re-arms its producer); `--hub` targets a hosted workflow |
101
122
  | `retract <wf> <path> --by <author> --text <msg>` | drop a collection member |
102
123
  | `skip <wf> <path> --by <author> --text <msg>` | a step declines its own output |
103
124
  | `retry <wf> <path> [--by a] [--text guidance] [--hub <url>]` | clear a stall and reset the counter, or answer an `ask` — `--hub` targets a hub-hosted run |
@@ -105,10 +126,27 @@ for the full breakdown.
105
126
  | `delete <wf>` | delete an instance and all its rows |
106
127
  | `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
107
128
 
129
+ Without `--hub`, `provide` and `reject` use the local SQLite engine exactly as
130
+ before. With `--hub`, they operate on the project-bound (or explicitly named)
131
+ hosted workflow and use the logged-in human credential; the explicit hub must
132
+ agree with an existing project binding. Hosted `reject` maps `--text` to the
133
+ hub's `reason`, forwards `--requested` when supplied, and does not accept
134
+ caller-controlled `--by` because the hub attributes the rejection to the
135
+ authenticated human. Hosted `provide` sends the input identifier as `name`.
136
+
137
+ Hosted workflow IDs must be `wf_` followed by exactly 24 lowercase hexadecimal
138
+ characters. The CLI rejects malformed IDs before resolving the hub, reading
139
+ credentials, or making a request for `cancel`, the `--hub` forms of `retry`,
140
+ `reject`, and `provide`, `instance show`, and `routing show`. Local
141
+ `provide`/`reject`/`retry` retain their SQLite behavior. Local `show` first
142
+ checks that the workflow instance exists: an existing instance with no
143
+ artifacts prints `[]`, while an unknown well-formed ID fails with
144
+ `no such workflow instance: <id>`.
145
+
108
146
  ## Bundles
109
147
 
110
- Bundle commands are deliberately dispatched before the CLI opens the engine
111
- store. `bundle pack`, `bundle inspect`, `bundle digest`, and `bundle unpack`
148
+ The package-format commands are deliberately dispatched before the CLI opens
149
+ the engine store. `bundle pack`, `bundle inspect`, `bundle digest`, and `bundle unpack`
112
150
  read or write only the paths named by the command; they do not create
113
151
  `.owenloop/state.db`, contact a remote coordinator, or use workflow definitions
114
152
  from `--defs`. Successful commands print one JSON object on stdout. Failures
@@ -119,8 +157,60 @@ owenloop bundle pack <source-dir> [--output <bundle.wnlp>]
119
157
  owenloop bundle unpack <bundle.wnlp> <destination-dir>
120
158
  owenloop bundle inspect <bundle.wnlp>
121
159
  owenloop bundle digest <bundle.wnlp>
160
+ owenloop bundle gc [--keep <n>] [--global] [--yes]
122
161
  ```
123
162
 
163
+ `bundle gc` is intentionally different from the four format commands: it reads
164
+ the selected content-addressed store plus the local runtime database's retained
165
+ definition snapshots. The project store under `--defs`/`OWENLOOP_DEFS` is the
166
+ default target; `--global` targets only `<home>/.owenloop/workflows` and cannot
167
+ be combined with a defs override. The other store may be read to establish
168
+ reachability. An applied run acquires both roots' writer locks in canonical
169
+ order, so installs cannot enter either side of the scan-to-delete window. Only
170
+ the selected root's bundle index and object tree are changed; coordinating with
171
+ a known but not-yet-created counterpart root may create its `.owenloop` lock
172
+ state so a concurrent first install uses the same lock. Project GC additionally
173
+ takes the legacy GitHub-add lock and recovers its separate journal before
174
+ clearing the staging tree those install routes share. Global GC takes that lock
175
+ as a read barrier while discovering project/add definition reachability, but
176
+ refuses a pending project journal rather than mutating the non-target project
177
+ tree. GC never contacts the hub.
178
+
179
+ GC is a pure dry run unless `--yes` is present. A dry run does not create a
180
+ missing store root, runtime database, lock, journal, or staging directory.
181
+ `--keep` is a positive integer and defaults to `2`: the selected/current version
182
+ plus one immediate rollback version, bounding history without eliminating the
183
+ cheapest fallback. The deterministic JSON report contains `ok`, `dryRun`,
184
+ `level`, `root`, `keep`, `count`, `bytes`, sorted `coordinates`, and sorted
185
+ `objects` with each digest's logical regular-file byte total and coordinates.
186
+ An unchanged `--yes` run reports the same candidates as its preceding dry run.
187
+
188
+ The collector protects every cross-root selected winner, the best `--keep`
189
+ versions of each qualified workflow, explicit index pins, every bundle digest
190
+ and lock dependency in retained local workflow snapshots, exact versioned
191
+ `calls:` edges in retained filesystem/add/legacy snapshots and currently
192
+ loadable non-CAS project/add definitions, and the exact coordinate+digest
193
+ dependency closure of every retained bundle in either index.
194
+ Project-to-global fallback is preserved. Protection is root-scoped: a complete
195
+ non-target coordinate/object copy can satisfy an exact edge without keeping a
196
+ redundant target copy, so `--keep` still bounds identical histories installed
197
+ in both roots. An all-non-SemVer candidate group is kept in full rather than
198
+ given an invented order. Multi-workflow bundles and multiple coordinates for
199
+ one digest are retained or collected atomically. Malformed indexes, objects,
200
+ links, special files, or snapshots fail closed before deletion.
201
+
202
+ Runtime snapshot writers share the relevant store writer locks and revalidate
203
+ CAS reachability before beginning SQLite. Store roots are guarded before lock
204
+ state is created, so a symlinked global parent cannot redirect coordination
205
+ writes. Bundle installs revalidate every
206
+ manifest lock against the combined store after taking their root lock and before
207
+ commit. GC therefore either observes a committed caller/pin, or a stale writer
208
+ is refused after collection and must reload. On filesystems that require a
209
+ temporary owner-write bit to move a hardened object, GC persists an
210
+ index-correlated journal first; all writers recover that journal before shared
211
+ staging cleanup, and the rename's source and destination parents are fsynced
212
+ before the evidence is cleared.
213
+
124
214
  `pack` requires a source directory containing root `bundle.yaml` and every
125
215
  workflow path listed by the manifest's `workflows` map. The source manifest is
126
216
  not modified. If `--output` is omitted,
@@ -223,6 +313,16 @@ one loop sweep and exits instead of keeping the foreground daemon running.
223
313
  | `--work-root <dir>` | **repeatable.** restrict this machine to orders whose working directory is inside one of these roots; precedence is the flags, then `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (a `:`-separated list), then `settings.allowedWorkdirRoots`. Each rung REPLACES the one below it rather than extending it. No rung set anywhere ⇒ **no restriction**, which is the default |
224
314
  | `--log-max-age <ms>` | worker-log retention, swept once at startup; precedence is flag, then `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, then `settings.shiftLogMaxAgeMs`, then `1209600000` (14 days). `0` reaps every completed run's log at the next startup; there is no value that disables the sweep, and `shift.log` is never reaped |
225
315
 
316
+ **Capacity re-offer damping.** When a `dispatch-cap-full` or `agent-cap-full`
317
+ claim is returned immediately, the shift suppresses targeted `whats_next` for
318
+ that workflow and stable step (workflow, step, and fan-out key) for a fixed
319
+ 30-second monotonic cooldown. A fresh hub run id does not bypass the cooldown.
320
+ The shift retries sooner when the relevant capacity returns: any total slot
321
+ for `dispatch-cap-full`, or room in the agent lane for `agent-cap-full`.
322
+ Untargeted inbox polling and sibling workflows continue, but command work in a
323
+ cooled workflow can wait until its cooldown expires. This shift-local damper
324
+ is separate from `--local-queue-hold` and from server `Retry-After` backoff.
325
+
226
326
  **On-disk logs.** A running shift appends its dispatch record to
227
327
  `<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
228
328
  and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
@@ -665,11 +765,11 @@ separate concern.
665
765
  `owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
666
766
  `workflows/**` folder (via GitHub's REST API and Node's built-in `fetch` — no
667
767
  new dependency), validates every def with the same lint/validate/`check`
668
- machinery `owenloop lint`/`owenloop check` use — plus a strict cross-def
669
- backstop (include expansion, `calls:` target/inputs/output-count checks,
670
- cycle detection) on the staged tree, so an error `loadDefsRaw` would
671
- otherwise swallow still refuses the install — and only then installs them
672
- under `<defsDir>/<owner>-<repo>-<hash>/`, where `<hash>` is the first 8 hex
768
+ machinery `owenloop lint`/`owenloop check` use. Those authoring commands now
769
+ also report invalid cross-definition `calls:` edges. `add` retains a strict
770
+ whole-staged-tree backstop for include expansion and final load validation, so
771
+ any remaining tolerant raw-loader failure still refuses the install — and only
772
+ then installs them under `<defsDir>/<owner>-<repo>-<hash>/`, where `<hash>` is the first 8 hex
673
773
  characters of `sha256(owner/repo)`. The hash keeps distinct sources that used
674
774
  to collide on the same `<owner>-<repo>` folder (e.g. `a-b/c` and `a/b-c`)
675
775
  from clobbering each other. `owner` and `repo` are restricted to the
@@ -813,16 +913,25 @@ defs dir is guarded only on the default `cwd/workflows` fallback — an explicit
813
913
  matching the `--db`/`OWENLOOP_DB` rule above.
814
914
 
815
915
  **Installed-def discovery.** Defs installed by `add` are discovered by default:
816
- a plain `owenloop defs`/`create`/`tick` against the DEFAULT defs dir
916
+ a plain `owenloop defs`/`lint`/`check`/`create`/`tick` against the DEFAULT defs dir
817
917
  (`cwd/workflows`) sees them by name, no `--defs` flag needed. `loadDefs` itself
818
918
  stays a pure dir-scanner (top-level `*.yaml` plus immediate-subdir
819
919
  `workflow.yaml`); the CLI folds installed subfolders in on top, ledger-driven and
820
920
  bounded — it only loads folders named by the fail-closed-validated
821
921
  `.owenloop/installed.json` entries, never a raw recurse of the tree.
822
922
 
923
+ **Definition listing.** The default JSON from `owenloop defs` retains each
924
+ definition's `name`, nullable `title`, ordered input-name `inputs`, and ordered
925
+ `steps`. It additively includes ordered `inputSchemas` entries (always `name`,
926
+ with complete `schema` when declared) and a present-only opaque `x` extension
927
+ bag. Schemas and extension bags are returned in full, never truncated; the
928
+ larger default terminal payload is the intentional tradeoff for making this the
929
+ discovery surface without requiring prior knowledge of a flag.
930
+
823
931
  - **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
824
932
  operator intent to target a literal dir and keeps the pure-scan behavior with
825
- no installed-def or CAS-store fold-in — the rule is "was an override given",
933
+ no installed-def or CAS-store fold-in for `defs`, `lint`, `check`, and runtime
934
+ commands — the rule is "was an override given",
826
935
  so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
827
936
  Pointing `--defs` straight at an install folder
828
937
  (`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
@@ -833,9 +942,12 @@ bounded — it only loads folders named by the fail-closed-validated
833
942
  - **Fail-open.** The fold-in never breaks base loading. A corrupt or
834
943
  structurally-invalid `installed.json`, a missing install folder, or an install
835
944
  folder that fails to load each emits a `warning:` on stderr and is skipped;
836
- your project defs still load and the command still exits 0. The add-time
837
- fail-closed lockfile validation is unchanged — discovery consumes it and simply
838
- refuses to act on a bad ledger rather than crashing.
945
+ your project defs still load and commands still exit 0, except that directory
946
+ `lint` exits 1 when it reports a failed installed-folder load. A malformed or
947
+ duplicate definition skips its entire installed folder for both authoring and
948
+ executable discovery; directory `lint` also reports that folder as a failed
949
+ load. The add-time fail-closed lockfile validation is unchanged — discovery
950
+ consumes it and simply refuses to act on a bad ledger rather than crashing.
839
951
 
840
952
  Public repos only — no auth/token support yet; a private repo (or a bad
841
953
  ref) surfaces as a 404 from the sha-resolve step.
@@ -1565,6 +1677,14 @@ stream cancelled) rather than buffered, closing the same memory-exhaustion gap
1565
1677
  on the hub path that the `add` download cap closes on the archive path.
1566
1678
  `OWENLOOP_HUB_MAX_RESPONSE_BYTES` overrides the cap (a test knob).
1567
1679
 
1680
+ **Authentication failures.** On the credential-verification and shared
1681
+ authenticated-read paths, a `401` keeps its credential-specific message, while
1682
+ a `429` is reported as `rate limited by the hub`. When the hub sends a
1683
+ `Retry-After` header, the CLI appends ` (retry after VALUE)`; it does not parse
1684
+ the value or sleep automatically. Other non-2xx responses keep the generic
1685
+ status-bearing hub-rejected message. Login verifies before storing, so a failed
1686
+ verification — including a `429` — never writes the credential.
1687
+
1568
1688
  ### `login` — authenticate the CLI against a hub
1569
1689
 
1570
1690
  Two ways to get a credential, both of which **verify before storing** (a token
@@ -1842,6 +1962,18 @@ On a `401`, an OAuth credential is refreshed once and the request retried; an
1842
1962
  agent (`olp_`) token has no refresh path, so a `401` is a hard "re-mint it"
1843
1963
  error.
1844
1964
 
1965
+ **`--map <authored>=<org>`** (repeatable) records a capability mapping for the
1966
+ defs being pushed, before any of them is published. It is the same mechanism
1967
+ [`install`](#install--publish-an-outside-repos-defs-under-scoped-capabilities)
1968
+ uses, exposed here for the case where an org-authored def's capability should
1969
+ resolve to a different org name — `push` itself scopes nothing, because a def
1970
+ you authored is already in your org's vocabulary. Only the non-identity entries
1971
+ a given def actually authors are written for it; a `--map` naming a capability
1972
+ no selected def authors is an error. Because the write precedes the publish, a
1973
+ hub with no mapping writer fails the push with nothing sent (exit 2), and no
1974
+ shipped hub implements that write yet — so `--map` is currently a
1975
+ fail-closed declaration of intent.
1976
+
1845
1977
  **Include and bodyFile limitations.** A def whose file uses `include:` is
1846
1978
  refused (`uses include:, not hub-pushable`): the hub's `create_workflow`
1847
1979
  parses the raw YAML without include expansion, and a re-serialized expanded
@@ -1850,6 +1982,73 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
1850
1982
  resolve the external file against once the YAML leaves this machine. Inline
1851
1983
  both before pushing.
1852
1984
 
1985
+ ### `install` — publish an outside repo's defs under scoped capabilities
1986
+
1987
+ ```text
1988
+ owenloop install <owner>/<repo>[@ref] [<defName>...] [--map <authored>=<org>] [--accept-defaults] [--dry-run] [--hub <origin>] [--as <slot>]
1989
+ ```
1990
+
1991
+ `install` is a **sibling of [`push`](#push--publish-local-defs-to-the-resolved-hub), not of [`add`](#add--installing-shared-workflow-defs-from-github)**. It
1992
+ publishes to your hub. It never writes into the local `workflows/` directory —
1993
+ `add` owns local installation, with its install lock, crash journal and atomic
1994
+ swap, and duplicating that here would be a second implementation of the same
1995
+ transaction. The outside repo is materialized into a temp directory, used, and
1996
+ deleted.
1997
+
1998
+ **Sources.** Only `owner/repo[@ref]` (a public GitHub repo) is an install source
1999
+ today. A local `.wnlp` bundle or an `http(s)` URL is refused, naming the two
2000
+ commands that do cover it: `owenloop add <source>` to install into the local
2001
+ store, then `owenloop push --bundle <bundle.wnlp>` to publish it.
2002
+
2003
+ **Capabilities are scoped by default.** `push` publishes defs you authored, so
2004
+ their capabilities join your org's shared vocabulary as written. A def from an
2005
+ unrelated author making the same claim is not the same claim, so every
2006
+ capability an installed def authors becomes `<defName>.<capability>` —
2007
+ `analyzer.review`, not `review`. A def name can never contain a dot and the def
2008
+ parser reserves only `:`, so the dot splits the two halves unambiguously and
2009
+ needs no new separator or escaping. The def's content is never edited: the
2010
+ mapping is org-side data recorded against `(def, authored-name)` on the hub, so
2011
+ upstream updates keep applying.
2012
+
2013
+ **Deciding the vocabulary,** highest precedence first: `--map <authored>=<org>`
2014
+ (repeatable); a mapping this hub already holds for that def, carried forward
2015
+ unchanged; `--accept-defaults`, which takes the scoped name for everything;
2016
+ otherwise one prompt per capability, prefilled with the scoped name, printed
2017
+ after the org's live vocabulary so a decision to link is an informed one. A
2018
+ `--map` naming a capability no selected def authors is an error, never a silent
2019
+ no-op. A mapping target containing `:` is refused — that suffix position is
2020
+ reserved for the run modifier the engine composes at offer time.
2021
+
2022
+ **The non-interactive guard fires before the first hub request.** A piped run
2023
+ with neither `--map` nor `--accept-defaults` exits 1 naming both flags, with an
2024
+ empty request log — never after a mapping read has already happened.
2025
+
2026
+ **Record, then publish, and that ordering is the point.** Publishing first would
2027
+ put an unscoped third-party def into your org's vocabulary for the window
2028
+ between the two calls — exactly the trust-boundary breach this verb exists to
2029
+ prevent. A hub that cannot record the mapping therefore fails the command with
2030
+ **nothing published**. Identity entries are skipped (the hub's resolver drops
2031
+ them anyway), as are entries the hub already holds.
2032
+
2033
+ **No shipped hub implements the mapping write yet.** Until one does, only the
2034
+ identity case completes end to end — where every capability keeps its authored
2035
+ name there is nothing to record, so the write is skipped and the publish
2036
+ proceeds. Every other case stops at the missing verb with exit 2, before any
2037
+ `create_workflow` call.
2038
+
2039
+ Everything downstream of the mapping is `push`'s machinery, unchanged: the same
2040
+ all-or-nothing lint/validate/`check` gate across every selected def, the same
2041
+ `GET /api/workflows` server diff, the same topological `calls:` ordering with
2042
+ dependency skips, the same `401` refresh-once and `429` batch halt. `--dry-run`
2043
+ reports `mapped` and `wouldRecord` alongside the usual plan and writes nothing.
2044
+ stdout is machine-parseable JSON; the mapping decisions, the diff, and the hub's
2045
+ capability report go to stderr.
2046
+
2047
+ Exit codes: 0 ok; 1 a runtime or hub error (a validation-gate refusal, a per-def
2048
+ rejection, a refused source kind, an invalid `--map`, or a credential the hub
2049
+ rejects after its one refresh — as in `push`); 2 the hub is unresolvable or does
2050
+ not implement the mapping write; 3 no credential is stored for the slot.
2051
+
1853
2052
  ### `publish` — pack and publish a workflow bundle
1854
2053
 
1855
2054
  ```text
@@ -2835,6 +3034,14 @@ inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into
2835
3034
  which **mints** a new credential directly and therefore stops rather than
2836
3035
  ever guessing — a wrong guess there is a side effect a retry cannot undo.
2837
3036
 
3037
+ For `create_workflow {ephemeral:true}`, the proxy first completes authenticated,
3038
+ non-mutating remote MCP initialization (`initialize`,
3039
+ `notifications/initialized`, then `tools/list`) using the negotiated protocol
3040
+ version and any returned session id. It forwards the create only when the
3041
+ selected hub itself advertises `create_workflow.ephemeral`,
3042
+ `list_workflows.include_ephemeral`, and `delete_workflow`; a proxy-local schema
3043
+ or a 200 inclusive listing is not sufficient evidence.
3044
+
2838
3045
  **`~/.owenloop/config.json`** is written by
2839
3046
  [`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
2840
3047
  JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
@@ -2847,25 +3054,58 @@ like every other command — an explicit bad value is reported, never silently
2847
3054
  skipped, precisely because rungs 1–2 come from something the operator typed
2848
3055
  or set, not from inference.
2849
3056
 
3057
+ ### Chief-of-staff guidance
3058
+
3059
+ The `initialize` result includes an `instructions` string for MCP hosts. It
3060
+ sets the expected operating posture for the control plane: act as the human's
3061
+ chief of staff, inspect the complete workflow catalog before doing multi-step
3062
+ work, and start a fitting playbook so its crews can execute. Inline step work is
3063
+ appropriate only when no available crew serves the required capability.
3064
+
3065
+ After a run starts or is attended, an MCP client should park on `wake` and call
3066
+ `whats_next` when the returned cursor changes (or when a workflow needs a tick
3067
+ or the human asks for an inbox). The client relays gates, worker asks, receipts,
3068
+ and status to the human; `provide_input` carries human gate answers and
3069
+ `retry_artifact` carries answers to worker `ask` escalations. Rejection is
3070
+ feedback to surface and resolve, not a route to bypass: use `reject_artifact`
3071
+ only for a real upstream defect with a concrete reason.
3072
+
3073
+ The opt-in [MCP chief-of-staff charter evaluation](mcp-charter-eval.md)
3074
+ measures that guidance from structured MCP calls. The current
3075
+ [two-harness baseline](evals/mcp-charter-baseline.json) records the attributable
3076
+ scores, ordered calls, and response evidence. A baseline is replaced only after
3077
+ both credentialed harnesses complete scoreably; it is never fabricated from an
3078
+ incomplete run. The evaluation is quota-spending and not part of required CI.
3079
+
2850
3080
  ### Tools
2851
3081
 
2852
- The server exposes 20 baseline tools mirroring the hub's own MCP toolset, plus
3082
+ The server exposes 23 baseline tools mirroring the hub's own MCP toolset, plus
2853
3083
  `create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
2854
3084
  `add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
2855
- toolset. Each baseline tool's result is the hub REST response as one text
2856
- block; a non-2xx response comes back as an error result.
3085
+ toolset. Each baseline tool's result is the hub REST response unchanged as one
3086
+ text block; a non-2xx response comes back as an error result. The
3087
+ `pending-gates` CLI command likewise prints the hub response unchanged.
3088
+
3089
+ Every `tools/call` validates its arguments against the input schema advertised
3090
+ by `tools/list` before the tool handler runs. An omitted `arguments` member is
3091
+ treated as `{}`; when supplied, `arguments` must be an object and must satisfy
3092
+ the registered schema. A mismatch returns JSON-RPC `-32602` (`INVALID_PARAMS`)
3093
+ and makes no hub request.
2857
3094
 
2858
3095
  | tool | what it does |
2859
3096
  |---|---|
2860
3097
  | `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances; optional `serve_capabilities` accepts raw advertised keys |
2861
- | `submit` | submit a work order output |
2862
- | `reject_artifact` | send an upstream artifact back to its producer with a reason |
2863
- | `retry_artifact` | re-arm a stalled or rejected artifact to owed — the human stall-clear, and the answer path for a worker's `ask` |
2864
- | `provide_input` | answer a human gate — provide a value for a seeded/owed input |
2865
- | `start_run` | create a new instance from a definition name; optional `scope` (free routing label, defaults to the session's repo name) and `priority` (`low\|normal\|high`) |
2866
- | `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
2867
- | `get_workflow` | fetch one loaded definition |
2868
- | `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
3098
+ | `pending_gates` | find gates waiting on a human — owed inputs no worker can supply; query after starting or attending runs, or when a human asks what needs attention; optional `serve_crews` narrows the list |
3099
+ | `submit` | return an owed work-order output from a crew member or held-order holder; not a way for a chief of staff to fabricate inline progress |
3100
+ | `reject_artifact` | send a real upstream defect back to its producer with a concrete reason; optional `requested` carries the replacement modifier requested from the producer |
3101
+ | `retry_artifact` | re-arm a stalled or rejected artifact to owed — the human stall-clear, and the answer path for a worker's `ask`; it must not bypass unresolved rejection feedback |
3102
+ | `provide_input` | relay a human answer into a seeded/owed gate |
3103
+ | `start_run` | start a fitting multi-step playbook and let its crews execute; optional `scope` (free routing label, defaults to the session's repo name) and `priority` (`low\|normal\|high`) |
3104
+ | `create_workflow` | parse + load a workflow def YAML when no catalog entry fits and the human chooses authoring; optional `bundle_digest` identifies the content-addressed bundle for reference orders; optional `ephemeral` publishes a retireable one-off only after remote-hub capability attestation |
3105
+ | `get_workflow` | inspect a promising loaded definition before selecting it |
3106
+ | `list_workflows` | discover published workflow definitions and decide which one fits a task; optional `include_ephemeral` includes definitions hidden from the default catalog |
3107
+ | `search_workflows` | context-smaller ranked read of the same published catalog when it is too large to read whole or the host cannot spend the full-list context; requires string `query`, accepts optional positive-integer `limit` and boolean `include_ephemeral`, and returns flattened ranked `{ text, results }`; for smaller catalogs (roughly below 75 definitions), the full listing can support better selection |
3108
+ | `delete_workflow` | retire an ephemeral workflow's live name; the hub refuses while an active root references its exact pinned definition closure |
2869
3109
  | `get_status` | `engine.status` verbatim plus a plain-English rendering |
2870
3110
  | `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
2871
3111
  | `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
package/docs/crypto.md CHANGED
@@ -174,13 +174,19 @@ consumer passes to `verifyConsumed` as `expectedVersion`. It is never inferred
174
174
  from process-local state.
175
175
 
176
176
  Retry-safety is a property of where the target is computed, not of the client.
177
- The engine computes it inside the claim transaction and persists it with the
178
- immutable order, so every read of that claim — a reconnect, a retried submit
179
- after a lost response, a restarted holder — yields the same number. Engine
180
- refusal paths that leave the run open (a schema reject) do not bump the
181
- artifact, so the target survives in-claim retries; a refinement is a new claim
182
- and receives a newly issued target. A stale target fails the consumer's version
183
- check, which is a refusal, never an admitted unverified value.
177
+ The engine issues it inside the claim transaction and persists it with the
178
+ order, so a reconnect, a retried submit after a lost response, or a restarted
179
+ holder re-reads the issued number instead of guessing one; a refinement is a new
180
+ claim and receives a newly issued target.
181
+
182
+ The target is not frozen for the life of the claim. A refusal that leaves the
183
+ run open without bumping the artifact (a schema reject) leaves it correct, but a
184
+ judgment or human reject follows a commit that already bumped the artifact and
185
+ leaves the same claim live to retry — so the engine re-stamps that claim's
186
+ target from the current committed version at the reject site. A client must
187
+ therefore re-read `owes[].version` off the order on every submit and never cache
188
+ it across a reject. A stale target fails the consumer's version check, which is
189
+ a refusal, never an admitted unverified value.
184
190
 
185
191
  A target is authoritative only when it is a positive integer: the smallest
186
192
  commit any producer can land is v1. An absent target, a `0`, or a non-integer